Documentation gives incorrect advice for making patches RFC-6902 compliant

[uckelman]

🐛 Bug Report

The patches documentation says

The generated patches are similar (but not the same) to the RFC-6902 JSON patch standard, except that the path property is an array, rather than a string. This makes processing patches easier. If you want to normalize to the official specification, patch.path = patch.path.join("/") should do the trick.

The advice for making the patches RFC-6920 compliant is incorrect. The suggested adjustment, patch.path.join("/"), will never return a path string with a leading /.

RFC-6902 requires the path to be a JSON Pointer, defined in RFC-6901. The grammar in RFC-6901 §3 defines a json-pointer token as follows:

 json-pointer    = *( "/" reference-token )

Thus, the only json-pointer which does not start with / is the empty string.

The suggestion in the docs produces non-compliant paths such as a/b/c (instead of /a/b/c).

Link to repro

See next section.

To Reproduce

const path = ['a'];
console.log(path.join("/"));

Observed behavior

a

Expected behavior

/a

Obviously we don't expect join() to produce this, but rather we expect the docs to suggest code which would.

Environment

Any environment you want---this is how join() works.

• Immer version:
• [x] I filed this report against the latest version of Immer
• [x] Occurs with setUseProxies(true)
• [x] Occurs with setUseProxies(false) (ES5 only)