@solid-primitives/deep 0.0.102 → 0.1.0

package/README.md

@@ -7,9 +7,12 @@
 [![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 changes in stores.
+
+- [`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.
 
 ## Installation
 
@@ -21,31 +24,80 @@ 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] = createSignal({ 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] = createSignal({ name: "John", age: 42 });
+
+createEffect(() => {
+  trackStore(state);
+  /* execute some logic whenever the state changes */
+});
+```
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md)

package/dist/index.cjs

@@ -1,23 +1,65 @@
 'use strict';
 
 var solidJs = require('solid-js');
+var store = require('solid-js/store');
 
-// 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);
   }
-  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));
+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(value) {
+  let track = TrackStoreCache.get(value);
+  if (!track) {
+    solidJs.createRoot(() => {
+      const unwrapped = store.unwrap(value);
+      track = createLazyMemo(() => {
+        value[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)?.();
+          }
+        }
+      });
+      TrackStoreCache.set(value, track);
+    });
+  }
+  return track;
+}
+function trackStore(store) {
+  TrackVersion++;
+  solidJs.$TRACK in store && getTrackStoreNode(store)?.();
+  return store;
 }
 
-exports.deepTrack = deepTrack;
+exports.trackDeep = trackDeep;
+exports.trackStore = trackStore;

package/dist/index.d.ts

@@ -1,27 +1,47 @@
 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:
+ * @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
  *
- * ```typescript
- * createEffect(
- *     on(
- *         deepTrack(store),
- *         () => {
- *            // this effect will run when any property of store changes
- *         }
- *     )
+ * @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 deepTrack<T>(store: Store<T>): T;
+declare function trackStore<T extends object>(store: Store<T>): T;
 
-export { deepTrack };
+export { deepTrack, trackDeep, trackStore };

package/dist/index.js

@@ -1,21 +1,62 @@
-import { $PROXY } from 'solid-js';
+import { $PROXY, $TRACK, createRoot, createSignal, createMemo, untrack } from 'solid-js';
+import { unwrap } from 'solid-js/store';
 
-// 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);
   }
-  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 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(value) {
+  let track = TrackStoreCache.get(value);
+  if (!track) {
+    createRoot(() => {
+      const unwrapped = unwrap(value);
+      track = createLazyMemo(() => {
+        value[$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)?.();
+          }
+        }
+      });
+      TrackStoreCache.set(value, track);
+    });
+  }
+  return track;
+}
+function trackStore(store) {
+  TrackVersion++;
+  $TRACK in store && getTrackStoreNode(store)?.();
+  return store;
 }
 
-export { deepTrack };
+export { deepTrack, trackDeep, trackStore };

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@solid-primitives/deep",
-  "version": "0.0.102",
+  "version": "0.1.0",
   "description": "Deep trigger effects for Stores.",
   "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,19 @@
   },
   "primitive": {
     "name": "deep",
-    "stage": 0,
+    "stage": 1,
     "list": [
-      "deepTrack"
+      "trackDeep",
+      "trackStore"
     ],
     "category": "Reactivity"
   },
   "keywords": [
     "solid",
     "primitives",
-    "deep"
+    "deep",
+    "store",
+    "reactivity"
   ],
   "private": false,
   "sideEffects": false,
@@ -48,10 +53,10 @@
   },
   "typesVersions": {},
   "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"
   }
 }