@jay-framework/view-state-merge 0.10.0

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type alias for trackBy map: maps property paths to trackBy field names.
+ * Example: { "items": "id", "products.variants": "sku" }
+ */
+type TrackByMap = Record<string, string>;
+/**
+ * Deep merge two view states using trackBy metadata for arrays.
+ * Used to combine view states from different rendering phases (slow + fast)
+ * or to merge default view state with interactive updates.
+ *
+ * @param base - Base ViewState (e.g., slow render result or default view state)
+ * @param overlay - Overlay ViewState (e.g., fast render result or interactive updates)
+ * @param trackByMap - Map from property path to trackBy field name (e.g., {"items": "id"})
+ * @param path - Current property path (used for recursion)
+ * @returns Merged ViewState combining properties from both inputs
+ */
+declare function deepMergeViewStates(base: object | undefined, overlay: object | undefined, trackByMap: TrackByMap, path?: string): object;
+
+export { type TrackByMap, deepMergeViewStates };

package/dist/index.js

@@ -0,0 +1,74 @@
+function deepMergeViewStates(base, overlay, trackByMap, path = "") {
+  if (!base && !overlay)
+    return {};
+  if (!base)
+    return overlay || {};
+  if (!overlay)
+    return base || {};
+  const result = {};
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(overlay)]);
+  for (const key of allKeys) {
+    const baseValue = base[key];
+    const overlayValue = overlay[key];
+    const currentPath = path ? `${path}.${key}` : key;
+    if (overlayValue === void 0) {
+      result[key] = baseValue;
+    } else if (baseValue === void 0) {
+      result[key] = overlayValue;
+    } else if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
+      const trackByField = trackByMap[currentPath];
+      if (trackByField) {
+        result[key] = mergeArraysByTrackBy(
+          baseValue,
+          overlayValue,
+          trackByField,
+          trackByMap,
+          currentPath
+        );
+      } else {
+        result[key] = overlayValue;
+      }
+    } else if (typeof baseValue === "object" && baseValue !== null && typeof overlayValue === "object" && overlayValue !== null && !Array.isArray(baseValue) && !Array.isArray(overlayValue)) {
+      result[key] = deepMergeViewStates(baseValue, overlayValue, trackByMap, currentPath);
+    } else {
+      result[key] = overlayValue;
+    }
+  }
+  return result;
+}
+function mergeArraysByTrackBy(baseArray, overlayArray, trackByField, trackByMap, arrayPath) {
+  const baseByKey = /* @__PURE__ */ new Map();
+  for (const item of baseArray) {
+    const key = item[trackByField];
+    if (key !== void 0 && key !== null) {
+      if (baseByKey.has(key)) {
+        console.warn(
+          `Duplicate trackBy key [${key}] in base array at path [${arrayPath}]. This may cause incorrect merging.`
+        );
+      }
+      baseByKey.set(key, item);
+    }
+  }
+  const overlayByKey = /* @__PURE__ */ new Map();
+  for (const item of overlayArray) {
+    const key = item[trackByField];
+    if (key !== void 0 && key !== null) {
+      overlayByKey.set(key, item);
+    }
+  }
+  return baseArray.map((baseItem) => {
+    const key = baseItem[trackByField];
+    if (key === void 0 || key === null) {
+      return baseItem;
+    }
+    const overlayItem = overlayByKey.get(key);
+    if (overlayItem) {
+      return deepMergeViewStates(baseItem, overlayItem, trackByMap, arrayPath);
+    } else {
+      return baseItem;
+    }
+  });
+}
+export {
+  deepMergeViewStates
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@jay-framework/view-state-merge",
+  "version": "0.10.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "^0.10.0",
+    "@types/node": "^20.11.5",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,113 @@
+# @jay-framework/view-state-merge
+
+Deep merge utility for combining ViewStates with identity-based array merging.
+
+## Purpose
+
+This library provides a deep merge algorithm that correctly combines ViewStates from different rendering phases or interactive updates. Unlike simple object spread (`{...a, ...b}`), this algorithm:
+
+1. **Deep merges nested objects** - Preserves properties from both sources at any nesting depth
+2. **Merges arrays by identity** - Uses `trackBy` metadata to match array items by their identity field (e.g., `id`) and merge their properties
+3. **Base defines structure** - For tracked arrays, items only in overlay are NOT added; the base array defines which items exist
+4. **Array replacement without trackBy** - Arrays without trackBy info are completely replaced by overlay, enabling dynamic list updates (search results, filters, etc.)
+
+## Usage
+
+```typescript
+import { deepMergeViewStates, TrackByMap } from '@jay-framework/view-state-merge';
+
+const base = {
+  name: 'Product',
+  items: [
+    { id: '1', title: 'Item 1' },
+    { id: '2', title: 'Item 2' },
+  ],
+};
+
+const overlay = {
+  price: 29.99,
+  items: [
+    { id: '1', selected: true },
+    { id: '2', selected: false },
+  ],
+};
+
+const trackByMap: TrackByMap = {
+  items: 'id', // 'items' array uses 'id' field for identity
+};
+
+const merged = deepMergeViewStates(base, overlay, trackByMap);
+// Result:
+// {
+//     name: 'Product',
+//     price: 29.99,
+//     items: [
+//         { id: '1', title: 'Item 1', selected: true },
+//         { id: '2', title: 'Item 2', selected: false },
+//     ],
+// }
+```
+
+## API
+
+### `deepMergeViewStates(base, overlay, trackByMap, path?)`
+
+Merges two ViewState objects, with overlay values taking precedence for conflicts.
+
+- `base` - Base ViewState object
+- `overlay` - Overlay ViewState object (values override base)
+- `trackByMap` - Map from property paths to trackBy field names
+- `path` - (internal) Current property path for recursion
+
+### `TrackByMap`
+
+Type alias for the trackBy mapping:
+
+```typescript
+type TrackByMap = Record<string, string>;
+```
+
+Keys are dot-separated property paths (e.g., `"items"`, `"user.orders"`), values are the field names used for identity (e.g., `"id"`, `"orderId"`).
+
+## Array Behavior
+
+### With trackBy (identity-based merge)
+
+When an array path is in `trackByMap`, items are matched by identity and merged:
+
+```typescript
+const trackByMap = { items: 'id' };
+
+// Base: [{ id: '1', name: 'A' }, { id: '2', name: 'B' }]
+// Overlay: [{ id: '1', selected: true }]
+// Result: [{ id: '1', name: 'A', selected: true }, { id: '2', name: 'B' }]
+```
+
+- Items are matched by their `id` field
+- Properties from both are merged
+- Base array order is preserved
+- Overlay-only items are NOT added (base defines structure)
+
+### Without trackBy (full replacement)
+
+When an array path is NOT in `trackByMap`, the overlay array completely replaces the base:
+
+```typescript
+const trackByMap = {}; // No trackBy for searchResults
+
+// Base: [{ id: '1', title: 'Old' }]
+// Overlay: [{ id: '3', title: 'New 1' }, { id: '4', title: 'New 2' }]
+// Result: [{ id: '3', title: 'New 1' }, { id: '4', title: 'New 2' }]
+```
+
+This is useful for:
+
+- Search results that change entirely
+- Filtered lists
+- Paginated data
+- Any dynamic list where items aren't being updated, but replaced
+
+## See Also
+
+- Design Log #56: Deep Merge View States with Track-By
+- Design Log #62: Relocate Deep Merge for Stack-Client-Runtime