@solid-primitives/deep

Primitives for tracking and observing nested reactive objects in Solid.

• trackDeep - Tracks all properties of a store by iterating over them recursively.
• trackStore - A more performant alternative to trackDeep utilizing specific store implementations.
• captureStoreUpdates - A utility function that captures all updates to a store and returns them as an array.

Installation

npm install @solid-primitives/deep
# or
yarn add @solid-primitives/deep
# or
pnpm add @solid-primitives/deep

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 call this function with any store under a tracking scope and it will iterate over all properties of the store and track them.

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.

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.

createEffect(() => {
  // will also work:
  trackDeep({ myStore: state });
});

Warning If you unwrap a store, it will no longer be tracked by trackDeep nor trackStore!

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.

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 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.

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), so it can be used inside a tracking scope.

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:

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.

Changelog

See CHANGELOG.md