@mmstack/primitives 22.5.0 → 22.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "22.5.0",
+  "version": "22.5.1",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -3024,6 +3024,32 @@ declare function mutableStore<T extends AnyRecord>(value: T, opt?: CreateSignalO
      */
     noUnionLeaves?: boolean;
 }): MutableSignalStore<T>;
+/**
+ * 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.
+ */
+declare function createStoreContext(): toStoreOptions;
 
 /**
  * A 3-way merge of a forked value against a changed base: given the common `ancestor` (the base
@@ -3117,11 +3143,28 @@ type OpBatch = {
     readonly version: number;
     readonly ops: readonly StoreOp[];
 };
+/**
+ * Drives an {@link opLog}'s emission reaction. Given the `run` closure (which reads the source in
+ * a tracking context and flushes the delta), a driver arranges for `run` to execute now and again
+ * on every subsequent change, returning a handle that stops it. The default driver is an Angular
+ * `effect` (needs an injector). Supply a custom driver to run an opLog with NO injector; a
+ * renderer-independent one built on `@angular/core/primitives/signals` `createWatch` ships as
+ * `microtaskOpLogDriver` from `@mmstack/worker/host` (the Web Worker seam).
+ */
+type OpLogDriver = (run: () => void) => {
+    destroy(): void;
+};
 type CreateOpLogOptions = {
     /** Transport identity for emitted batches. Defaults to a random id. */
     readonly origin?: string;
-    /** Injection context for the observing effect (required outside one). */
+    /** Injection context for the default effect-based driver (required outside one). */
     readonly injector?: Injector;
+    /**
+     * Replaces the default Angular-`effect` emission driver. Supply a custom driver (e.g.
+     * `microtaskOpLogDriver` from `@mmstack/worker/host`) to run an opLog with NO injector. When
+     * given, `injector` is ignored and no injection context is required.
+     */
+    readonly driver?: OpLogDriver;
 };
 type OpLog<T extends object> = {
     /**
@@ -3131,6 +3174,15 @@ type OpLog<T extends object> = {
     subscribe(cb: (batch: OpBatch) => void): () => void;
     /** The most recent batch — a lossy sampling view (devtools); use `subscribe` for transport. */
     readonly latest: Signal<OpBatch | null>;
+    /**
+     * Synchronously diff the source and emit any pending change NOW, rather than waiting for the
+     * driver's scheduled run (an app tick, or a custom driver's microtask). Idempotent
+     * and coalescing: writes since the last emission compose into one batch, and a `flush()` with
+     * nothing pending is a no-op. Use it to make emission deterministic — the worker host calls it
+     * to settle its mirror synchronously (tests), and it underpins the flush-before-apply honesty of
+     * {@link OpLog.apply}. Independent of the driver: a later scheduled run simply finds no diff.
+     */
+    flush(): void;
     /**
      * Applies ops (a remote batch, a persisted journal entry, an {@link invertBatch} result)
      * atomically: ONE `set`, one notification wave. Also advances this log's diff baseline in
@@ -3142,6 +3194,21 @@ type OpLog<T extends object> = {
     /** Stops observing and drops subscribers. Also happens when the injection context dies. */
     destroy(): void;
 };
+/**
+ * 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.
+ */
+declare function applyOps<T>(root: T, ops: OpBatch | readonly StoreOp[]): T;
+/**
+ * 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.
+ */
+declare function diffOps(prev: unknown, next: unknown): StoreOp[];
 /**
  * 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
@@ -3174,6 +3241,48 @@ declare function invertBatch(batch: OpBatch | readonly StoreOp[]): StoreOp[];
  */
 declare function opLog<T extends object>(source: WritableSignal<T>, opt?: CreateOpLogOptions): OpLog<T>;
 
+/** Identity selector for keyed array reconciliation: a property name, or a function per item. */
+type ReconcileKey = string | ((item: any) => unknown);
+/**
+ * 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.
+ */
+declare function reconcile<T>(prev: T, next: T, key?: ReconcileKey): T;
+type ProjectionOptions = toStoreOptions & {
+    /** Identity key for reconciling array items (default `'id'`). */
+    readonly key?: ReconcileKey;
+};
+/**
+ * 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.
+ */
+declare function projection<T extends object>(fn: (draft: T) => void | T, seed: T, opt?: ProjectionOptions): SignalStore<T>;
+
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
  * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).
@@ -3632,5 +3741,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-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 type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, LatestSignal, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpLog, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ReconcileFn, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOp, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };
+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 };
+export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, LatestSignal, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpLog, OpLogDriver, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, ReconcileFn, ReconcileKey, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOp, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };