feat: add typescript typing

Author: QuentinRoy

.changeset/metal-pandas-wave.md

@@ -0,0 +1,5 @@
+---
+"tiny-merge-patch": minor
+---
+
+Add TypeScript typings so patch results are inferred accurately.

.tool-versions

@@ -0,0 +1,2 @@
+nodejs 22.14.0
+pnpm 10.33.0

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "editor.codeActionsOnSave": {
+    "source.organizeImports.biome": "explicit",
+    "source.fixAll.biome": "explicit"
+  }
+}

README.md

@@ -12,6 +12,8 @@ describe modifications to JSON documents.
 This library complies with the functional programming style: it does not mutate
 the original target, but recycles what it can. It is particularly appropriate to update a state used by [React](https://reactjs.org), allowing selective re-rendering of the UI.
 
+`tiny-merge-patch` is fully typed and provides strong TypeScript inference for patch results.
+
 `tiny-merge-patch` passes all [RFC 7396](http://tools.ietf.org/html/rfc7396) tests.
 
 ## Install

biome.json

@@ -13,5 +13,12 @@
     "rules": {
       "recommended": true
     }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
   }
 }

package.json

@@ -36,8 +36,8 @@
     "version-packages": "changeset version",
     "release": "changeset publish",
     "prepublishOnly": "pnpm run build",
-    "test": "vitest run --coverage",
-    "test:watch": "vitest",
+    "test": "vitest run --coverage --typecheck",
+    "test:watch": "vitest --typecheck",
     "lint": "biome check .",
     "format": "biome format --write .",
     "check": "pnpm run lint && pnpm run typecheck && pnpm run test",

src/index.ts

@@ -4,28 +4,64 @@
 const isObject = (val: unknown): val is Record<string, unknown> =>
   val != null && typeof val === "object" && Array.isArray(val) === false;
 
+/**
+ * Extract keys from a patch object where the value is null (properties to remove).
+ */
+type NullKeys<T> = {
+  [K in keyof T]: T[K] extends null ? K : never;
+}[keyof T];
+
+type IsPlainObject<T> = T extends readonly unknown[]
+  ? false
+  : T extends Record<PropertyKey, unknown>
+    ? true
+    : false;
+
+declare const emptyObjectSymbol: unique symbol;
+export interface EmptyObject {
+  [emptyObjectSymbol]?: never;
+}
+
+type NormalizeEmptyObject<T extends object> = keyof T extends never ? EmptyObject : T;
+
+type Patched<Origin, Patch> =
+  IsPlainObject<Patch> extends true
+    ? IsPlainObject<Origin> extends true
+      ? NormalizeEmptyObject<{
+          [K in Exclude<keyof Origin | keyof Patch, NullKeys<Patch>>]: K extends keyof Patch
+            ? K extends keyof Origin
+              ? Patched<Origin[K], Patch[K]>
+              : Patched<unknown, Patch[K]>
+            : K extends keyof Origin
+              ? Origin[K]
+              : never;
+        }>
+      : NormalizeEmptyObject<{
+          [K in Exclude<keyof Patch, NullKeys<Patch>>]: Patched<unknown, Patch[K]>;
+        }>
+    : Patch;
+
 /**
  * Apply a JSON merge patch. The origin is not modified, but unchanged
  * properties are recycled.
  */
-export function apply(origin: unknown, patch: unknown): unknown {
+export function apply<Origin, Patch>(origin: Origin, patch: Patch): Patched<Origin, Patch> {
   if (!isObject(patch)) {
     // If the patch is not an object, it replaces the origin.
-    return patch;
+    return patch as Patched<Origin, Patch>;
   }
 
   const result: Record<string, unknown> = !isObject(origin) ? {} : { ...origin };
 
-  for (const key of Object.keys(patch)) {
-    const patchVal = patch[key];
+  for (const [key, patchVal] of Object.entries(patch)) {
     if (patchVal === null) {
       delete result[key];
     } else {
       result[key] = apply(result[key], patchVal);
     }
   }
 
-  return result;
+  return result as Patched<Origin, Patch>;
 }
 
 export default apply;

test/index.test-d.ts

@@ -0,0 +1,82 @@
+import { describe, expectTypeOf, it } from "vitest";
+import type { EmptyObject } from "../src/index.js";
+import jsonMergePatch from "../src/index.js";
+
+describe("jsonMergePatch type", () => {
+  it("should replace an attribute", () => {
+    const patched = jsonMergePatch({ a: "b" }, { a: "c" });
+    expectTypeOf(patched).toEqualTypeOf<{ a: string }>();
+  });
+
+  it("should add an attribute", () => {
+    const patched = jsonMergePatch({ a: "b" }, { b: "c" });
+    expectTypeOf(patched).toEqualTypeOf<{ a: string; b: string }>();
+  });
+
+  it("should delete attribute", () => {
+    let patched = jsonMergePatch({ a: "b" }, { a: null });
+    expectTypeOf(patched).toEqualTypeOf<EmptyObject>();
+    // @ts-expect-error
+    patched = 5;
+  });
+
+  it("should delete attribute without affecting others", () => {
+    const patched = jsonMergePatch({ a: "b", b: "c" }, { a: null });
+    expectTypeOf(patched).toEqualTypeOf<{ b: string }>();
+  });
+
+  it("should replace array with a string", () => {
+    const patched = jsonMergePatch({ a: ["b"] }, { a: "c" });
+    expectTypeOf(patched).toEqualTypeOf<{ a: string }>();
+  });
+
+  it("should replace a string with an array", () => {
+    const patched = jsonMergePatch({ a: "c" }, { a: ["b"] });
+    expectTypeOf(patched).toEqualTypeOf<{ a: string[] }>();
+  });
+
+  it("should apply recursively", () => {
+    const patched = jsonMergePatch({ a: { b: "c" } }, { a: { b: "d", c: null } });
+    expectTypeOf(patched).toEqualTypeOf<{ a: { b: string } }>();
+  });
+
+  it("should replace an object array with a number array", () => {
+    const patched = jsonMergePatch({ a: [{ b: "c" }] }, { a: [1] as const });
+    expectTypeOf(patched).toEqualTypeOf<{ a: readonly [1] }>();
+  });
+
+  it("should replace an array", () => {
+    const patched = jsonMergePatch(["a", "b"] as const, ["c", "d"] as const);
+    expectTypeOf(patched).toEqualTypeOf<readonly ["c", "d"]>();
+  });
+
+  it("should replace an object with an array", () => {
+    const patched = jsonMergePatch({ a: "b" }, ["c"] as const);
+    expectTypeOf(patched).toEqualTypeOf<readonly ["c"]>();
+  });
+
+  it("should replace an object with null", () => {
+    const patched = jsonMergePatch({ a: "foo" }, null);
+    expectTypeOf(patched).toEqualTypeOf<null>();
+  });
+
+  it("should replace an object with a string", () => {
+    const patched = jsonMergePatch({ a: "foo" }, "bar");
+    expectTypeOf(patched).toEqualTypeOf<string>();
+  });
+
+  it("should not change null attributes", () => {
+    const patched = jsonMergePatch({ e: null }, { a: 1 });
+    expectTypeOf(patched).toEqualTypeOf<{ e: null; a: number }>();
+  });
+
+  it("should not set an attribute to null", () => {
+    const patched = jsonMergePatch([1, 2], { a: "b", c: null });
+    expectTypeOf(patched).toEqualTypeOf<{ a: string }>();
+  });
+
+  it("should not set an attribute to null in a sub object", () => {
+    const patched = jsonMergePatch({}, { a: { bb: { ccc: null } } });
+    expectTypeOf(patched).toEqualTypeOf<{ a: { bb: EmptyObject } }>();
+  });
+});

test/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import jsonMergePatch from "../src";
+import jsonMergePatch from "../src/index.js";
 
 describe("jsonMergePatch", () => {
   it("should replace an attribute", () => {

tsconfig.json

@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
     "strict": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,