Deep

Primitives for tracking and observing nested reactive objects.

npm i @solid-primitives/deep@next

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.

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:

import { deep } from "solid-js";

createEffect(
  () => deep(store),
  snapshot => localStorage.setItem("state", JSON.stringify(snapshot)),
);

This package complements that with three distinct utilities:

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.

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(
  () => 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.

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

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

import { snapshot } from "solid-js";

const plain = snapshot(state);

createEffect(
  () => trackDeep(plain), // This will NOT work — plain objects are not reactive
  () => {},
);

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(s => {
  s.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(
  () => 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.

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(
  () => delta(),
  value => console.log(value),
);
createEffect(
  () => delta(),
  value => console.log(value),
);

Changelog

See CHANGELOG.md