tracked-instance 1.0.23 → 2.0.0

package/README.md

@@ -70,6 +70,27 @@ useTrackedInstance(false)
 useTrackedInstance([1,2,3])
 ```
 
+### Custom equality with `equals` option
+
+By default, values are compared with strict equality (`===`). You can override this with a custom `equals` function that is called for primitive leaf values.
+
+A common use case is treating `null` and `""` as equivalent — for example, when a UI component (like Vuetify's text field with a clear button) sets a value to `null`, but the original data used `""`:
+
+```javascript
+const { data, isDirty } = useTrackedInstance(
+  { comment: null },
+  { equals: (a, b) => (a ?? '') === (b ?? '') }
+)
+
+data.value.comment = ''   // treated as equal to null
+console.log(isDirty.value) // false
+
+data.value.comment = 'hello'
+console.log(isDirty.value) // true
+```
+
+The `equals` function receives the two values being compared and should return `true` if they are considered equal. It is only called for primitive values — object and array fields are always compared by recursing into their properties.
+
 ### Real-world example
 [Try on playground](https://play.vuejs.org/#eNqNVc1u00AQfpXBl7RSapfCAVlJVGh7KEiloj36srEn8TbrtbU/aaMoz4DEjROvgYTEw/AC8AjM7tqpaarSm+d/vplv1uvobdPES4tRGo10rnhjQKOxzSSTvGpqZWBtNV4rli+wOJfaMJnjBmaqrmBggvqAt/pBJjOZ1yTBumCGDSEvmZxjceoFrk+5MqshKKQaQxA185YNjGG3yN46kwCGG4EpDAZDJ62QqRSkFcKLXF/aqeC6xCKFGRMavbpAw7jQKfgMAEkCuqytKGCKYBvqDOlzta3vvDaZ3Oy79sk5uACX3HAmwCGBW24ohYGKLRBmtaqgcFgy2SUJ7XJq5KVvomv8ukQ4ZWoBHySfl6aP4+jw8M0uDqPs4zCoIOampsBWASBZ5WqclIprUzclKrioBZMDh9l3qRHbJWgCBBK1A79kwqIOWQh5D37YnmZLPGmjxrC3D+NJKLpF64YS+zQURtGjJLCHeEOCwaoRNEOSAEYFX07a3VPv644HsNmMEmfzTqWCJHxNrTG1hONc8HwxziLPliya/Pr64/f3z/DJiaMkePlyFOOxHms7rbiJG4VLlIZCezgoQcA74rKxppvg8qCqCxTk6xH5rWVRZzWrBslk8I4aaMn0VJpY2mqKqsvm1ryTLLg8K12Xp8ePnXR5ifliWt/1Ez4jZUuuuCNV7Kj0X+Bt4jD7B75h+Pcp0oJrNhVYkO1Fu/LO2oIG+PPty0+4oi11JG0r3K/XCW673abLo0nYaOEPMx0lpPEWWvuE2NV7cjzDnNrxs8fJaBiFx+2gYk18o2tJz5/nd9YaiC7bM6MxPHjnnDGLSmManSaJlc1iHud1lez6dbdFFY2m25rx+YN6FNdwgepjYzjd3j91mRD17Xuv274KPsbt/BH9jSYauNYu3c2oJTWwtRmm5u6MnPns6sIvdmskaljH+yeMdHa1sK7H4PbOyoLa7vn5bs/9+LicX+uzO4NSd6Bco34a3j+L6J9z8gT0+3Zfxa+3U9z8BYQrOQM=)
 ```vue
@@ -156,7 +177,7 @@ console.log(isDirty.value) // true
 Add new item:
 ```javascript
 const addedItem = add({name: 'Taras'})
-console.log(addedItem) // {instance: TrackedInstance<{name: 'Taras'}>, isRemoved: false, isNew: true, meta: {}}}
+console.log(addedItem) // {instance: TrackedInstance<{name: 'Taras'}>, isRemoved: false, isNew: true, meta: undefined}
 ```
 Add new item in specific position:
 ```javascript
@@ -259,27 +280,61 @@ console.log(items.value[0].meta.isValidName.value) // false
 ```
 
 # Documentation
-## TrackedInstance
-- **data** - tracked data
-- **changeData** - includes only modified fields from data, considers nested objects and arrays
-- **isDirty** - weather instance has some changes
-- **loadData** - rewrite data and clear dirty state
-- **reset** - rollback changes at the last point when the instance was not isDirty
+## useTrackedInstance(initialData?, options?)
 
-## Collection
-- **items** - array of `CollectionItem`
-- **isDirty** - weather collection includes some changes (add/remove/change)
-- **add** - add new item
-- **remove** - soft remove item by index. Soft removed items should be deleted permanently after load data. Can be reverted by reset. If passed second param isHardRemove can be deleted permanently.
-- **loadData** - accepts array of data for each item. Rewrite each instance data and clear dirty state
-- **reset** - rollback changes at the last point when the instance was not isDirty
+```typescript
+useTrackedInstance<Data>(initialData?: Data, options?: TrackedInstanceOptions): TrackedInstance<Data>
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `equals` | `(a: unknown, b: unknown) => boolean` | Custom equality function for primitive leaf values. Replaces default `===`. |
+
+### TrackedInstance
+
+- **data** — reactive reference to the current data. Mutate it directly to track changes.
+- **changedData** — only the modified fields, deeply nested. `undefined` when nothing has changed.
+- **isDirty** — `true` when any field differs from the original.
+- **loadData(newData)** — replace data and clear dirty state (new baseline).
+- **reset()** — revert all changes back to the last `loadData()` baseline.
+
+## useCollection(createItemMeta?, options?)
+
+```typescript
+useCollection<Item, Meta>(
+  createItemMeta?: (instance: TrackedInstance<Item>) => Meta,
+  options?: TrackedInstanceOptions,
+): Collection<Item, Meta>
+```
+
+The `options` object (including `equals`) is passed to every `TrackedInstance` created inside the collection — both from `loadData()` and `add()`.
+
+```javascript
+const { items, isDirty } = useCollection(
+  () => undefined,
+  { equals: (a, b) => (a ?? '') === (b ?? '') }
+)
+```
+
+### Collection
+
+- **items** — reactive array of `CollectionItem`.
+- **isDirty** — `true` if any item is dirty, new, or soft-removed.
+- **add(item, index?)** — add a new item (marked `isNew`). Appended to end by default.
+- **remove(index, isHardRemove?)** — soft-remove by default (`isRemoved = true`). Pass `true` to hard-delete from array.
+- **loadData(items)** — replace all items and clear dirty state.
+- **reset()** — remove new items, restore soft-removed items, and reset all instance data.
+
+### CollectionItem
 
 ```typescript
