@solid-primitives/deep 0.3.5 → 1.0.0-next.0

package/README.md

@@ -4,9 +4,10 @@
 
 # @solid-primitives/deep
 
-[![size](https://img.shields.io/bundlephobia/minzip/@solid-primitives/deep?style=for-the-badge&label=size)](https://bundlephobia.com/package/@solid-primitives/deep)
+[![size](https://img.shields.io/badge/size-1.3_kB-blue?style=for-the-badge)](https://bundlephobia.com/package/@solid-primitives/deep)
 [![version](https://img.shields.io/npm/v/@solid-primitives/deep?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/deep)
 [![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-1.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)
+[![tested with vitest](https://img.shields.io/badge/tested_with-vitest-6E9F18?style=for-the-badge&logo=vitest)](https://vitest.dev)
 
 Primitives for tracking and observing nested reactive objects in Solid.
 
@@ -14,6 +15,35 @@ Primitives for tracking and observing nested reactive objects in Solid.
 - [`trackStore`](#trackstore) - A more performant alternative to `trackDeep` utilizing specific store implementations.
 - [`captureStoreUpdates`](#capturestoreupdates) - A utility function that captures all updates to a store and returns them as an array.
 
+## Comparison with Solid's built-in `deep`
+
+Solid 2.0 ships a `deep` helper in `solid-js` that tracks all nested properties of a store and returns a **plain snapshot** — a non-reactive copy suitable for serialization:
+
+```ts
+import { deep } from "solid-js";
+
+createEffect(
+  () => deep(store),
+  snapshot => localStorage.setItem("state", JSON.stringify(snapshot)),
+);
+```
+
+This package complements that with three distinct utilities:
+
+|                                        | Solid's `deep` | `trackDeep` | `trackStore` | `captureStoreUpdates` |
+| -------------------------------------- | -------------- | ----------- | ------------ | --------------------- |
+| Tracks all nested changes              | ✓              | ✓           | ✓            | ✓                     |
+| Returns live store proxy               | —              | ✓           | ✓            | —                     |
+| Returns plain snapshot                 | ✓              | —           | —            | —                     |
+| Works on plain objects wrapping stores | —              | ✓           | —            | —                     |
+| Reports what changed and where         | —              | —           | —            | ✓                     |
+
+**Use Solid's `deep`** when you want to observe all changes and immediately consume a serializable value (e.g. persist to localStorage, send over the wire).
+
+**Use `trackDeep` or `trackStore`** when you need the live reactive proxy back — for example, to pass it reactively to another primitive, or when you want to decide what to do with the store rather than serialize it immediately. `trackStore` is preferred for large or frequently updated stores due to its use of memoized structural subscriptions; `trackDeep` additionally accepts plain objects that contain stores.
+
+**Use `captureStoreUpdates`** when you need to know _what_ changed and _where_ — it returns an array of `{ path, value }` deltas since the last call. Solid's `deep` has no equivalent for this.
+
 ## Installation
 
 ```bash
@@ -41,20 +71,23 @@ import { trackDeep } from "@solid-primitives/deep";
 
 const [state, setState] = createStore({ name: "John", age: 42 });
 
-createEffect(() => {
-  trackDeep(state);
-  /* execute some logic whenever the state changes */
-});
+createEffect(
+  () => trackDeep(state),
+  () => {
+    /* execute some logic whenever the state changes */
+  },
+);
 ```
 
 Or since this has a composable design, you can create _derivative_ functions and use them similar to derivative signals.
 
 ```ts
 const deeplyTrackedStore = () => trackDeep(sign);
-createEffect(() => {
-  console.log("Store is: ", deeplyTrackedStore());
-  //                        ^ this causes a re-execution of the effect on deep changes of properties
-});
+createEffect(
+  () => deeplyTrackedStore(),
+  //    ^ this causes a re-execution of the effect on deep changes of properties
+  value => console.log("Store is:", value),
+);
 ```
 
 `trackDeep` will traverse any "wrappable" object _(objects that solid stores will wrap with proxies)_, even if it's not a solid store.
@@ -66,15 +99,17 @@ createEffect(() => {
 });
 ```
 
-> **Warning** If you `unwrap` a store, it will no longer be tracked by `trackDeep` nor `trackStore`!
+> **Warning** If you `snapshot` a store, it will no longer be tracked by `trackDeep` nor `trackStore`!
 
 ```ts
-const unwrapped = unwrap(state);
+import { snapshot } from "solid-js";
 
-createEffect(() => {
-  // This will NOT work:
-  trackDeep(unwrapped);
-});
+const plain = snapshot(state);
+
+createEffect(
+  () => trackDeep(plain), // This will NOT work — plain objects are not reactive
+  () => {},
+);
 ```
 
 ## `trackStore`
@@ -92,10 +127,12 @@ import { trackStore } from "@solid-primitives/deep";
 
 const [state, setState] = createStore({ name: "John", age: 42 });
 
-createEffect(() => {
-  trackStore(state);
-  /* execute some logic whenever the state changes */
-});
+createEffect(
+  () => trackStore(state),
+  () => {
+    /* execute some logic whenever the state changes */
+  },
+);
 ```
 
 ## `captureStoreUpdates`
@@ -115,7 +152,9 @@ const getDelta = captureStoreUpdates(state);
 
 getDelta(); // [{ path: [], value: { todos: [] } }]
 
-setState("todos", ["foo"]);
+setState(s => {
+  s.todos = ["foo"];
+});
 
 getDelta(); // [{ path: ["todos"], value: ["foo"] }]
 ```
@@ -127,11 +166,13 @@ const [state, setState] = createStore({ todos: [] });
 
 const getDelta = captureStoreUpdates(state);
 
-createEffect(() => {
-  const delta = getDelta();
-  /* execute some logic whenever the state changes */
-  console.log(delta);
-});
+createEffect(
+  () => getDelta(),
+  delta => {
+    /* execute some logic whenever the state changes */
+    console.log(delta);
+  },
+);
 ```
 
 The returned function is not a signal - it won't get updated by itself, it has to be called manually, or under a tracking scope to capture new updates.
@@ -144,18 +185,16 @@ const [state, setState] = createStore({ todos: [] });
 const delta = createMemo(captureStoreUpdates(state));
 
 // both of these effects will receive the same delta
-createEffect(() => {
-  console.log(delta());
-});
-createEffect(() => {
-  console.log(delta());
-});
+createEffect(
+  () => delta(),
+  value => console.log(value),
+);
+createEffect(
+  () => delta(),
+  value => console.log(value),
+);
 ```
 
-### Demo
-
-See a demo of this primitive in action [here](https://primitives.solidjs.community/playground/deep).
-
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md)

package/dist/store-updates.d.ts

@@ -24,7 +24,7 @@ export type NestedUpdate<T> = {
  *
  * getDelta(); // [{ path: [], value: { todos: [] } }]
  *
- * setState("todos", ["foo"]);
+ * setState(s => { s.todos = ["foo"]; });
  *
  * getDelta(); // [{ path: ["todos"], value: ["foo"] }]
  * ```

package/dist/store-updates.js

@@ -1,7 +1,9 @@
 import { createLazyMemo } from "@solid-primitives/memo";
-import { $PROXY, $TRACK, createRoot, untrack } from "solid-js";
-import { unwrap } from "solid-js/store";
-import { isDev, isServer } from "solid-js/web";
+import { $PROXY, $TRACK, DEV, runWithOwner, untrack, snapshot } from "solid-js";
+import { isServer } from "@solidjs/web";
+// Typed iterator that preserves numeric keys for arrays vs. string keys for objects.
+// Object.entries() returns [string, T][] even for arrays, losing the numeric key type,
+// so arrays are iterated manually.
 function* entries(obj) {
     if (Array.isArray(obj)) {
         for (let i = 0; i < obj.length; i++) {
@@ -14,18 +16,31 @@ function* entries(obj) {
         yield* Object.entries(obj)[Symbol.iterator]();
     }
 }
+// One lazy memo per store node, keyed by node identity. The memo re-runs whenever the node's
+// structure changes ([$TRACK] subscription) and returns the current set of child store nodes.
+// Detached from any owner so it lives as long as the node is reachable, then self-disposes.
 const StoreNodeChildrenCache = new WeakMap();
+// Returns the reactive snapshot of a node's direct store-node children.
+// Uses a lazy memo so the computation is only created once per node, and only runs when read.
 function getStoreNodechildren(node) {
     let signal = StoreNodeChildrenCache.get(node);
     if (!signal) {
-        const unwrapped = unwrap(node), isArray = Array.isArray(unwrapped);
-        signal = createRoot(() => createLazyMemo(() => {
+        const isArray = Array.isArray(node);
+        // runWithOwner(null) detaches the memo from any current reactive owner so it won't be
+        // disposed when a caller's effect re-runs. It self-disposes when it has no subscribers.
+        signal = runWithOwner(null, () => createLazyMemo(() => {
+            // Subscribe to structural changes (key additions/removals) on this node.
             node[$TRACK];
+            // snapshot() inside untrack() gives us the plain key list without subscribing to
+            // individual property signals — we only want to know which keys exist, not their values.
+            const unwrapped = untrack(() => snapshot(node));
             const children = isArray ? [] : {};
             for (const [key, child] of entries(unwrapped)) {
                 let childNode;
                 if (child != null &&
                     typeof child === "object" &&
+                    // Prefer the proxy stored on the plain value ($PROXY), falling back to reading the
+                    // key through the live store proxy (which re-wraps nested objects on access).
                     ((childNode = child[$PROXY]) ||
                         ((childNode = untrack(() => node[key])) && $TRACK in childNode))) {
                     children[key] = childNode;
@@ -37,29 +52,42 @@ function getStoreNodechildren(node) {
     }
     return signal();
 }
+// Module-level globals, reset at the start of every getDelta() call.
+// Safe because JS is single-threaded — no two calls can interleave.
 let CurrentUpdates;
 let SeenNodes;
+// Builds a fresh cache entry for a node that was added or changed.
+// Recursively pre-populates children so future calls can diff them.
 function newCacheNode(children) {
     const record = { ...children };
     for (const [key, node] of entries(children)) {
         if (SeenNodes.has(node))
-            continue;
+            continue; // guard against circular references
         SeenNodes.add(node);
         record[key] = newCacheNode(getStoreNodechildren(node));
     }
     return { children, record };
 }
+// Walks the store tree, diffing each node against its cached snapshot.
+// A node is "changed" when its children reference differs from the cached one —
+// getStoreNodechildren() returns a stable reference when nothing has changed,
+// so a strict equality check is sufficient and cheap.
+// When a change is found, the whole subtree is re-cached and reported as a single
+// update at the shallowest changed node (so leaf changes inside an object are reported
+// as one update on the parent object, not one per leaf).
 function compareStoreWithCache(node, parent, key, path) {
     if (SeenNodes.has(node))
-        return;
+        return; // guard against circular references
     SeenNodes.add(node);
     const cacheNode = parent[key], children = getStoreNodechildren(node);
     if (cacheNode && children === cacheNode.children) {
+        // Node itself is unchanged; recurse to check its children.
         for (const [key, child] of entries(children)) {
             compareStoreWithCache(child, cacheNode.record, key, [...path, key]);
         }
     }
     else {
+        // Node is new or its structure changed — record it and rebuild its subtree cache.
         parent[key] = newCacheNode(children);
         CurrentUpdates.push({ path, value: node });
     }
@@ -82,25 +110,30 @@ function compareStoreWithCache(node, parent, key, path) {
  *
  * getDelta(); // [{ path: [], value: { todos: [] } }]
  *
- * setState("todos", ["foo"]);
+ * setState(s => { s.todos = ["foo"]; });
  *
  * getDelta(); // [{ path: ["todos"], value: ["foo"] }]
  * ```
  */
 export function captureStoreUpdates(store) {
-    // on the server you cannot check if the passed object is a store
-    // so we just return the whole store always
-    if (isServer || !($TRACK in store)) {
-        if (isDev) {
+    // On the server $TRACK is not present on store proxies, so we can't diff.
+    // Return the whole store on the first call and nothing thereafter.
+    if (isServer) {
+        let init = true;
+        return () => (init ? ((init = false), [{ path: [], value: store }]) : []);
+    }
+    if (!(typeof store === "object" && store !== null && $TRACK in store)) {
+        if (DEV) {
             // eslint-disable-next-line no-console
-            console.warn("createStoreDelta expects a store, got", store);
+            console.warn("captureStoreUpdates expects a store, got", store);
         }
         let init = true;
         return () => (init ? ((init = false), [{ path: [], value: store }]) : []);
     }
+    // The root cache entry — "root" is a synthetic key so compareStoreWithCache can write
+    // cache[key] uniformly without special-casing the top level.
     const cache = {};
     return () => {
-        // set globals before each cycle
         CurrentUpdates = [];
         SeenNodes = new WeakSet();
         compareStoreWithCache(store, cache, "root", []);

package/dist/track-deep.d.ts

@@ -1,4 +1,4 @@
-import { type Store } from "solid-js/store";
+import { type Store } from "solid-js";
 /**
  * Tracks all properties of a {@link store} by iterating over them recursively.
  *
@@ -9,12 +9,12 @@ import { type Store } from "solid-js/store";
  *
  * @example
  * ```ts
- * createEffect(on(
+ * createEffect(
  *   () => trackDeep(store),
  *   () => {
  *     // this effect will run when any property of store changes
  *   }
- * ));
+ * );
  * ```
  */
 declare function trackDeep<T extends Store<object>>(store: T): T;

package/dist/track-deep.js

@@ -1,5 +1,4 @@
 import { $PROXY } from "solid-js";
-import {} from "solid-js/store";
 /**
  * Tracks all properties of a {@link store} by iterating over them recursively.
  *
@@ -10,12 +9,12 @@ import {} from "solid-js/store";
  *
  * @example
  * ```ts
- * createEffect(on(
+ * createEffect(
  *   () => trackDeep(store),
  *   () => {
  *     // this effect will run when any property of store changes
  *   }
- * ));
+ * );
  * ```
  */
 function trackDeep(store) {
@@ -25,7 +24,7 @@ function trackDeep(store) {
 function traverse(value, seen) {
     let isArray;
     let proto;
-    // check the same conditions as in `isWrappable` from `/packages/solid/store/src/store.ts`
+    // check the same conditions as in `isWrappable` from solid's store implementation
     if (value != null &&
         typeof value === "object" &&
         !seen.has(value) &&

package/dist/track-store.d.ts

@@ -1,4 +1,4 @@
-import { type Store } from "solid-js/store";
+import { type Store } from "solid-js";
 /**
  * Tracks all nested changes to passed {@link store}.
  *
@@ -9,12 +9,12 @@ import { type Store } from "solid-js/store";
  *
  * @example
  * ```ts
- * createEffect(on(
+ * createEffect(
  *   () => trackStore(store),
  *   () => {
  *     // this effect will run when any property of store changes
  *   }
- * ));
+ * );
  * ```
  */
 declare function trackStore<T extends object>(store: Store<T>): T;

package/dist/track-store.js

@@ -1,54 +1,4 @@
-import { $PROXY, $TRACK, createMemo, createRoot, createSignal, untrack } from "solid-js";
-import { unwrap } from "solid-js/store";
-const EQUALS_FALSE = { equals: false };
-const TrackStoreCache = new WeakMap();
-// for preventing the same object to be visited multiple times in the same trackStore call
-let TrackVersion = 0;
-function getTrackStoreNode(node) {
-    let track = TrackStoreCache.get(node);
-    if (!track) {
-        createRoot(() => {
-            const unwrapped = unwrap(node);
-            // custom lazy memo to support circular references
-            // maybe it won't be needed in solid 2.0
-            let is_reading = false;
-            let is_stale = true;
-            let version = 0;
-            const [signal, trigger] = createSignal(undefined, EQUALS_FALSE);
-            const memo = createMemo(() => {
-                if (is_reading) {
-                    node[$TRACK]; // shallow track store node
-                    // track each child node
-                    for (const [key, child] of Object.entries(unwrapped)) {
-                        let childNode;
-                        if (child != null &&
-                            typeof child === "object" &&
-                            ((childNode = child[$PROXY]) || $TRACK in (childNode = untrack(() => node[key])))) {
-                            getTrackStoreNode(childNode)?.();
-                        }
-                    }
-                }
-                else {
-                    signal();
-                    is_stale = true;
-                }
-            }, undefined, EQUALS_FALSE);
-            track = () => {
-                is_reading = true;
-                if (is_stale) {
-                    trigger();
-                    is_stale = false;
-                }
-                const already_tracked = version === TrackVersion;
-                version = TrackVersion;
-                already_tracked || memo();
-                is_reading = false;
-            };
-            TrackStoreCache.set(node, track);
-        });
-    }
-    return track;
-}
+import { $TRACK } from "solid-js";
 /**
  * Tracks all nested changes to passed {@link store}.
  *
@@ -59,17 +9,29 @@ function getTrackStoreNode(node) {
  *
  * @example
  * ```ts
- * createEffect(on(
+ * createEffect(
  *   () => trackStore(store),
  *   () => {
  *     // this effect will run when any property of store changes
  *   }
- * ));
+ * );
  * ```
  */
 function trackStore(store) {
-    TrackVersion++;
-    $TRACK in store && getTrackStoreNode(store)?.();
+    traverseStore(store, new Set());
     return store;
 }
+function traverseStore(node, seen) {
+    if (!($TRACK in node) || seen.has(node))
+        return;
+    seen.add(node);
+    // subscribe to structural changes (additions/removals)
+    node[$TRACK];
+    // access all values through the proxy to subscribe to getters and collect children
+    for (const child of Object.values(node)) {
+        if (child != null && typeof child === "object") {
+            traverseStore(child, seen);
+        }
+    }
+}
 export { trackStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solid-primitives/deep",
-  "version": "0.3.5",
+  "version": "1.0.0-next.0",
   "description": "Primitives for tracking and observing nested reactive objects in Solid.",
   "author": "Samuel Burbano <me@iosamuel.dev>",
   "contributors": [
@@ -17,13 +17,14 @@
   },
   "primitive": {
     "name": "deep",
-    "stage": 1,
+    "stage": 3,
     "list": [
       "trackDeep",
       "trackStore",
       "captureStoreUpdates"
     ],
-    "category": "Reactivity"
+    "category": "Reactivity",
+    "gzip": 1298
   },
   "keywords": [
     "solid",
@@ -51,16 +52,17 @@
   },
   "typesVersions": {},
   "dependencies": {
-    "@solid-primitives/memo": "^1.4.5"
+    "@solid-primitives/memo": "^2.0.0-next.0"
   },
   "peerDependencies": {
-    "solid-js": "^1.6.12"
+    "@solidjs/web": "^2.0.0-beta.15",
+    "solid-js": "^2.0.0-beta.15"
   },
   "devDependencies": {
-    "solid-js": "^1.9.7"
+    "@solidjs/web": "2.0.0-beta.15",
+    "solid-js": "2.0.0-beta.15"
   },
   "scripts": {
-    "dev": "node --import=@nothing-but/node-resolve-ts --experimental-transform-types ../../scripts/dev.ts",
     "build": "node --import=@nothing-but/node-resolve-ts --experimental-transform-types ../../scripts/build.ts",
     "vitest": "vitest -c ../../configs/vitest.config.ts",
     "test": "pnpm run vitest",