Consider supporting JSONPatch

[LifeIsStrange]

http://jsonpatch.com/
as the format is "standard" and is widely supported on backend stacks

[AsyncBanana]

That could be done, but it would require a breaking change and might come at a bit of a performance cost because of the value handling (the value can be an array or object instead of just going a level deeper).

[AsyncBanana]

I am returning to this, as this is more possible than I initially thought.
Question to everyone: Would you be willing to go through a breaking change if it meant that everything was compatible with JSONPatch? This would mean you would have to update some of your code, but it shouldn't be much more than some find and replace since the formats are very related, and it would allow for more integration without a compatibility layer. Also, this would make patching much easier since the libraries already exist (although I still might fully release Micropatch for the same reason I made Microdiff, but for JSONPatch patching).

[LifeIsStrange]

I am not an existing user but my frontend basically necessitate a diff library that output JSON-Patch given that libraries on the backend commonly expect (or generate) this format.
I think this breaking change is for the greater good as it allows standardization and interoperability with a wider ecosystem.

[AsyncBanana]

I am looking at doing this again. However, a feature some people rely on in Microdiff is the oldValue property, which does not exist in JSON Patch. I could add oldValue while otherwise keeping compatibility with JSON Patch. This would still be compatible with most things and would be simple enough to filter out if there is an incompatible library.
Another option would be to add a JSON Patch config option. This would allow for perfect JSON Patch compatibility while still making it possible to see the past value for those who need it and could even allow for no breaking change (although I would probably still release a new major version for other things). However, I try to minimize the configuration, as each config option increases size and decreases performance.
What do you think?

[LifeIsStrange]

I would personally vote for the config but it's your codebase, do as you please :)

to be clear what you mean is: for the given input

{
  "baz": "qux",
  "foo": "bar"
}

and following patch

[
  { "op": "replace", "path": "/baz", "value": "boo" },
  { "op": "add", "path": "/hello", "value": ["world"] },
  { "op": "remove", "path": "/foo" }
]

microdiff would output:

{
"oldValueBaz": "qux",
"oldValueFoo": "bar",
"oldValueBaz": "???"
  "baz": "boo",
  "hello": ["world"]
}

instead of

{
  "baz": "boo",
  "hello": ["world"]
}

? What's the exact format
I believe in most cases those oldvalues would need to be filtered out (cpu time and increase network payload size and libraries incompatibility) although emitting them might be very useful for debugging and some validations/custom logics. I'm not aware of other use cases but maybe there are.

[AsyncBanana]

I am little confused about what you mean. I am not talking about adding patching functionality for Microdiff. What I am saying is that Microdiff would output JSON Patch statements. For example, if oldValue was included, the output could be:

[
  { "op": "replace", "path": "/baz", "value": "boo" , "oldValue": "qux"},
  { "op": "add", "path": "/hello", "value": ["world"] },
  { "op": "remove", "path": "/foo" , "oldValue": "bar"}
]

As for use cases, it is anything that needs the past value, as getting it from the path and the old object can be slow and annoying. For example, the old value would be helpful if you built a diff viewer.
About the config, I am leaning towards that, but the code would be made much larger and potentially slower.

[Julienng]

Hello, I think keeping "oldValue" is reasonable if any other key is compatible with json-patch.
One other way would be to expose a patch and a reverse patch, so you can apply / reverse some diff changes.

Maybe making json-patch available through a new file to import might help to avoid config / breaking changes.

import { diff, patch, reversePatch } from "microdiff/json-patch"

[Julienng]

I'm going to play with microdiff and json-patch soon by transforming the result to a patch.

Do you have a branch with json-patch? I might play with microdiff locally and try to implement something

[AsyncBanana]

@Julienng There is an implementation of patching functionality, although it is currently only on GitHub, not NPM (https://github.com/AsyncBanana/micropatch).
I could make it accessible through a subpath, although I could also just release a new major version with json-patch and continue maintaining v1 (although there is not much maintenance needed to do the library being compact and dependency-less).
Currently, I do not have a branch with json-patch, although it would be trivial to implement.

[GabrielCTroia]

+1 for this! Love your micro library :)

[jgornick]

👍 Bump.

@AsyncBanana any chance you might be able to do a quick prototype of the JSONPatch result? Maybe then I or someone else could finish it up.

Thank you!

[AsyncBanana]

Here is a quick function I wrote for converting Microdiff's patching to JSONPatch @jgornick

