npm package: @sirexelite/pathsignals
Description: A lightweight state manager for React that is optimized for **large apps with many subscriptions**:
Latest version: 1.0.3

# 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

```bash
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)
```function Value() {
  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```:

```import { combine } from "@sirexelite/pathsignals";

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