Overview

A lightweight state manager for React that is optimized for large apps with many subscriptions:

• Copy-On-Write (COW) updates via store.update(draft => { ... })
• Path-based routing: notify only listeners that care about the changed path (not “everyone”)
• useStore automatically derives subscriptions via read tracking (Proxy on reads)
• For complex selectors you can declare deps explicitly via combine(deps, fn)

Problem

In large React applications with complex global state:

• small state updates cause many unrelated components to rerender
• subscriptions become hard to reason about
• selector-based optimizations are fragile and implicit
• performance issues appear only in production-scale data

Why PathSignals

PathSignals routes updates by state paths, not by global change detection. Components rerender only when the exact parts of state they read change.

Install

npm i @sirexelite/pathsignals

Quick start

Create a store

import { createStore, createActions } from "@sirexelite/pathsignals";

type State = {
  count: number;
  a: number;
  b: { c: number; d: number };
  tags: string[];
};

export const store = createStore<State>({
  a: 0,
  b: { c: 1, d: 2 },
  tags: ["x"],
});
export const actions = createActions(store, {
  inc(draft, by: number) { draft.count += by; },
  reset(draft) { draft.count = 0; },
});

Update state (COW draft)

store.update(draft => {
  draft.b.c += 1;
  draft.a = 10;
});

Subscribe (redux-style: any change)

const unsub = store.subscribe(() => {
  console.log("anything changed", store.getState());
});

// later:
unsub();

Subscribe by path (precise)

const unsub = store.subscribePath(["b", "c"], () => {
  console.log("b.c changed");
}, "exact");

// later:
unsub();

React usage

useStore with a bound store

import { store, actions } from "./setup";
import type { State } from "./setup";

const useAppStore = createSelectorWithStore(store);

function Counter() {
  const c = useAppStore(s => s.b.c);
  return <div>{c}</div>;
}

const useAction = createUseActionWithState<State, typeof actions>(store);
const useAct = createUseActionWithState<State, typeof actions>(store);
const useActs = createUseActionsWithState<State, typeof actions>(store);

function Btn() {
  const inc = useAct("inc");       // (by: number) => void
  const reset = useAct("reset");   // () => void
  return (
    <>
      <button onClick={() => inc(1)}>+1</button>
      <button onClick={() => reset()}>reset</button>
    </>
  );
}

function Toolbar() {
  const a = useActs(); // { inc, reset }
  return <button onClick={() => a.inc(5)}>+5</button>;
}

useStore will:

• run the selector against a read-proxy to collect read paths (deps)
• subscribe to those paths via subscribePath(..., "exact")
• rerender only when the relevant paths change

Conditional selectors (deps change over time)

  const v = useAppStore(s => (s.a === 0 ? s.b.c : s.b.d));
  return <div>{v}</div>;
}

When the condition changes what the selector reads, useStore will recompute deps and resubscribe.

combine(deps, fn) for complex selectors

When a selector is expensive (loops, searching, filtering), or you want explicit control over deps, use combine:

const sum = combine(
  [["b", "c"], ["b", "d"]] as const,
  (c, d) => c + d
);

// React:
const v = useAppStore(sum);

When combine is especially useful

• selector performs loops/filter/search and you want to avoid proxy read-tracking overhead
• you know exactly which paths matter
• you want to avoid “selector may run twice” (read-tracking + real state)

Rules and limitations (important)

1) Only mutate state via store.update

Do not mutate store.getState() directly.

❌ Wrong:

store.getState().b.c = 123; // store won't know, no notifications

✅ Correct:

store.update(d => { d.b.c = 123; });

2) Selectors must be pure (read-only)

Selectors may run against a read-proxy to collect deps. They must not write.

❌ Wrong:

useAppStore(s => {
  s.a = 1;      // throws
  return s.a;
});

✅ Correct:

useAppStore(s => s.a);

3) No shared references (same object in multiple branches)

Path-based routing assumes one object belongs to one logical place in the tree. If the same object reference is reachable via multiple paths, change tracking becomes ambiguous.

In dev mode this is detected and throws.

❌ Wrong:

const shared = { x: 1 };
createStore({ a: shared, b: shared }); // dev: error during draft usage

✅ Correct:

createStore({ a: { x: 1 }, b: { x: 1 } });

4) Arrays policy: primitive arrays only

Arrays in state must contain only primitives:

• string | number | boolean | null | undefined | bigint | symbol

✅ Allowed:

tags: ["a", "b"]
ids: [1, 2, 3]

❌ Forbidden:

items: [{ id: 1 }, { id: 2 }] // dev: throws

How to store “array of objects”

Use normalization:

type State = {
  users: {
    byId: Record<string, User>;
    ids: string[];
  }
}

5) Array mutations are treated as “array path changed”

If you write tags[i] or do push/pop/splice, it is treated as a change of the whole array path ["tags"].

Subscribing to individual array elements is not supported by design.

6) "exact" vs "deep" subscription modes

• "exact" — subscribe to a specific path
• "deep" — subscribe to a path and any descendant changes (useful for tools/logging/dev)

useStore uses "exact".

Recommendation:

• UI components: use "exact"
• tooling/global listeners: use "deep"

State modeling recommendations

For big collections, normalize

✅ Preferred:

{
  messages: {
    byId: Record<string, Message>;
    ids: string[];
  }
}

Benefits:

• updating one entity only wakes subscriptions for that byId[id] subtree
• ids changes separately and typically less frequently

Performance notes

• Leaf updates clone only the container chain to root (COW)
• Notifications route by trie paths, not by iterating all subscribers
• In React, normally only the components that read changed paths rerender

Dev vs Prod

createStore(initial, { dev: true }) enables:

• shared reference detection
• array policy checks (no complex elements)

In production you typically want:

createStore(initial, { dev: false })

FAQ

Why can a selector run twice?

If you do not use combine, useStore may:

1. run selector on a read-proxy to collect deps
2. run selector on the real state to compute value

If that matters for a specific selector, use combine(deps, fn).

Why forbid arrays of objects?

Subscribing to array elements causes path explosion and expensive update logic. Primitive arrays + normalized object collections keep routing predictable and fast.

Benchmark

React hook benchmarks (useStore) — update-only
  name                                                               hz      min      max     mean      p75      p99     p995     p999      rme  samples
· mount 2000 subscribers (single root)                          26.7227  31.7558  58.8020  37.4213  36.1713  58.8020  58.8020  58.8020  ±15.65%       10
· 2000 subscribers mounted -> update 1 leaf (update-only)      1,815.88   0.4863   3.6128   0.5507   0.5278   1.7170   3.6128   3.6128   ±6.73%      182
· teardown                                                 1,154,538.18   0.0007   0.0034   0.0009   0.0009   0.0017   0.0020   0.0025   ±1.18%     1155

Store benchmarks (routing/update only)
  name                                                                    hz     min     max    mean     p75     p99    p995    p999      rme  samples
· routing: 10k leaf subscriptions -> 1 leaf update (update-only)      308.56  2.9479  5.6728  3.2409  3.1977  5.6728  5.6728  5.6728   ±6.23%       31
· COW: deep leaf write (depth=30) update-only                      17,403.35  0.0433  5.5667  0.0575  0.0478  0.1640  0.2429  0.6212  ±11.13%     1741
· arrays: push+pop (stable size) update-only                      108,057.73  0.0073  0.4722  0.0093  0.0090  0.0216  0.0269  0.1090   ±1.83%    10806