import microdiff, { type Difference } from "microdiff";
interface BasePatch {
	op: string;
	path: string;
}
interface AddPatch extends BasePatch {
	op: "add";
	value: any;
}
interface ReplacePatch extends BasePatch {
	op: "replace";
	value: any;
}
interface RemovePatch extends BasePatch {
	op: "remove";
}
type JSONPatch = AddPatch | ReplacePatch | RemovePatch;
function convertPath(path: Difference["path"]): string {
	return (
		"/" +
		path
			.map((pathEl) =>
				typeof pathEl === "string"
					? pathEl.replace(/[~/]/g, (c) => (c === "~" ? "~0" : "~1"))
					: pathEl,
			)
			.join("/")
	);
}
function convertToJSONPatch(input: Difference[]): JSONPatch[] {
	return input.map((diff) =>
		diff.type === "CREATE" || diff.type === "CHANGE"
			? {
					op: diff.type === "CREATE" ? "add" : "replace",
					path: convertPath(diff.path),
					value: diff.value,
				}
			: { op: "remove", path: convertPath(diff.path) },
	);
}

I haven't optimized or tested it much, but because most of the differences between JSONPatch and Microdiff's diff format are relatively superficial, there shouldn't be any major issues.

Moving forward, I still see three options: integrating a conversion function into Microdiff under microdiff/jsonpatch, moving Microdiff to only use JSONPatch in a v2, or keeping this as an external function for those needing it. I am leaning towards the first option, because I still see benefits to Microdiff's current format, and the conversion would be fairly simple, but I am interested to hear if anyone has new thoughts on the matter.

[rqbazan]

In the JSON Patch RFC, it states:

Each operation in the sequence is applied to the target document; the resulting document becomes the target of the next operation.

This means that the JSON Patch format is all-or-nothing.

The current output of microdiff also behaves in an all-or-nothing manner, but I had the impression that it didn't 🤔

[Jodre11]

Not able to raise a PR but,

index.ts

export interface JsonPatchOperation {
	op: "add" | "remove" | "replace" | "move" | "copy" | "test";
	path: string;
	value?: any;
	from?: string;
}

interface Options {
	cyclesFix: boolean;
}

const richTypes = { Date: true, RegExp: true, String: true, Number: true };

function pathToJsonPointer(path: (string | number)[]): string {
	return "/" + path.map(segment => {
		// Escape special characters in path segments according to JSON Pointer spec
		return String(segment).replace(/~/g, "~0").replace(/\//g, "~1");
	}).join("/");
}

export default function diff(
	obj: Record<string, any> | any[],
	newObj: Record<string, any> | any[],
	options: Partial<Options> = { cyclesFix: true },
	_stack: Record<string, any>[] = [],
): JsonPatchOperation[] {
	let diffs: JsonPatchOperation[] = [];
	const isObjArray = Array.isArray(obj);

	for (const key in obj) {
		const objKey = obj[key];
		const path = isObjArray ? +key : key;
		if (!(key in newObj)) {
			diffs.push({
				op: "remove",
				path: pathToJsonPointer([path]),
			});
			continue;
		}
		const newObjKey = newObj[key];
		const areCompatibleObjects =
			typeof objKey === "object" &&
			typeof newObjKey === "object" &&
			Array.isArray(objKey) === Array.isArray(newObjKey);
		if (
			objKey &&
			newObjKey &&
			areCompatibleObjects &&
			!richTypes[Object.getPrototypeOf(objKey)?.constructor?.name] &&
			(!options.cyclesFix || !_stack.includes(objKey))
		) {
			diffs.push.apply(
				diffs,
				diff(
					objKey,
					newObjKey,
					options,
					options.cyclesFix ? _stack.concat([objKey]) : [],
				).map((operation) => {
					operation.path = pathToJsonPointer([path]) + (operation.path === "/" ? "" : operation.path);
					return operation;
				}),
			);
		} else if (
			objKey !== newObjKey &&
			// treat NaN values as equivalent
			!(Number.isNaN(objKey) && Number.isNaN(newObjKey)) &&
			!(
				areCompatibleObjects &&
				(isNaN(objKey)
					? objKey + "" === newObjKey + ""
					: +objKey === +newObjKey)
			)
		) {
			diffs.push({
				op: "replace",
				path: pathToJsonPointer([path]),
				value: newObjKey,
			});
		}
	}

	const isNewObjArray = Array.isArray(newObj);
	for (const key in newObj) {
		if (!(key in obj)) {
			diffs.push({
				op: "add",
				path: pathToJsonPointer([isNewObjArray ? +key : key]),
				value: newObj[key],
			});
		}
	}
	return diffs;
}

Notably, this omits oldValue, but I would suggest keeping by default and removing via configuration.