@mmstack/primitives 22.5.0 → 22.5.1

package/README.md

@@ -17,7 +17,7 @@ npm install @mmstack/primitives
 
 - [Writable signal variants](#writable-signal-variants) — `mutable`, `derived`, `store` / `mutableStore`, `forkStore`, `toWritable`
 - [Timing & propagation](#timing--propagation) — `debounced`, `throttled`, `until`
-- [Reactive collections](#reactive-collections) — `indexArray`, `keyArray`, `mapObject`
+- [Reactive collections](#reactive-collections) — `indexArray`, `keyArray`, `mapObject`, `projection`
 - [Effects](#effects) — `nestedEffect`
 - [Concurrency & transitions](#concurrency--transitions) — `keepPrevious`, keep-alive (`MmActivity`), `pausable*` / `providePausableOptions`, Suspense (`mm-suspense`), hold-and-swap (`*mmTransition`), per-element morphs (`mmViewTransitionName`), async derivations (`latest` / `use`), `deferredValue`, `startTransition` / `startTransaction`, `holdUntilReady`
 - [History & persistence](#history--persistence) — `withHistory`, `stored`, `tabSync`, `opLog`
@@ -303,6 +303,32 @@ const controls = mapObject(
 );
 ```
 
+### `projection`
+
+A derived **store**, the store-shaped counterpart to `computed`. Where `derived` slices one value out of a source and `indexArray` / `keyArray` map a list, `projection` derives a whole store subtree from a computation. `fn` receives a mutable draft seeded with the current value and either mutates it or returns new data; the result is reconciled against the previous value so unchanged object subtrees keep their reference and keyed array items keep their identity across recomputes. Reading through the returned store is per-leaf, so a `computed` over one field only recomputes when that field actually changes, even though the whole projection re-ran.
+
+```typescript
+import { projection } from '@mmstack/primitives';
+
+const users = signal<User[]>([]);
+
+// return form: derive a filtered collection, reconciled by id
+const active = projection<User[]>(() => users().filter((u) => u.active), [], {
+  key: 'id',
+});
+
+// mutate form: update fields on the draft
+const summary = projection<{ total: number; active: number }>(
+  (draft) => {
+    draft.total = users().length;
+    draft.active = users().filter((u) => u.active).length;
+  },
+  { total: 0, active: 0 },
+);
+```
+
+Recompute is pull-based, exactly like `computed`: memoized, re-run on the first read after a dependency changes, coherent immediately after a write (no waiting on an effect flush), and skipped entirely while nobody reads. `fn` must be pure since it runs inside the reactive computation. Prefer `computed` for a plain value, and reach for `projection` when you want the per-property tracking of a store on top of a derivation. The standalone `reconcile(prev, next, key)` is exported too, for producing a reference-stable value by hand. Values must be structured-clonable (the draft is a clone of the current value). With an explicit store context (`createStoreContext()`) a projection is injector-free, so it also runs on a worker host.
+
 ## Effects
 
 ### `nestedEffect`
@@ -681,6 +707,7 @@ log.latest(); // Signal<OpBatch | null> — lossy sampling (devtools-style)
 state.user.name.set('Bea');
 // → { origin, version, ops: [{ kind: 'set', path: ['user','name'], next: 'Bea', prev: 'Ann' }] }
 
+log.flush(); // synchronously emit any pending change now, instead of waiting for the tick. idempotent, no-op when clean.
 log.apply(remoteBatch); // applies ops in ONE commit AND advances the diff baseline —
 // so applying a remote batch emits no echo batch (sync loops terminate by construction)
 invertBatch(batch); // prev-based inverse — undo is a data transform
@@ -688,6 +715,8 @@ invertBatch(batch); // prev-based inverse — undo is a data transform
 
 Batching is per tick (two writes to one leaf in a tick emit one composed op), `prev` is always carried in-memory (structural sharing makes it free — wire serializers decide whether to keep it), arrays diff per-index at equal lengths and as whole-array ops on length change, and a `forkStore`'s `commit()` lands as a single batch — fork *is* the transaction primitive. Mutable stores are unsupported (in-place mutation defeats ref-identity diffing; dev warn). This is the substrate for worker mirrors, tab/mesh sync, persistence journals, and undo — one protocol, many consumers.
 
+An `opLog` can also run with no Angular injector, which is what lets the graph mirror into a Web Worker. Pass `driver: microtaskOpLogDriver()` to drive emission off the microtask queue instead of an `effect()`, and build the store with `createStoreContext()` (a self-contained proxy cache) so `store` and `opLog` work in a worker or a plain Node process. The pure helpers `applyOps(root, ops)` and `diffOps(prev, next)` apply and produce batches without owning a log. [`@mmstack/worker`](https://www.npmjs.com/package/@mmstack/worker) is built directly on these seams.
+
 ## Performance helpers
 
 ### `chunked`

package/fesm2022/mmstack-primitives.mjs

@@ -4296,7 +4296,11 @@ function buildChildNode(target, prop, isMutableSource, options) {
 function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...rest } = {}) {
     if (isStore(source))
         return source;
-    if (!injector)
+    // injector is needed ONLY to resolve the two proxy-globals tokens; if a caller supplies the
+    // globals directly (createStoreContext — the worker-side seam with no DI), skip inject entirely
+    const sharedGlobals = rest[STORE_SHARED_GLOBALS];
+    const hasSharedGlobals = !!(sharedGlobals?.cache && sharedGlobals?.registry);
+    if (!injector && !hasSharedGlobals)
         injector = inject(Injector);
     const writableSource = isWritableSignal(source)
         ? source
@@ -4315,13 +4319,18 @@ function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...r
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "kind" }] : /* istanbul ignore next */ []));
     const STORE_OPTIONS = {
-        injector,
+        // may be undefined in worker/DI-less mode; unused downstream once globals are resolved
+        // (children thread the resolved globals via STORE_SHARED_OPTIONS, derived needs no injector)
+        injector: injector,
         vivify,
         noUnionLeaves,
         [STORE_SHARED_GLOBALS]: {
-            cache: rest[STORE_SHARED_GLOBALS]?.cache ?? injector.get(PROXY_CACHE_TOKEN),
-            registry: rest[STORE_SHARED_GLOBALS]?.registry ??
-                injector.get(PROXY_CLEANUP_TOKEN),
+            // the `injector!` reads run only when a global is absent, which (per hasSharedGlobals) means
+            // an injector was resolved above
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            cache: sharedGlobals?.cache ?? injector.get(PROXY_CACHE_TOKEN),
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            registry: sharedGlobals?.registry ?? injector.get(PROXY_CLEANUP_TOKEN),
         },
     };
     // built lazily so non-array nodes never allocate it
@@ -4393,7 +4402,14 @@ function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...r
                 return () => {
                     if (!isWritableSource)
                         return s;
-                    return untracked(() => toStore(source.asReadonly(), { injector, vivify, noUnionLeaves }));
+                    return untracked(() => toStore(source.asReadonly(), {
+                        injector,
+                        vivify,
+                        noUnionLeaves,
+                        // forward the resolved globals — re-resolving from the injector both re-injects
+                        // needlessly and breaks in DI-less (worker) mode where injector is undefined
+                        [STORE_SHARED_GLOBALS]: STORE_OPTIONS[STORE_SHARED_GLOBALS],
+                    }));
                 };
             const k = untracked(kind);
             if (prop === 'extend' && k !== 'array')
@@ -4559,6 +4575,40 @@ function mutableStore(value, opt) {
         ...opt,
     });
 }
+/**
+ * Builds a DI-less store context — the shared proxy-cache and cleanup registry that {@link toStore}
+ * normally resolves from the injector — so a `store`/`toStore`/`opLog` graph can run with NO Angular
+ * injection context. Spread the result into the options:
+ *
+ * ```ts
+ * import { microtaskOpLogDriver } from '@mmstack/worker/host';
+ * const ctx = createStoreContext();
+ * const s = store({ todos: [] }, ctx);
+ * const log = opLog(s, { driver: microtaskOpLogDriver(), origin: 'worker' }); // no injector anywhere
+ * ```
+ *
+ * **This is a worker-only fallback — do NOT use it on the main thread.** DI is the default and
+ * correct path in an app: the injector scopes the proxy-cache/cleanup singletons per app instance,
+ * which on the SERVER keeps one request's store identity from bleeding into another's (the exact
+ * hazard a module-scope singleton would reintroduce). A Web Worker is safe because it is a single
+ * store graph per thread and never runs during SSR (spawn is a `PLATFORM_ID === 'server'` no-op),
+ * so there is no cross-request scope to contaminate. Never hoist a `createStoreContext()` to module
+ * scope on a shared/main thread.
+ *
+ * **Share ONE context across every store in a worker** — the same way `providedIn: 'root'` shares
+ * one cache across all of an app's stores. `@mmstack/worker/host` memoizes this per worker
+ * (`workerStoreContext()`); reach for `createStoreContext()` directly only in a bare
+ * (non-worker-host) DI-less setup, and hold the single instance yourself.
+ */
+function createStoreContext() {
+    const cache = new WeakMap();
+    const registry = new FinalizationRegistry(({ target, prop }) => {
+        const entry = cache.get(target);
+        if (entry)
+            entry.delete(prop);
+    });
+    return { [STORE_SHARED_GLOBALS]: { cache, registry } };
+}
 
 function isPlainRecord(value) {
     if (value === null || typeof value !== 'object')
@@ -4638,7 +4688,7 @@ function generateOrigin() {
         return globalThis.crypto.randomUUID();
     return Math.random().toString(36).substring(2);
 }
-const isPlainArray = (v) => Array.isArray(v) && !isOpaque(v);
+const isPlainArray$1 = (v) => Array.isArray(v) && !isOpaque(v);
 /**
  * Reference-identity-pruned structural diff — the same short-circuit discipline as `merge3`:
  * an untouched subtree kept its reference (the store's copy-on-write contract), so the walk
@@ -4663,7 +4713,7 @@ function diffNode(prev, next, path, ops) {
         }
         return;
     }
-    if (isPlainArray(prev) && isPlainArray(next)) {
+    if (isPlainArray$1(prev) && isPlainArray$1(next)) {
         // same length → per-index descent (matches `arr[i].x.set(...)` writes); a length
         // change is a whole unit — index attribution lies under insert/remove/reorder
         if (prev.length === next.length) {
@@ -4680,7 +4730,7 @@ function diffNode(prev, next, path, ops) {
 /** Immutably applies one op along its path, vivifying missing containers `'auto'`-style. */
 function applyAt(container, path, idx, op) {
     const seg = path[idx];
-    const base = isPlainArray(container)
+    const base = isPlainArray$1(container)
         ? container.slice()
         : isRecord(container)
             ? { ...container }
@@ -4700,6 +4750,37 @@ function applyAt(container, path, idx, op) {
     base[seg] = applyAt(base[seg], path, idx + 1, op);
     return base;
 }
+/**
+ * Pure, store-free application of ops onto a plain root value, returning the next immutable root
+ * (structural-sharing along op paths, missing containers vivified `'auto'`-style). This is the
+ * same transform {@link OpLog.apply} runs, extracted so a replica can fold a received batch into
+ * a value WITHOUT owning a diffing {@link opLog} — e.g. the worker-graph read-replica seam.
+ * Accepts a batch or a bare op list.
+ */
+function applyOps(root, ops) {
+    const list = Array.isArray(ops) ? ops : ops.ops;
+    let next = root;
+    for (const op of list) {
+        if (op.path.length === 0) {
+            if (op.kind === 'set')
+                next = op.next;
+            continue; // a root delete is meaningless — ignore (mirrors OpLog.apply)
+        }
+        next = applyAt(next, op.path, 0, op);
+    }
+    return next;
+}
+/**
+ * Pure reference-pruned structural diff of two roots into minimal ops (the emission core of
+ * {@link opLog}, exported so code outside a log can produce a batch — e.g. diffing a scratch
+ * draft against a replica's current value to route a write to its owner). Trusts the
+ * copy-on-write contract: an untouched subtree that kept its reference is skipped.
+ */
+function diffOps(prev, next) {
+    const ops = [];
+    diffNode(prev, next, [], ops);
+    return ops;
+}
 /**
  * Inverts a batch for undo: reversed order, `set`↔its own inverse (an add — a `set` with no
  * `prev` — inverts to a `delete`; a `delete` inverts to a `set` restoring `prev`). Feed the
@@ -4712,14 +4793,24 @@ function invertBatch(batch) {
     for (let i = ops.length - 1; i >= 0; i--) {
         const op = ops[i];
         if (op.kind === 'delete') {
-            inverted.push({ kind: 'set', path: op.path, next: op.prev, prev: undefined });
+            inverted.push({
+                kind: 'set',
+                path: op.path,
+                next: op.prev,
+                prev: undefined,
+            });
             continue;
         }
         if (!Object.hasOwn(op, 'prev')) {
             inverted.push({ kind: 'delete', path: op.path, prev: op.next });
         }
         else {
-            inverted.push({ kind: 'set', path: op.path, next: op.prev, prev: op.next });
+            inverted.push({
+                kind: 'set',
+                path: op.path,
+                next: op.prev,
+                prev: op.next,
+            });
         }
     }
     return inverted;
@@ -4748,7 +4839,6 @@ function invertBatch(batch) {
  * ```
  */
 function opLog(source, opt) {
-    const injector = opt?.injector ?? inject(Injector);
     const origin = opt?.origin ?? generateOrigin();
     // a store proxy's `has` trap answers for the VALUE's keys, so `isMutable`'s `'mutate' in`
     // probe can't see the brand — ask the store's own kind symbol first
@@ -4780,16 +4870,24 @@ function opLog(source, opt) {
         for (const cb of [...subscribers])
             cb(batch);
     };
-    const ref = effect(() => {
+    const run = () => {
         source(); // track every commit…
         untracked(flush); // …and emit the delta since the last flush
-    }, { ...(ngDevMode ? { debugName: "ref" } : /* istanbul ignore next */ {}), injector: opt?.injector });
+    };
+    // default driver is an Angular effect (needs an injector); a supplied driver runs injector-free
+    // (the worker-side seam, e.g. microtaskOpLogDriver from @mmstack/worker/host)
+    const ref = opt?.driver
+        ? opt.driver(run)
+        : effect(run, { injector: opt?.injector ?? inject(Injector) });
     return {
         latest: latest.asReadonly(),
         subscribe: (cb) => {
             subscribers.add(cb);
             return () => subscribers.delete(cb);
         },
+        // the emission core, callable on demand — reads the source untracked, so it never disturbs the
+        // driver's subscription; a subsequent scheduled run just finds the baseline already advanced
+        flush: () => flush(),
         apply: (batchOrOps) => {
             const ops = Array.isArray(batchOrOps)
                 ? batchOrOps
@@ -4798,15 +4896,7 @@ function opLog(source, opt) {
                 return;
             // pending local writes must emit BEFORE the baseline advances past them
             flush();
-            let root = untracked(source);
-            for (const op of ops) {
-                if (op.path.length === 0) {
-                    if (op.kind === 'set')
-                        root = op.next;
-                    continue; // a root delete is meaningless — ignore
-                }
-                root = applyAt(root, op.path, 0, op);
-            }
+            const root = applyOps(untracked(source), ops); // one atomic root, structural-shared
             source.set(root);
             prevRoot = root; // baseline advance: an applied batch never echoes
         },
@@ -4818,6 +4908,98 @@ function opLog(source, opt) {
     };
 }
 
+const isPlainArray = (v) => Array.isArray(v) && !isOpaque(v);
+function keyOf(item, key) {
+    if (typeof key === 'function')
+        return key(item);
+    return isRecord(item) ? item[key] : item;
+}
+/**
+ * Produces a value equal to `next` but sharing as much of `prev`'s reference structure as possible:
+ * an object subtree that did not change keeps its `prev` reference, and array items are matched by
+ * `key` so a surviving item keeps its identity across a reorder/insert/remove (only added items are
+ * new, only removed items are dropped). This is what lets a derived store recompute without tearing
+ * down every downstream `computed` that reads an unchanged part of it.
+ */
+function reconcile(prev, next, key = 'id') {
+    return reconcileValue(prev, next, key);
+}
+function reconcileValue(prev, next, key) {
+    if (Object.is(prev, next))
+        return prev;
+    if (isPlainArray(prev) && isPlainArray(next)) {
+        const byKey = new Map();
+        for (const item of prev)
+            byKey.set(keyOf(item, key), item);
+        let changed = prev.length !== next.length;
+        const out = next.map((item, i) => {
+            const match = byKey.get(keyOf(item, key));
+            const rv = match !== undefined ? reconcileValue(match, item, key) : item;
+            if (rv !== prev[i])
+                changed = true;
+            return rv;
+        });
+        return changed ? out : prev;
+    }
+    if (isRecord(prev) && isRecord(next)) {
+        const nextKeys = Object.keys(next);
+        let changed = Object.keys(prev).length !== nextKeys.length;
+        const out = {};
+        for (const k of nextKeys) {
+            const rv = Object.hasOwn(prev, k)
+                ? reconcileValue(prev[k], next[k], key)
+                : next[k];
+            out[k] = rv;
+            if (rv !== prev[k])
+                changed = true;
+        }
+        return changed ? out : prev;
+    }
+    return next;
+}
+/**
+ * A derived STORE, the store-shaped counterpart to `computed`. `fn` receives a mutable draft seeded
+ * with the current value and either mutates it in place or returns a new value; whichever it does,
+ * the result is reconciled against the previous value (see {@link reconcile}) so unchanged subtrees
+ * keep reference identity and keyed array items keep their proxy identity. Reading through the
+ * returned store is fine-grained: a `computed` over one field only recomputes when that field
+ * actually changes, even though the whole projection re-ran.
+ *
+ * Recompute is pull-based, exactly like `computed`: the projection is memoized and re-runs on the
+ * first read after a signal `fn` depends on changes, so reads are always coherent (no waiting on an
+ * effect flush) and nothing recomputes while nobody reads. `fn` must be pure, it runs inside the
+ * reactive computation. Prefer `computed` for a plain value; reach for `projection` when you want
+ * the per-property tracking of a store on top of a derivation.
+ *
+ * ```ts
+ * const active = projection<User[]>(() => users().filter((u) => u.active), [], { key: 'id' });
+ * // active[0].name(); — surviving users keep identity across recomputes
+ * ```
+ *
+ * Needs an injection context (or an explicit `injector`) for the store layer's cleanup on the main
+ * thread; with an explicit store context (`createStoreContext()`) it is injector-free, so it also
+ * runs on a worker host.
+ *
+ * @param fn receives the current draft; mutate it, or return new data.
+ * @param seed the initial value, held before the first run.
+ */
+function projection(fn, seed, opt) {
+    const { key = 'id', ...storeOpt } = opt ?? {};
+    // linkedSignal rather than an effect-driven signal: the computation runs in the tracked
+    // context (fn's reads are dependencies) and `previous` hands back the last emitted value for
+    // the reconcile, so the projection is glitch-free, lazy, and needs no effect scheduler.
+    const root = linkedSignal({ ...(ngDevMode ? { debugName: "root" } : /* istanbul ignore next */ {}), source: () => undefined,
+        computation: (_, previous) => {
+            const base = previous ? previous.value : seed;
+            // a plain mutable scratch seeded with the current value; fn mutates it or returns new data
+            const draft = structuredClone(base);
+            const returned = fn(draft);
+            const next = (returned === undefined ? draft : returned);
+            return reconcile(base, next, key);
+        } });
+    return toStore(root, storeOpt).asReadonlyStore();
+}
+
 /**
  * @internal The plain-`effect` sibling of the public {@link pausableEffect} (which is built on
  * `nestedEffect`). For infra utilities that own a single top-level effect/subscription and don't
@@ -5346,5 +5528,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { MmActivity, MmTransition, MmViewTransitionName, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, deferredValue, derived, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, invertBatch, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, latest, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opLog, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, windowSize, withHistory };
+export { MmActivity, MmTransition, MmViewTransitionName, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, invertBatch, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, latest, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opLog, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, projection, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, reconcile, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map