@solid-primitives/deep 0.0.102 → 0.2.0

package/README.md

@@ -7,9 +7,13 @@
 [![turborepo](https://img.shields.io/badge/built%20with-turborepo-cc00ff.svg?style=for-the-badge&logo=turborepo)](https://turborepo.org/)
 [![size](https://img.shields.io/bundlephobia/minzip/@solid-primitives/deep?style=for-the-badge&label=size)](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-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)
+[![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)
 
-- [`deepTrack`](#deepTrack) - A function that allows to trigger effects when deep properties for a store change
+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
 
@@ -21,31 +25,138 @@ yarn add @solid-primitives/deep
 pnpm add @solid-primitives/deep
 ```
 
-## How to use it
+## `trackDeep`
+
+Tracks all properties of a store by iterating over them recursively.
+
+It's a slightly more performant alternative to tracing a store with `JSON.stringify`, that won't throw when encountering circular references or `BigInt` values.
+
+Since it iterates over all properties of a store, it's not recommended to use this on large stores under rapid updates.
+
+### How to use it
 
-You can explicitly pass dependencies to effect functions like `on` and `defer` to deeply track its dependencies.
+You can call this function with any store under a tracking scope and it will iterate over all properties of the store and track them.
 
 ```ts
-createEffect(
-  on(
-    () => deepTrack(sign),
-    () => {
-      /* function to execute */
-    },
-  ),
-);
+import { trackDeep } from "@solid-primitives/deep";
+
+const [state, setState] = createStore({ name: "John", age: 42 });
+
+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 = () => deepTrack(sign);
+const deeplyTrackedStore = () => trackDeep(sign);
 createEffect(() => {
   console.log("Store is: ", deeplyTrackedStore());
   //                        ^ this causes a re-execution of the effect on deep changes of properties
 });
 ```
 
+`trackDeep` will traverse any "wrappable" object _(objects that solid stores will wrap with proxies)_, even if it's not a solid store.
+
+```ts
+createEffect(() => {
+  // will also work:
+  trackDeep({ myStore: state });
+});
+```
+
+> **Warning** If you `unwrap` a store, it will no longer be tracked by `trackDeep` nor `trackStore`!
+
+```ts
+const unwrapped = unwrap(state);
+
+createEffect(() => {
+  // This will NOT work:
+  trackDeep(unwrapped);
+});
+```
+
+## `trackStore`
+
+A much more performant alternative to `trackDeep` that is utilizing memoization and specific store implementations of solid stores.
+
+You should consider using this instead of other tracking methods, for large stores, stores that are updated rapidly or tracked in many effects.
+
+### How to use it
+
+It can be used in almost the same way as `trackDeep`, the only difference is that it requires a store to be directly passed in. So it won't work with objects that contain stores.
+
+```ts
+import { trackStore } from "@solid-primitives/deep";
+
+const [state, setState] = createStore({ name: "John", age: 42 });
+
+createEffect(() => {
+  trackStore(state);
+  /* execute some logic whenever the state changes */
+});
+```
+
+## `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

@@ -1,23 +1,141 @@
 'use strict';
 
 var solidJs = require('solid-js');
+var store = require('solid-js/store');
+var memo = require('@solid-primitives/memo');
+var web = require('solid-js/web');
 
-// src/index.ts
-function deepTrack(store) {
-  return deepTraverse(store, /* @__PURE__ */ new Set());
+// src/track-deep.ts
+function trackDeep(store) {
+  traverse(store, /* @__PURE__ */ new Set());
+  return store;
 }
-function deepTraverse(value, seen) {
-  if (!seen.has(value) && isWrappable(value)) {
+function traverse(value, seen) {
+  let isArray;
+  let proto;
+  if (value != null && typeof value === "object" && !seen.has(value) && ((isArray = Array.isArray(value)) || value[solidJs.$PROXY] || !(proto = Object.getPrototypeOf(value)) || proto === Object.prototype)) {
     seen.add(value);
-    for (const key in value) {
-      deepTraverse(value[key], seen);
+    for (const child of isArray ? value : Object.values(value))
+      traverse(child, seen);
+  }
+}
+exports.deepTrack = trackDeep;
+var EQUALS_FALSE = { equals: false };
+var TrackStoreCache = /* @__PURE__ */ new WeakMap();
+var TrackVersion = 0;
+function createLazyMemo(calc) {
+  let isReading = false, isStale = true, alreadyTracked = false, version = 0;
+  const [track, trigger] = solidJs.createSignal(void 0, EQUALS_FALSE), memo = solidJs.createMemo(() => isReading ? calc() : isStale = !track(), void 0, {
+    equals: () => alreadyTracked
+  });
+  return () => {
+    isReading = true;
+    if (isStale)
+      isStale = trigger();
+    alreadyTracked = version === TrackVersion;
+    version = TrackVersion;
+    memo();
+    isReading = false;
+  };
+}
+function getTrackStoreNode(node) {
+  let track = TrackStoreCache.get(node);
+  if (!track) {
+    solidJs.createRoot(() => {
+      const unwrapped = store.unwrap(node);
+      track = createLazyMemo(() => {
+        node[solidJs.$TRACK];
+        for (const [key, child] of Object.entries(unwrapped)) {
+          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(node, track);
+    });
+  }
+  return track;
+}
+function trackStore(store) {
+  TrackVersion++;
+  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]();
   }
-  return value;
 }
-function isWrappable(obj) {
-  let proto;
-  return obj != null && typeof obj === "object" && (obj[solidJs.$PROXY] || !(proto = Object.getPrototypeOf(obj)) || proto === Object.prototype || Array.isArray(obj));
+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.deepTrack = deepTrack;
+exports.captureStoreUpdates = captureStoreUpdates;
+exports.trackDeep = trackDeep;
+exports.trackStore = trackStore;

package/dist/index.d.ts

@@ -1,27 +1,80 @@
 import { Store } from 'solid-js/store';
 
 /**
- * deepTrack - create a deep getter on the given object
- * ```typescript
- * export function deepTrack<T>(
- *   store: Store<T>
- * ): T;
- * ```
+ * Tracks all properties of a {@link store} by iterating over them recursively.
+ *
  * @param store reactive store dependency
- * @returns same dependency, just traversed deeply to trigger effects on deeply nested properties. For example:
- *
- * ```typescript
- * createEffect(
- *     on(
- *         deepTrack(store),
- *         () => {
- *            // this effect will run when any property of store changes
- *         }
- *     )
- *
- * );
+ * @returns same {@link store} that was passed in
+ *
+ * @see https://github.com/solidjs-community/solid-primitives/tree/main/packages/deep#trackDeep
+ *
+ * @example
+ * ```ts
+ * createEffect(on(
+ *   () => trackDeep(store),
+ *   () => {
+ *     // this effect will run when any property of store changes
+ *   }
+ * ));
+ * ```
+ */
+declare function trackDeep<T extends Store<object>>(store: T): T;
+/**
+ * @deprecated Renamed to {@link trackDeep}
+ */
+declare const deepTrack: typeof trackDeep;
+
+/**
+ * Tracks all nested changes to passed {@link store}.
+ *
+ * @param store a reactive store proxy
+ * @returns same {@link store} that was passed in
+ *
+ * @see https://github.com/solidjs-community/solid-primitives/tree/main/packages/deep#trackStore
+ *
+ * @example
+ * ```ts
+ * createEffect(on(
+ *   () => trackStore(store),
+ *   () => {
+ *     // this effect will run when any property of store changes
+ *   }
+ * ));
+ * ```
+ */
+declare function trackStore<T extends object>(store: Store<T>): T;
+
+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 deepTrack<T>(store: Store<T>): T;
+declare function captureStoreUpdates<T extends Static>(store: T): () => NestedUpdate<T>[];
 
-export { deepTrack };
+export { AllNestedObjects, NestedUpdate, captureStoreUpdates, deepTrack, trackDeep, trackStore };

package/dist/index.js

@@ -1,21 +1,137 @@
-import { $PROXY } from 'solid-js';
+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/index.ts
-function deepTrack(store) {
-  return deepTraverse(store, /* @__PURE__ */ new Set());
+// src/track-deep.ts
+function trackDeep(store) {
+  traverse(store, /* @__PURE__ */ new Set());
+  return store;
 }
-function deepTraverse(value, seen) {
-  if (!seen.has(value) && isWrappable(value)) {
+function traverse(value, seen) {
+  let isArray;
+  let proto;
+  if (value != null && typeof value === "object" && !seen.has(value) && ((isArray = Array.isArray(value)) || value[$PROXY] || !(proto = Object.getPrototypeOf(value)) || proto === Object.prototype)) {
     seen.add(value);
-    for (const key in value) {
-      deepTraverse(value[key], seen);
+    for (const child of isArray ? value : Object.values(value))
+      traverse(child, seen);
+  }
+}
+var deepTrack = trackDeep;
+var EQUALS_FALSE = { equals: false };
+var TrackStoreCache = /* @__PURE__ */ new WeakMap();
+var TrackVersion = 0;
+function createLazyMemo(calc) {
+  let isReading = false, isStale = true, alreadyTracked = false, version = 0;
+  const [track, trigger] = createSignal(void 0, EQUALS_FALSE), memo = createMemo(() => isReading ? calc() : isStale = !track(), void 0, {
+    equals: () => alreadyTracked
+  });
+  return () => {
+    isReading = true;
+    if (isStale)
+      isStale = trigger();
+    alreadyTracked = version === TrackVersion;
+    version = TrackVersion;
+    memo();
+    isReading = false;
+  };
+}
+function getTrackStoreNode(node) {
+  let track = TrackStoreCache.get(node);
+  if (!track) {
+    createRoot(() => {
+      const unwrapped = unwrap(node);
+      track = createLazyMemo(() => {
+        node[$TRACK];
+        for (const [key, child] of Object.entries(unwrapped)) {
+          let childNode;
+          if (child != null && typeof child === "object" && ((childNode = child[$PROXY]) || (childNode = untrack(() => node[key])) && $TRACK in childNode)) {
+            getTrackStoreNode(childNode)?.();
+          }
+        }
+      });
+      TrackStoreCache.set(node, track);
+    });
+  }
+  return track;
+}
+function trackStore(store) {
+  TrackVersion++;
+  $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]();
   }
-  return value;
 }
-function isWrappable(obj) {
-  let proto;
-  return obj != null && typeof obj === "object" && (obj[$PROXY] || !(proto = Object.getPrototypeOf(obj)) || proto === Object.prototype || Array.isArray(obj));
+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 };
+export { captureStoreUpdates, deepTrack, trackDeep, trackStore };

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@solid-primitives/deep",
-  "version": "0.0.102",
-  "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": [],
+  "contributors": [
+    "Damian Tarnawski <gthetarnav@gmail.com>"
+  ],
   "license": "MIT",
   "homepage": "https://github.com/solidjs-community/solid-primitives/tree/main/packages/deep#readme",
   "repository": {
@@ -15,16 +17,21 @@
   },
   "primitive": {
     "name": "deep",
-    "stage": 0,
+    "stage": 1,
     "list": [
-      "deepTrack"
+      "trackDeep",
+      "trackStore",
+      "captureStoreUpdates"
     ],
     "category": "Reactivity"
   },
   "keywords": [
     "solid",
     "primitives",
-    "deep"
+    "deep",
+    "store",
+    "reactivity",
+    "delta"
   ],
   "private": false,
   "sideEffects": false,
@@ -43,15 +50,21 @@
     },
     "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": "vite serve dev",
-    "page": "vite build dev",
+    "dev": "jiti ../../scripts/dev.ts",
     "build": "jiti ../../scripts/build.ts",
-    "test": "vitest -c ../../configs/vitest.config.ts",
-    "test:ssr": "pnpm run test --mode ssr"
+    "vitest": "vitest -c ../../configs/vitest.config.ts",
+    "test": "pnpm run vitest",
+    "test:ssr": "pnpm run vitest --mode ssr"
   }
 }