-interface CollectionItem {
-  instance: TrackedInstance
-  isRemoved: Ref<boolean>
-  isNew: Ref<boolean> //weather is new instance. Field can be changed manually or changed in loadData in second argument
-  meta: Record<string, any>
-  remove: (isHardRemove?: boolean) => void
+interface CollectionItem<Item, Meta = undefined> {
+  instance: TrackedInstance<Item>  // the tracked instance for this item
+  isRemoved: Ref<boolean>          // true after soft remove
+  isNew: Ref<boolean>              // true for items added via add(), false for items loaded via loadData()
+  meta: Meta                       // custom metadata from createItemMeta(), undefined by default
+  remove: (isHardRemove?: boolean) => void  // shortcut: removes self from collection
 }
 ```

package/dist/index.mjs

@@ -1535,7 +1535,7 @@ var setOriginalDataValue = (originalData, path) => {
   const lastItem = path.at(-1);
   originalDataTarget[lastItem.property] = lastItem.target[lastItem.property];
 };
-var snapshotValueToOriginalData = (originalData, path, value) => {
+var snapshotValueToOriginalData = (originalData, path, value, equals) => {
   const pathAsString = path.map((i) => i.property);
   const valueInOriginalData = get_default(originalData, pathAsString);
   const markRemovedFieldsAsUndefined = (valueInOriginalData2, oldValue2) => {
@@ -1555,7 +1555,8 @@ var snapshotValueToOriginalData = (originalData, path, value) => {
       snapshotValueToOriginalData(
         originalData,
         path.concat({ target: oldValue2 || value, property: key }),
-        void 0
+        void 0,
+        equals
       );
     }
   };
@@ -1564,7 +1565,7 @@ var snapshotValueToOriginalData = (originalData, path, value) => {
   if (isObject2(value) && (isObject2(valueInOriginalData) || isObject2(oldValue))) {
     markRemovedFieldsAsUndefined(valueInOriginalData, oldValue);
     for (const key of Object.keys(value)) {
-      snapshotValueToOriginalData(originalData, path.concat({ target: oldValue || value, property: key }), value[key]);
+      snapshotValueToOriginalData(originalData, path.concat({ target: oldValue || value, property: key }), value[key], equals);
     }
   } else if (Array.isArray(value) && (valueInOriginalData instanceof ArrayInOriginalData || Array.isArray(oldValue))) {
     markRemovedFieldsAsUndefined(valueInOriginalData, oldValue);
@@ -1572,20 +1573,24 @@ var snapshotValueToOriginalData = (originalData, path, value) => {
       snapshotValueToOriginalData(
         originalData,
         path.concat({ target: oldValue || value, property: key.toString() }),
-        value[key]
+        value[key],
+        equals
       );
     }
   } else {
+    const isEqual = equals ? equals(oldValue, value) : oldValue === value;
+    const isEqualToOriginal = equals ? equals(valueInOriginalData, value) : valueInOriginalData === value;
     if (!has_default(originalData, pathAsString)) {
-      if (oldValue !== value) {
+      if (!isEqual) {
         setOriginalDataValue(originalData, path);
       }
-    } else if (valueInOriginalData === value) {
+    } else if (isEqualToOriginal) {
       unset_default(originalData, pathAsString);
     }
   }
 };
-function useTrackedInstance(initialData) {
+function useTrackedInstance(initialData, options) {
+  const { equals } = options ?? {};
   const _originalData = createNestedRef({}, (path) => ({
     deleteProperty(target, property) {
       const result = Reflect.deleteProperty(target, property);
@@ -1623,13 +1628,13 @@ function useTrackedInstance(initialData) {
           triggerChangingArrayItems();
         }
       } else {
-        snapshotValueToOriginalData(_originalData.value, path, value);
+        snapshotValueToOriginalData(_originalData.value, path, value, equals);
       }
       return Reflect.set(target, property, cloneDeep(value), receiver);
     },
     deleteProperty(target, property) {
       const path = parentThree.concat({ target, property });
-      snapshotValueToOriginalData(_originalData.value, path, void 0);
+      snapshotValueToOriginalData(_originalData.value, path, void 0, equals);
       return Reflect.deleteProperty(target, property);
     }
   }));
@@ -1660,7 +1665,7 @@ function useTrackedInstance(initialData) {
     _originalData.value = {};
   };
   const reset = () => {
-    const updatedData = JSON.parse(JSON.stringify(_data.value));
+    const updatedData = cloneDeep(_data.value);
     for (const [path, value] of iterateObject(_originalData.value, { includeParent: true })) {
       if (value instanceof ArrayInOriginalData) {
         set_default(updatedData, path.concat("length"), value.length);
@@ -1686,7 +1691,11 @@ function useTrackedInstance(initialData) {
 
 // src/collection.ts
 import { computed as computed2, markRaw, ref } from "vue";
-var useCollection = (createItemMeta = () => void 0) => {
+var useCollection = (options) => {
+  const {
+    createItemMeta = () => void 0,
+    ...instanceOptions
+  } = options ?? {};
   const items = ref([]);
   const isDirty = computed2(
     () => items.value.some(({
@@ -1696,7 +1705,7 @@ var useCollection = (createItemMeta = () => void 0) => {
     }) => instance.isDirty.value || isNew.value || isRemoved.value)
   );
   const createItem = (item, isNew) => {
-    const instance = useTrackedInstance(item);
+    const instance = useTrackedInstance(item, instanceOptions);
     const collectionItem = markRaw({
       isRemoved: ref(false),
       isNew: ref(isNew),

package/dist/types/collection.d.ts

@@ -1,18 +1,43 @@
 import { ComputedRef, Raw, Ref } from 'vue';
-import { TrackedInstance } from './tracked-instance';
+import { TrackedInstance, TrackedInstanceOptions } from './tracked-instance';
 export type CollectionItem<Item, Meta = undefined> = Raw<{
     instance: TrackedInstance<Item>;
+    /** Arbitrary metadata attached to this item, produced by CollectionOptions.createItemMeta. */
     meta: Meta;
+    /** True when the item has been soft-deleted via remove(). */
     isRemoved: Ref<boolean>;
+    /** True for items added via add() after the last loadData() call. */
     isNew: Ref<boolean>;
+    /** Removes this item from the collection. Shortcut for calling collection.remove(index). */
     remove: (isHardRemoved?: boolean) => void;
 }>;
 export interface Collection<Item, Meta = undefined> {
     items: Ref<CollectionItem<Item, Meta>[]>;
+    /** True when any item is modified, newly added, or soft-deleted. */
     isDirty: ComputedRef<boolean>;
-    add: (item: Item, afterIndex?: number) => CollectionItem<Item, Meta>;
+    /** Adds an item to the collection. Inserts at the end by default; pass `index` to insert elsewhere. */
+    add: (item: Item, index?: number) => CollectionItem<Item, Meta>;
+    /** Soft-deletes an item by index (sets isRemoved). Pass isHardRemove=true to splice immediately. */
     remove: (index: number, isHardRemove?: boolean) => void;
+    /** Replaces all items and clears the dirty state. The loaded items become the new baseline. */
     loadData: (items: Item[]) => void;
+    /** Reverts all changes: drops new items, restores removed items, resets modified fields. */
     reset: () => void;
 }
-export declare const useCollection: <Item = any, Meta = undefined>(createItemMeta?: (instance: TrackedInstance<Item>) => Meta) => Collection<Item, Meta>;
+export interface CollectionOptions<Item, Meta = undefined> extends TrackedInstanceOptions {
+    /**
+     * Factory called when a collection item is created (via loadData or add).
+     * Use it to attach arbitrary metadata to each item — UI flags, sub-forms, derived state —
+     * that lives alongside the tracked instance but is not part of the tracked data.
+     * Receives the newly created TrackedInstance so the meta can reference reactive instance fields.
+     */
+    createItemMeta?: (instance: TrackedInstance<Item>) => Meta;
+}
+/**
+ * Creates a reactive collection of TrackedInstance items.
+ *
+ * Tracks additions, removals, and field-level modifications across all items.
+ * Each item is wrapped with markRaw to prevent Vue from making the collection item
+ * itself deeply reactive — only instance.data, isRemoved, and isNew carry reactivity.
+ */
+export declare const useCollection: <Item = any, Meta = undefined>(options?: CollectionOptions<Item, Meta>) => Collection<Item, Meta>;

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export type { TrackedInstance } from './tracked-instance';
-export type { Collection, CollectionItem } from './collection';
+export type { TrackedInstance, TrackedInstanceOptions } from './tracked-instance';
+export type { Collection, CollectionItem, CollectionOptions } from './collection';
 export { useTrackedInstance } from './tracked-instance';
 export { useCollection } from './collection';

package/dist/types/tracked-instance.d.ts

@@ -1,11 +1,27 @@
 import { Ref } from 'vue';
 import { DeepPartial } from './utils';
 export interface TrackedInstance<Data> {
+    /** Reactive reference to the current (possibly modified) data. */
     data: Ref<Data>;
+    /** True when at least one field differs from the value at the last loadData() call. */
     isDirty: Ref<boolean>;
+    /** Partial object containing only the fields that have changed since the last loadData(). */
     changedData: Ref<DeepPartial<Data>>;
+    /** Replaces the current data and clears the dirty state. The new value becomes the new baseline. */
     loadData: (newData: Data) => void;
+    /** Reverts all changes, restoring data to the state at the last loadData() call. */
     reset: () => void;
 }
-export declare function useTrackedInstance<Data = any>(): TrackedInstance<Data | undefined>;
-export declare function useTrackedInstance<Data>(value: Data): TrackedInstance<Data>;
+export interface TrackedInstanceOptions {
+    /**
+     * Custom equality function for comparing primitive values.
+     * When provided, replaces the default strict equality (===) check.
+     * Called only for primitive leaf values (strings, numbers, booleans, null, undefined).
+     *
+     * @example treat null and empty string as equal
+     * equals: (a, b) => (a ?? '') === (b ?? '')
+     */
+    equals?: (a: unknown, b: unknown) => boolean;
+}
+export declare function useTrackedInstance<Data = any>(value?: undefined, options?: TrackedInstanceOptions): TrackedInstance<Data | undefined>;
+export declare function useTrackedInstance<Data>(value: Data, options?: TrackedInstanceOptions): TrackedInstance<Data>;

package/dist/types/utils.d.ts

@@ -1,16 +1,52 @@
+/**
+ * Recursively makes all properties of T optional.
+ * Arrays use element-level DeepPartial rather than making the array itself optional,
+ * which allows sparse array diffs (e.g. only index 2 changed).
+ */
 export type DeepPartial<Value> = Value extends object ? Value extends Array<infer ArrayValue> ? Array<DeepPartial<ArrayValue>> : {
     [Property in keyof Value]?: DeepPartial<Value[Property]>;
 } : Value;
+/**
+ * Represents one segment in the path from the root proxy to the currently accessed node.
+ * Accumulated as Proxy `get` traps are traversed, then passed to `set`/`deleteProperty`
+ * handlers so they can reconstruct the full property path for _originalData bookkeeping.
+ */
 export interface NestedProxyPathItem {
     target: Record<string, any>;
     property: string;
     receiver?: Record<string, any>;
 }
+/**
+ * Returns true only for plain objects — intentionally excludes Array, Date, File, Map,
+ * and Set so they are treated as atomic leaf values rather than being traversed.
+ */
 export declare const isObject: (value: unknown) => boolean;
 export declare const isEmpty: (value: object) => boolean;
+/**
+ * Depth-first generator that walks an object tree, yielding [path, value] pairs.
+ *
+ * By default it descends into plain objects (via isObject). Supply `goDeepCondition`
+ * to override — e.g. to also descend into ArrayInOriginalData entries.
+ * When `includeParent` is true, intermediate nodes are yielded before their children,
+ * which is needed for reset() to handle ArrayInOriginalData length restoration.
+ */
 export declare const iterateObject: (source: Record<string, any>, params?: {
     goDeepCondition?: (path: string[], value: any) => boolean;
     includeParent?: boolean;
 }) => Generator<[string[], any], void, any>;
+/**
+ * Creates a Vue customRef whose value is a deeply nested Proxy tree.
+ *
+ * Every nested object/array returned by a `get` is itself wrapped in a new Proxy,
+ * so mutations at any depth trigger Vue's reactivity system via the root `track`/`trigger`
+ * pair. The `handler` factory receives the full path from the root to the current node,
+ * allowing callers to intercept `set` and `deleteProperty` with complete path context.
+ */
 export declare const createNestedRef: <Source extends Record<string, any>>(source: Source, handler: <InnerSource extends Record<string, any>>(path: NestedProxyPathItem[]) => ProxyHandler<InnerSource>) => import("vue").Ref<Source, Source>;
+/**
+ * Deep-clones a value while preserving special types:
+ * - Date → new Date instance with the same timestamp
+ * - File → same reference (Files are immutable browser objects and cannot be meaningfully cloned)
+ * All other types delegate to lodash cloneDeepWith for recursive cloning.
+ */
 export declare const cloneDeep: (inputValue: any) => any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracked-instance",
-  "version": "1.0.23",
+  "version": "2.0.0",
   "description": "Build large forms and track all changes",
   "type": "module",
   "scripts": {
@@ -10,6 +10,12 @@
   },
   "main": "./dist/index.mjs",
   "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
   "files": [
     "dist"
   ],