docs: update mentions of formatters and code blocks

Author: benjamine

README.md

@@ -24,15 +24,14 @@
 - min+gzipped ~ 16KB
 - browser and server (ESM-only)
 - deep diff, use delta to patch
-- (optionally) uses [google-diff-match-patch](http://code.google.com/p/google-diff-match-patch/) for long text diffs (diff at character level)
 - smart array diffing using [LCS](http://en.wikipedia.org/wiki/Longest_common_subsequence_problem), **_IMPORTANT NOTE:_** to match objects inside an array you must provide an `objectHash` function (this is how objects are matched, otherwise a dumb match by position is used). For more details, check [Array diff documentation](docs/arrays.md)
+- (optionally) text diffing of long strings powered by [google-diff-match-patch](http://code.google.com/p/google-diff-match-patch/) (diff at character level)
 - reverse a delta, unpatch (eg. revert object to its original state using a delta)
-- simplistic, pure JSON, low footprint [delta format](docs/deltas.md)
-- multiple output formatters:
-  - html (check it at the [Live Demo](https://jsondiffpatch.com))
-  - annotated json (html), makes the JSON delta format self-explained
+- multiple output formats:
+  - pure JSON, low footprint [delta format](docs/deltas.md)
+  - annotated JSON (html), to help explain the format with annotations
+  - JSON Patch ([RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902)), can generate patches, and also apply them
   - console (colored), try running `./node_modules/.bin/jsondiffpatch left.json right.json`
-  - JSON Patch format RFC 6902 support
   - write your own! check [Formatters documentation](docs/formatters.md)
 - BONUS: `jsondiffpatch.clone(obj)` (deep clone)
 
@@ -53,8 +52,7 @@ npx jsondiffpatch https://jsondiffpatch.com/demo/left.json https://jsondiffpatch
 
 or as a library:
 
-```javascript
-// sample data
+```ts// sample data
 const country = {
   name: 'Argentina',
   capital: 'Buenos Aires',
@@ -92,8 +90,7 @@ assert(delta2 === undefined);
 
 Array diffing:
 
-```javascript
-// sample data
+```ts// sample data
 const country = {
   name: 'Argentina',
   cities: [
@@ -202,8 +199,7 @@ In a browser, you can load a bundle using a tool like [esm.sh](https://esm.sh) o
 
 ## Options
 
-```javascript
-import * as jsondiffpatch from 'jsondiffpatch';
+```tsimport * as jsondiffpatch from 'jsondiffpatch';
 
 // Only import if you want text diffs using diff-match-patch
 import DiffMatchPatch from 'diff-match-patch';

demos/html-demo/index.html

@@ -400,12 +400,17 @@ <h2>Features</h2>
           plain text
         </li>
         <li>
-          json diff as visual diff or json (see
+          output visual diff, json (see
           <a
             href="https://github.com/benjamine/jsondiffpatch/blob/master/docs/deltas.md"
             rel="nofollow"
             target="_blank"
             >delta format</a
+          >), or json patch (<a
+            href="https://datatracker.ietf.org/doc/html/rfc6902"
+            target="_blank"
+            rel="nofollow"
+            >RFC 6902</a
           >)
         </li>
         <li>

docs/arrays.md

@@ -22,8 +22,8 @@ To improve the results leveraging the power of LCS (and position move detection)
 
 ### An example using objectHash
 
-```javascript
-var delta = jsondiffpatch
+```ts
+const delta = jsondiffpatch
   .create({
     objectHash: function (obj, index) {
       // try to find an id property, otherwise just use the index in the array
@@ -47,8 +47,8 @@ This introduces a few benefits:
 
 moves are detected by default, you can turn move detection off with:
 
-```javascript
-var customDiffPatch = jsondiffpatch.create({
+```ts
+const customDiffPatch = jsondiffpatch.create({
   arrays: {
     detectMove: false,
   },

docs/deltas.md

@@ -16,23 +16,23 @@ Here's a complete reference of this format.
 
 a value was added, i.e. it was `undefined` and now has a value.
 
-```javascript
+```ts
 delta = [newValue];
 ```
 
 ## Modified
 
 a value was replaced by another value
 
-```javascript
+```ts
 delta = [oldValue, newValue];
 ```
 
 ## Deleted
 
 a value was deleted, i.e. it had a value and is now `undefined`
 
-```javascript
+```ts
 delta = [oldValue, 0, 0];
 ```
 
@@ -44,7 +44,7 @@ This makes the delta irreversible (can't be used for unpatch), but might be a go
 
 value is an object, and there are nested changes inside its properties
 
-```javascript
+```ts
 delta = {
   property1: innerDelta1,
   property2: innerDelta2,
@@ -56,19 +56,19 @@ delta = {
 
 Here's an example combining what we have:
 
-```
+```ts
 delta = {
-  property1: [ newValue1 ], // obj[property1] = newValue1
-  property2: [ oldValue2, newValue2 ], // obj[property2] = newValue2 (and previous value was oldValue2)
-  property5: [ oldValue5, 0, 0 ] // delete obj[property5] (and previous value was oldValue5)
-}
+  property1: [newValue1], // obj[property1] = newValue1
+  property2: [oldValue2, newValue2], // obj[property2] = newValue2 (and previous value was oldValue2)
+  property5: [oldValue5, 0, 0], // delete obj[property5] (and previous value was oldValue5)
+};
 ```
 
 ## Array with inner changes
 
 value is an array, and there are nested changes inside its items
 
-```javascript
+```ts
 delta = {
   _t: 'a',
   index1: innerDelta1,
@@ -92,7 +92,7 @@ Indices on array deltas can be expressed in two ways:
 
 an item was moved to a different position in the same array
 
-```javascript
+```ts
 delta = ['', destinationIndex, 3];
 ```
 
@@ -104,16 +104,16 @@ delta = ['', destinationIndex, 3];
 
 If two strings are compared and they are different, you will see as you expect:
 
-```javascript
+```ts
 delta = ['some text', 'some text modified'];
 ```
 
 But if both strings are long enough, [a text diffing algorithm](https://code.google.com/p/google-diff-match-patch/) will be used to efficiently detect changes in parts of the text.
 
 You can modify the minimum length with:
 
-```javascript
-var customDiffPatch = jsondiffpatch.create({
+```ts
+const customDiffPatch = jsondiffpatch.create({
   textDiff: {
     minLength: 60, // default value
   },
@@ -122,7 +122,7 @@ var customDiffPatch = jsondiffpatch.create({
 
 And the delta will look like this:
 
-```javascript
+```ts
 delta = [unidiff, 0, 2];
 ```
 

docs/formatters.md

@@ -6,8 +6,8 @@ Some formatters are included that let you convert a JSON delta into other format
 
 add `build/formatters.js` and `src/formatters/html.css` to your page, and:
 
-```javascript
-var delta = jsondiffpatch.diff(left, right);
+```ts
+const delta = jsondiffpatch.diff(left, right);
 // left is optional, if specified unchanged values will be visible too
 document.getElementBy('the-diff').innerHTML =
   jsondiffpatch.formatters.html.format(delta, left);
@@ -28,8 +28,8 @@ This will render the original JSON delta in html, with annotations aside explain
 
 add `build/formatters.js` and `src/formatters/annotated.css` to your page, and:
 
-```javascript
-var delta = jsondiffpatch.diff(left, right);
+```ts
+const delta = jsondiffpatch.diff(left, right);
 document.getElementBy('the-diff').innerHTML =
   jsondiffpatch.formatters.annotated.format(delta);
 ```
@@ -44,9 +44,9 @@ colored text to console log, it's used by the CLI:
 
 but you can use it programmatically too:
 
-```javascript
-var delta = jsondiffpatch.diff(left, right);
-var output = jsondiffpatch.formatters.console.format(delta);
+```ts
+const delta = jsondiffpatch.diff(left, right);
+const output = jsondiffpatch.formatters.console.format(delta);
 console.log(output);
 
 // or simply
@@ -55,14 +55,26 @@ jsondiffpatch.console.log(delta);
 
 ## JSON PATCH (RFC 6902)
 
-```javascript
-var delta = jsondiffpatch.diff(left, right);
-var output = jsondiffpatch.formatters.jsonpatch.format(delta);
-console.log(output);
+```ts
+const delta = jsondiffpatch.diff(left, right);
+const patch = jsondiffpatch.formatters.jsonpatch.format(delta);
+console.log(patch);
 ```
 
 _Don't use with `textDiff` as it isn't suppported_
 
+an implementation of patch method is also provided:
+
+```ts
+const target = jsondiffpatch.clone(left);
+const patched = jsondiffpatch.formatters.jsonpatch.patch(target, patch);
+
+// target is now equals to right
+assert(JSON.stringify(patched), JSON.stringify(right));
+```
+
+Note: this patch method is atomic as specified by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902#section-5). If any error occurs during patching, the `target` object is rolled back to its original state.
+
 ## Create one
 
 Of course, first step to create a formatters is understanding the [delta format](deltas.md).

docs/plugins.md

@@ -17,7 +17,7 @@ Check the `/src/filters` folder for filter examples.
 Here is an example to provide number differences in deltas (when left and right values are both numbers)
 This, way when diffing 2 numbers instead of obtaining `[ oldValue, newValue ] `, the difference between both values will be saved, this could be useful for counters simultaneously incremented in multiple client applications (patches that both increment a value would be combined, instead of failing with a conflict).
 
-```javascript
+```ts
 /*
 Plugin a new diff filter
 */