@solid-primitives/deep 0.1.0 → 0.2.0

package/README.md

@@ -9,10 +9,11 @@
 [![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)
 
-Primitives for tracking changes in stores.
+Primitives for tracking and observing nested reactive objects in Solid.
 
 - [`trackDeep`](#trackDeep) - Tracks all properties of a store by iterating over them recursively.
 - [`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.
 
 ## Installation
 
@@ -39,7 +40,7 @@ You can call this function with any store under a tracking scope and it will ite
 ```ts
 import { trackDeep } from "@solid-primitives/deep";
 
-const [state, setState] = createSignal({ name: "John", age: 42 });
+const [state, setState] = createStore({ name: "John", age: 42 });
 
 createEffect(() => {
   trackDeep(state);
@@ -90,7 +91,7 @@ It can be used in almost the same way as `trackDeep`, the only difference is tha
 ```ts
 import { trackStore } from "@solid-primitives/deep";
 
-const [state, setState] = createSignal({ name: "John", age: 42 });
+const [state, setState] = createStore({ name: "John", age: 42 });
 
 createEffect(() => {
   trackStore(state);
@@ -98,6 +99,64 @@ createEffect(() => {
 });
 ```
 
+## `captureStoreUpdates`
+
+Creates a function for tracking and capturing updates to a store.
+
+It could be useful for implementing [undo/redo functionality](https://primitives.solidjs.community/package/history) or for turning a store into a immutable stream of updates.
+
+### How to use it
+
+Each execution of the returned function will return an array of updates to the store since the last execution.
+
+```ts
+const [state, setState] = createStore({ todos: [] });
+
+const getDelta = captureStoreUpdates(state);
+
+getDelta(); // [{ path: [], value: { todos: [] } }]
+
+setState("todos", ["foo"]);
+
+getDelta(); // [{ path: ["todos"], value: ["foo"] }]
+```
+
+The returned function will track all updates to a store (just like [`trackStore`](#trackStore)), so it can be used inside a tracking scope.
+
+```ts
+const [state, setState] = createStore({ todos: [] });
+
+const getDelta = captureStoreUpdates(state);
+
+createEffect(() => {
+  const delta = getDelta();
+  /* 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.
+
+But it can be turned into a signal by using `createMemo`:
+
+```ts
+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());
+});
+```
+
+### Demo
+
+See a demo of this primitive in action [here](https://primitives.solidjs.community/playground/deep).
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md)

package/dist/index.cjs

@@ -2,6 +2,8 @@
 
 var solidJs = require('solid-js');
 var store = require('solid-js/store');
+var memo = require('@solid-primitives/memo');
+var web = require('solid-js/web');
 
 // src/track-deep.ts
 function trackDeep(store) {
@@ -36,21 +38,21 @@ function createLazyMemo(calc) {
     isReading = false;
   };
 }
-function getTrackStoreNode(value) {
-  let track = TrackStoreCache.get(value);
+function getTrackStoreNode(node) {
+  let track = TrackStoreCache.get(node);
   if (!track) {
     solidJs.createRoot(() => {
-      const unwrapped = store.unwrap(value);
+      const unwrapped = store.unwrap(node);
       track = createLazyMemo(() => {
-        value[solidJs.$TRACK];
+        node[solidJs.$TRACK];
         for (const [key, child] of Object.entries(unwrapped)) {
-          let obj;
-          if (child != null && typeof child === "object" && ((obj = child[solidJs.$PROXY]) || (obj = solidJs.untrack(() => value[key])) && solidJs.$TRACK in obj)) {
-            getTrackStoreNode(obj)?.();
+          let childNode;
+          if (child != null && typeof child === "object" && ((childNode = child[solidJs.$PROXY]) || (childNode = solidJs.untrack(() => node[key])) && solidJs.$TRACK in childNode)) {
+            getTrackStoreNode(childNode)?.();
           }
         }
       });
-      TrackStoreCache.set(value, track);
+      TrackStoreCache.set(node, track);
     });
   }
   return track;
@@ -60,6 +62,80 @@ function trackStore(store) {
   solidJs.$TRACK in store && getTrackStoreNode(store)?.();
   return store;
 }
+function* entries(obj) {
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      yield [i, obj[i]];
+    }
+  } else {
+    yield* Object.entries(obj)[Symbol.iterator]();
+  }
+}
+var StoreNodeChildrenCache = /* @__PURE__ */ new WeakMap();
+function getStoreNodechildren(node) {
+  let signal = StoreNodeChildrenCache.get(node);
+  if (!signal) {
+    const unwrapped = store.unwrap(node), isArray = Array.isArray(unwrapped);
+    signal = solidJs.createRoot(
+      () => memo.createLazyMemo(() => {
+        node[solidJs.$TRACK];
+        const children = isArray ? [] : {};
+        for (const [key, child] of entries(unwrapped)) {
+          let childNode;
+          if (child != null && typeof child === "object" && ((childNode = child[solidJs.$PROXY]) || (childNode = solidJs.untrack(() => node[key])) && solidJs.$TRACK in childNode)) {
+            children[key] = childNode;
+          }
+        }
+        return children;
+      })
+    );
+    StoreNodeChildrenCache.set(node, signal);
+  }
+  return signal();
+}
+var CurrentUpdates;
+var SeenNodes;
+function newCacheNode(children) {
+  const record = { ...children };
+  for (const [key, node] of entries(children)) {
+    if (SeenNodes.has(node))
+      continue;
+    SeenNodes.add(node);
+    record[key] = newCacheNode(getStoreNodechildren(node));
+  }
+  return { children, record };
+}
+function compareStoreWithCache(node, parent, key, path) {
+  if (SeenNodes.has(node))
+    return;
+  SeenNodes.add(node);
+  const cacheNode = parent[key], children = getStoreNodechildren(node);
+  if (cacheNode && children === cacheNode.children) {
+    for (const [key2, child] of entries(children)) {
+      compareStoreWithCache(child, cacheNode.record, key2, [...path, key2]);
+    }
+  } else {
+    parent[key] = newCacheNode(children);
+    CurrentUpdates.push({ path, value: node });
+  }
+}
+function captureStoreUpdates(store) {
+  if (web.isServer || !(solidJs.$TRACK in store)) {
+    if (web.isDev) {
+      console.warn("createStoreDelta expects a store, got", store);
+    }
+    let init = true;
+    return () => init ? (init = false, [{ path: [], value: store }]) : [];
+  }
+  const cache = {};
+  return () => {
+    CurrentUpdates = [];
+    SeenNodes = /* @__PURE__ */ new WeakSet();
+    compareStoreWithCache(store, cache, "root", []);
+    return CurrentUpdates;
+  };
+}
 
+exports.captureStoreUpdates = captureStoreUpdates;
 exports.trackDeep = trackDeep;
 exports.trackStore = trackStore;

package/dist/index.d.ts

@@ -44,4 +44,37 @@ declare const deepTrack: typeof trackDeep;
  */
 declare function trackStore<T extends object>(store: Store<T>): T;
 
-export { deepTrack, trackDeep, trackStore };
+type Static<T = unknown> = {
+    [K in number | string]: T;
+} | T[];
+type AllNestedObjects<T> = T extends Static<infer U> ? AllNestedObjects<U> | T : never;
+type NestedUpdate<T> = {
+    path: (string | number)[];
+    value: AllNestedObjects<T>;
+};
+/**
+ * Creates a function for tracking and capturing updates to a {@link store}.
+ *
+ * Each execution of the returned function will return an array of updates to the store since the last execution.
+ *
+ * @param store - The store to track.
+ * @returns A function that returns an array of updates to the store since the last execution.
+ *
+ * @see https://github.com/solidjs-community/solid-primitives/tree/main/packages/deep#captureStoreUpdates
+ *
+ * @example
+ * ```ts
+ * const [state, setState] = createStore({ todos: [] });
+ *
+ * const getDelta = captureStoreUpdates(state);
+ *
+ * getDelta(); // [{ path: [], value: { todos: [] } }]
+ *
+ * setState("todos", ["foo"]);
+ *
+ * getDelta(); // [{ path: ["todos"], value: ["foo"] }]
+ * ```
+ */
+declare function captureStoreUpdates<T extends Static>(store: T): () => NestedUpdate<T>[];
+
+export { AllNestedObjects, NestedUpdate, captureStoreUpdates, deepTrack, trackDeep, trackStore };

package/dist/index.js

@@ -1,5 +1,7 @@
 import { $PROXY, $TRACK, createRoot, createSignal, createMemo, untrack } from 'solid-js';
 import { unwrap } from 'solid-js/store';
+import { createLazyMemo as createLazyMemo$1 } from '@solid-primitives/memo';
+import { isServer, isDev } from 'solid-js/web';
 
 // src/track-deep.ts
 function trackDeep(store) {
@@ -34,21 +36,21 @@ function createLazyMemo(calc) {
     isReading = false;
   };
 }
-function getTrackStoreNode(value) {
-  let track = TrackStoreCache.get(value);
+function getTrackStoreNode(node) {
+  let track = TrackStoreCache.get(node);
   if (!track) {
     createRoot(() => {
-      const unwrapped = unwrap(value);
+      const unwrapped = unwrap(node);
       track = createLazyMemo(() => {
-        value[$TRACK];
+        node[$TRACK];
         for (const [key, child] of Object.entries(unwrapped)) {
-          let obj;
-          if (child != null && typeof child === "object" && ((obj = child[$PROXY]) || (obj = untrack(() => value[key])) && $TRACK in obj)) {
-            getTrackStoreNode(obj)?.();
+          let childNode;
+          if (child != null && typeof child === "object" && ((childNode = child[$PROXY]) || (childNode = untrack(() => node[key])) && $TRACK in childNode)) {
+            getTrackStoreNode(childNode)?.();
           }
         }
       });
-      TrackStoreCache.set(value, track);
+      TrackStoreCache.set(node, track);
     });
   }
   return track;
@@ -58,5 +60,78 @@ function trackStore(store) {
   $TRACK in store && getTrackStoreNode(store)?.();
   return store;
 }
+function* entries(obj) {
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      yield [i, obj[i]];
+    }
+  } else {
+    yield* Object.entries(obj)[Symbol.iterator]();
+  }
+}
+var StoreNodeChildrenCache = /* @__PURE__ */ new WeakMap();
+function getStoreNodechildren(node) {
+  let signal = StoreNodeChildrenCache.get(node);
+  if (!signal) {
+    const unwrapped = unwrap(node), isArray = Array.isArray(unwrapped);
+    signal = createRoot(
+      () => createLazyMemo$1(() => {
+        node[$TRACK];
+        const children = isArray ? [] : {};
+        for (const [key, child] of entries(unwrapped)) {
+          let childNode;
+          if (child != null && typeof child === "object" && ((childNode = child[$PROXY]) || (childNode = untrack(() => node[key])) && $TRACK in childNode)) {
+            children[key] = childNode;
+          }
+        }
+        return children;
+      })
+    );
+    StoreNodeChildrenCache.set(node, signal);
+  }
+  return signal();
+}
+var CurrentUpdates;
+var SeenNodes;
+function newCacheNode(children) {
+  const record = { ...children };
+  for (const [key, node] of entries(children)) {
+    if (SeenNodes.has(node))
+      continue;
+    SeenNodes.add(node);
+    record[key] = newCacheNode(getStoreNodechildren(node));
+  }
+  return { children, record };
+}
+function compareStoreWithCache(node, parent, key, path) {
+  if (SeenNodes.has(node))
+    return;
+  SeenNodes.add(node);
+  const cacheNode = parent[key], children = getStoreNodechildren(node);
+  if (cacheNode && children === cacheNode.children) {
+    for (const [key2, child] of entries(children)) {
+      compareStoreWithCache(child, cacheNode.record, key2, [...path, key2]);
+    }
+  } else {
+    parent[key] = newCacheNode(children);
+    CurrentUpdates.push({ path, value: node });
+  }
+}
+function captureStoreUpdates(store) {
+  if (isServer || !($TRACK in store)) {
+    if (isDev) {
+      console.warn("createStoreDelta expects a store, got", store);
+    }
+    let init = true;
+    return () => init ? (init = false, [{ path: [], value: store }]) : [];
+  }
+  const cache = {};
+  return () => {
+    CurrentUpdates = [];
+    SeenNodes = /* @__PURE__ */ new WeakSet();
+    compareStoreWithCache(store, cache, "root", []);
+    return CurrentUpdates;
+  };
+}
 
-export { deepTrack, trackDeep, trackStore };
+export { captureStoreUpdates, deepTrack, trackDeep, trackStore };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solid-primitives/deep",
-  "version": "0.1.0",
-  "description": "Deep trigger effects for Stores.",
+  "version": "0.2.0",
+  "description": "Primitives for tracking and observing nested reactive objects in Solid.",
   "author": "Samuel Burbano <me@iosamuel.dev>",
   "contributors": [
     "Damian Tarnawski <gthetarnav@gmail.com>"
@@ -20,7 +20,8 @@
     "stage": 1,
     "list": [
       "trackDeep",
-      "trackStore"
+      "trackStore",
+      "captureStoreUpdates"
     ],
     "category": "Reactivity"
   },
@@ -29,7 +30,8 @@
     "primitives",
     "deep",
     "store",
-    "reactivity"
+    "reactivity",
+    "delta"
   ],
   "private": false,
   "sideEffects": false,
@@ -48,10 +50,16 @@
     },
     "require": "./dist/index.cjs"
   },
+  "typesVersions": {},
+  "dependencies": {
+    "@solid-primitives/memo": "^1.3.1"
+  },
   "peerDependencies": {
     "solid-js": "^1.6.12"
   },
-  "typesVersions": {},
+  "devDependencies": {
+    "solid-js": "1.7.5"
+  },
   "scripts": {
     "dev": "jiti ../../scripts/dev.ts",
     "build": "jiti ../../scripts/build.ts",