@mmstack/primitives 21.8.4 → 21.9.0

package/package.json

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

package/types/mmstack-primitives.d.ts

@@ -4180,6 +4180,7 @@ type StoredSignal<T> = WritableSignal<T> & {
  * ```
  */
 declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, validate, pause, injector: providedInjector, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
+declare function isStored<T = unknown>(value: WritableSignal<T>): value is StoredSignal<T>;
 
 /**
  * The cross-tab transport `tabSync` rides. The default is {@link MessageBus} (a `BroadcastChannel`);
@@ -4367,6 +4368,85 @@ declare function toWritable<T>(source: Signal<T>, set: (value: T) => void, updat
     pure?: boolean;
 }): WritableSignal<T>;
 
+/**
+ * A member of the writable-signal family that has been wrapped by {@link traced}.
+ * It carries the full surface of the wrapped signal `S` plus a {@link Traced.causedBy}
+ * read that reports the cause recorded at the most recent write.
+ *
+ * @typeParam S - The wrapped writable-signal type (e.g. `WritableSignal`, `MutableSignal`, `DerivedSignal`).
+ * @typeParam C - The type of the captured cause.
+ */
+type Traced<S extends WritableSignal<unknown>, C> = S & {
+    /**
+     * The cause captured during the most recent synchronous write, or `undefined`
+     * if the last write happened with no ambient cause. This is a plain read, not
+     * a signal — it never creates a reactive dependency and adds zero recomputations.
+     */
+    causedBy(): C | undefined;
+};
+/**
+ * Wraps any member of the writable-signal family so that every synchronous write
+ * first records an ambient "cause" (via the caller-provided `capture` function)
+ * and then delegates to the original write, preserving the wrapped signal's exact
+ * write semantics. The recorded cause is exposed through a plain {@link Traced.causedBy}
+ * read, letting a downstream consumer attribute a change to whatever caused it —
+ * without any dependency on a particular telemetry system.
+ *
+ * Capture is **synchronous-only** and last-writer-wins: the cause is whatever
+ * `capture()` returns during the `set`/`update`/`mutate`/`inline` call. A write
+ * performed after an `await` (once the ambient cause has been cleared) records
+ * `undefined`; a write while `capture()` returns `undefined` clears the cause.
+ * `causedBy()` is a plain read, not a signal — reading it never subscribes, and
+ * a cause-only change (a write with a different cause but no dependent-visible
+ * value change) never invalidates a consumer.
+ *
+ * The traced twin behaves like the original except for `causedBy`: it carries the
+ * wrapped signal's surface — `asReadonly`, the `mutate`/`inline` methods of a
+ * mutable, and the `from` of a derived — and the underlying write semantics survive
+ * (a traced `derived` still writes through to its source; a traced `toWritable` still
+ * runs its custom `set`). Reads through the twin stay tracked — consumers subscribe
+ * exactly as they would to the source.
+ *
+ * @typeParam S - The wrapped writable-signal type.
+ * @typeParam C - The type of the captured cause.
+ *
+ * @param sig - The writable signal to trace. Any family member is accepted
+ *              (`signal`, `mutable`, `derived`, `toWritable`, `stored`, ...).
+ * @param capture - A function invoked synchronously at the start of every write.
+ *                  Its return value becomes the current cause; returning `undefined`
+ *                  clears it.
+ * @param opt - Optional configuration.
+ * @param opt.pure - If `true` (the default), the returned twin is a **new** signal
+ *                   that reads through to `sig`; `sig` itself is left untouched, so
+ *                   tracing a shared signal never makes the original writable or
+ *                   alters its behaviour.
+ *
+ *                   CAUTION: with `pure: false` the write methods are patched
+ *                   directly onto the `sig` object you passed in — every other
+ *                   holder of that signal now records causes on write. Only use it
+ *                   with a signal you created and own exclusively.
+ *
+ * @returns A {@link Traced} twin of `sig` exposing `causedBy()`.
+ *
+ * @example
+ * // A refetch attributing itself to whatever wrote the query.
+ * let activeCause: string | undefined;
+ * const query = traced(signal(''), () => activeCause);
+ *
+ * activeCause = 'user-typed';
+ * query.set('hello');
+ * query.causedBy(); // 'user-typed'
+ *
+ * @example
+ * // Tracing a shared, read-only-exposed signal without making it writable.
+ * const shared = signal(0);
+ * const twin = traced(shared, () => currentInteraction());
+ * twin === shared; // false — the original is untouched
+ */
+declare function traced<S extends WritableSignal<unknown>, C>(sig: S, capture: () => C | undefined, opt?: {
+    pure?: boolean;
+}): Traced<S, C>;
+
 type UntilOptions = {
     /**
      * Optional timeout in milliseconds. If the condition is not met
@@ -4517,5 +4597,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { CONCURRENCY_INSTRUMENTATION, MmActivity, MmTransition, MmViewTransitionName, OP_PROTO_VERSION, PAUSABLE_OPTIONS, PERSISTED_STORE_OPTIONS, POS_SEGMENT, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, compareHlc, compareSiblings, compareTotal, createAttributedPending, createConvergingApply, createForwardingScope, createHlcClock, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, defaultFold, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, insertElement, invertBatch, isConflicted, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, keyedArray, latest, lww, map, mapArray, mapObject, mediaQuery, merge3, mergeThree, mousePosition, moveElement, mutable, mutableStore, nestedEffect, networkStatus, opLog, opSync, opaque, orderedEntries, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, perfCustomTracks, persist, persistedStore, pipeable, piped, pointerDrag, policyStrategy, pooled, pooledArray, pooledMap, pooledSet, posBetween, prefersDarkMode, prefersReducedMotion, preserve, projection, provideConcurrencyInstrumentation, provideForwardingTransitionScope, providePausableOptions, providePaused, providePersistedStoreOptions, provideTransitionScope, rebalanceContainer, rebaseOps, reconcile, registerResource, removeElement, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, storeHistory, stored, syncedFork, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, validateEnvelope, windowSize, withHistory };
-export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ContainerNode, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, Dot, DotFrontier, DuplicateKeyPolicy, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, FoldFn, FoldPolicyEntry, FoldResult, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncCheckpoint, OpSyncOptions, Opaque, OrderedEntry, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterCheckpoint, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncOp, SyncSibling, SyncSignalOptions, SyncedFork, TabSyncBus, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };
+export { CONCURRENCY_INSTRUMENTATION, MmActivity, MmTransition, MmViewTransitionName, OP_PROTO_VERSION, PAUSABLE_OPTIONS, PERSISTED_STORE_OPTIONS, POS_SEGMENT, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, compareHlc, compareSiblings, compareTotal, createAttributedPending, createConvergingApply, createForwardingScope, createHlcClock, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, defaultFold, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, insertElement, invertBatch, isConflicted, isDerivation, isLeaf, isMutable, isOpaque, isStore, isStored, keepPrevious, keyArray, keyedArray, latest, lww, map, mapArray, mapObject, mediaQuery, merge3, mergeThree, mousePosition, moveElement, mutable, mutableStore, nestedEffect, networkStatus, opLog, opSync, opaque, orderedEntries, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, perfCustomTracks, persist, persistedStore, pipeable, piped, pointerDrag, policyStrategy, pooled, pooledArray, pooledMap, pooledSet, posBetween, prefersDarkMode, prefersReducedMotion, preserve, projection, provideConcurrencyInstrumentation, provideForwardingTransitionScope, providePausableOptions, providePaused, providePersistedStoreOptions, provideTransitionScope, rebalanceContainer, rebaseOps, reconcile, registerResource, removeElement, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, storeHistory, stored, syncedFork, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, traced, until, use, validateEnvelope, windowSize, withHistory };
+export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ContainerNode, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, Dot, DotFrontier, DuplicateKeyPolicy, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, FoldFn, FoldPolicyEntry, FoldResult, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncCheckpoint, OpSyncOptions, Opaque, OrderedEntry, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterCheckpoint, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncOp, SyncSibling, SyncSignalOptions, SyncedFork, TabSyncBus, ThrottledSignal, Traced, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };