form-diff-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tejas Kadam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# form-diff-lite
+
+Dirty-field tracking and structured diffing for form state — compares initial vs current values field by field, nested objects included.
+
+## Install
+
+```bash
+npm install form-diff-lite
+```
+
+## Quick start
+
+```ts
+import { dirtyFields, isDirty, buildPatch } from 'form-diff-lite';
+
+const initial = { name: 'Ann', address: { city: 'NYC', zip: '10001' } };
+const current = { name: 'Ann', address: { city: 'LA', zip: '10001' } };
+
+isDirty(initial, current); // true
+dirtyFields(initial, current); // ['address.city']
+buildPatch(initial, current); // { address: { city: 'LA' } }
+```
+
+## Why form-diff-lite
+
+Knowing exactly which fields a user actually changed — not just "is the form dirty" — is what lets you send a minimal PATCH request, show a targeted "unsaved changes" list, or warn about specific fields before navigating away. form-diff-lite walks two same-shaped objects recursively (following nested plain objects, deep-comparing arrays), and gives you the changed leaf paths, a dirty flag, or a nested patch object containing only what changed — no form-library dependency, works with any state shape.
+
+## API
+
+- `diffFields(before, after)` — returns `{ path, before, after }` for every changed leaf field.
+- `dirtyFields(before, after)` — just the changed field paths.
+- `isDirty(before, after)` — true if anything changed.
+- `buildPatch(before, after)` — a nested object containing only the changed values.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,15 @@
+interface FieldChange {
+    path: string;
+    before: unknown;
+    after: unknown;
+}
+/** Walks two objects field-by-field (recursing into nested plain objects) and lists changed leaf paths. */
+declare function diffFields<T extends Record<string, unknown>>(before: T, after: T, prefix?: string): FieldChange[];
+/** Returns just the set of dirty (changed) top-level-or-nested field paths. */
+declare function dirtyFields<T extends Record<string, unknown>>(before: T, after: T): string[];
+/** True if any field differs between before and after. */
+declare function isDirty<T extends Record<string, unknown>>(before: T, after: T): boolean;
+/** Builds a partial "patch" object containing only the changed leaf values, at their original nesting. */
+declare function buildPatch<T extends Record<string, unknown>>(before: T, after: T): Record<string, unknown>;
+
+export { type FieldChange, buildPatch, diffFields, dirtyFields, isDirty };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+interface FieldChange {
+    path: string;
+    before: unknown;
+    after: unknown;
+}
+/** Walks two objects field-by-field (recursing into nested plain objects) and lists changed leaf paths. */
+declare function diffFields<T extends Record<string, unknown>>(before: T, after: T, prefix?: string): FieldChange[];
+/** Returns just the set of dirty (changed) top-level-or-nested field paths. */
+declare function dirtyFields<T extends Record<string, unknown>>(before: T, after: T): string[];
+/** True if any field differs between before and after. */
+declare function isDirty<T extends Record<string, unknown>>(before: T, after: T): boolean;
+/** Builds a partial "patch" object containing only the changed leaf values, at their original nesting. */
+declare function buildPatch<T extends Record<string, unknown>>(before: T, after: T): Record<string, unknown>;
+
+export { type FieldChange, buildPatch, diffFields, dirtyFields, isDirty };

package/dist/index.js

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  buildPatch: () => buildPatch,
+  diffFields: () => diffFields,
+  dirtyFields: () => dirtyFields,
+  isDirty: () => isDirty
+});
+module.exports = __toCommonJS(index_exports);
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function valuesEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => valuesEqual(v, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].every((k) => valuesEqual(a[k], b[k]));
+  }
+  return false;
+}
+function diffFields(before, after, prefix = "") {
+  const changes = [];
+  const keys = /* @__PURE__ */ new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]);
+  for (const key of keys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const beforeVal = before?.[key];
+    const afterVal = after?.[key];
+    if (isPlainObject(beforeVal) && isPlainObject(afterVal)) {
+      changes.push(...diffFields(beforeVal, afterVal, path));
+      continue;
+    }
+    if (!valuesEqual(beforeVal, afterVal)) {
+      changes.push({ path, before: beforeVal, after: afterVal });
+    }
+  }
+  return changes;
+}
+function dirtyFields(before, after) {
+  return diffFields(before, after).map((c) => c.path);
+}
+function isDirty(before, after) {
+  return diffFields(before, after).length > 0;
+}
+function buildPatch(before, after) {
+  const patch = {};
+  for (const change of diffFields(before, after)) {
+    const parts = change.path.split(".");
+    let cursor = patch;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const key = parts[i];
+      if (!isPlainObject(cursor[key])) cursor[key] = {};
+      cursor = cursor[key];
+    }
+    cursor[parts[parts.length - 1]] = change.after;
+  }
+  return patch;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildPatch,
+  diffFields,
+  dirtyFields,
+  isDirty
+});

package/dist/index.mjs

@@ -0,0 +1,58 @@
+// src/index.ts
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function valuesEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => valuesEqual(v, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].every((k) => valuesEqual(a[k], b[k]));
+  }
+  return false;
+}
+function diffFields(before, after, prefix = "") {
+  const changes = [];
+  const keys = /* @__PURE__ */ new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]);
+  for (const key of keys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const beforeVal = before?.[key];
+    const afterVal = after?.[key];
+    if (isPlainObject(beforeVal) && isPlainObject(afterVal)) {
+      changes.push(...diffFields(beforeVal, afterVal, path));
+      continue;
+    }
+    if (!valuesEqual(beforeVal, afterVal)) {
+      changes.push({ path, before: beforeVal, after: afterVal });
+    }
+  }
+  return changes;
+}
+function dirtyFields(before, after) {
+  return diffFields(before, after).map((c) => c.path);
+}
+function isDirty(before, after) {
+  return diffFields(before, after).length > 0;
+}
+function buildPatch(before, after) {
+  const patch = {};
+  for (const change of diffFields(before, after)) {
+    const parts = change.path.split(".");
+    let cursor = patch;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const key = parts[i];
+      if (!isPlainObject(cursor[key])) cursor[key] = {};
+      cursor = cursor[key];
+    }
+    cursor[parts[parts.length - 1]] = change.after;
+  }
+  return patch;
+}
+export {
+  buildPatch,
+  diffFields,
+  dirtyFields,
+  isDirty
+};

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "form-diff-lite",
+  "version": "0.1.0",
+  "description": "Dirty-field tracking and structured diffing for form state — compares initial vs current values field by field, nested objects included.",
+  "main": "dist/index.js", "module": "dist/index.mjs", "types": "dist/index.d.ts", "files": ["dist"],
+  "license": "MIT", "author": "Tejas Kadam",
+  "repository": { "type": "git", "url": "git+https://github.com/tejas821/form-diff-lite.git" },
+  "keywords": ["forms", "dirty-fields", "diff", "typescript"],
+  "scripts": { "build": "tsup src/index.ts --format cjs,esm --dts", "test": "jest", "typecheck": "tsc --noEmit" },
+  "devDependencies": { "typescript": "^5.5.4", "tsup": "^8.2.4", "jest": "^29.7.0", "ts-jest": "^29.2.5", "@types/jest": "^29.5.12" }
+}