@mmstack/primitives 20.15.3 → 20.16.0

package/index.d.ts

@@ -1244,6 +1244,15 @@ declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterF
     bindToFrame?: (parent: Frame | null) => Frame | null;
 }): EffectRef;
 
+/**
+ * Options for {@link keepPrevious}: the signal options of the held value, plus
+ * `fallback` — what to yield while there is nothing to hold yet (the source has
+ * never been defined). Once a defined value has been seen the fallback is never
+ * yielded again; the previous value is.
+ */
+type KeepPreviousOptions<T> = CreateSignalOptions<T> & {
+    readonly fallback?: T;
+};
 /**
  * Wraps a signal so it HOLDS its last defined value whenever the source becomes
  * `undefined`, yielding that value instead of the gap. This is the foundation of
@@ -1257,10 +1266,10 @@ declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterF
  * so it stays a drop-in replacement. (Angular's `resource` is itself linkedSignal-backed
  * and exposes a writable `value` for optimistic updates; this preserves that.)
  */
-declare function keepPrevious<T>(value: MutableSignal<T>, opt?: CreateSignalOptions<T>): MutableSignal<T>;
-declare function keepPrevious<T, U>(value: DerivedSignal<T, U>, opt?: CreateSignalOptions<U>): DerivedSignal<T, U>;
-declare function keepPrevious<T>(value: WritableSignal<T>, opt?: CreateSignalOptions<T>): WritableSignal<T>;
-declare function keepPrevious<T>(value: Signal<T>, opt?: CreateSignalOptions<T>): Signal<T>;
+declare function keepPrevious<T>(value: MutableSignal<T>, opt?: KeepPreviousOptions<T>): MutableSignal<T>;
+declare function keepPrevious<T, U>(value: DerivedSignal<T, U>, opt?: KeepPreviousOptions<U>): DerivedSignal<T, U>;
+declare function keepPrevious<T>(value: WritableSignal<T>, opt?: KeepPreviousOptions<T>): WritableSignal<T>;
+declare function keepPrevious<T>(value: Signal<T>, opt?: KeepPreviousOptions<T>): Signal<T>;
 
 /**
  * Reactively maps items from a source array to a new array, creating stable signals for each item.
@@ -2848,7 +2857,10 @@ type Key$2 = string | number;
 /**
  * One structural operation. `set` on a key that did not previously exist carries NO `prev`
  * property (an absent key is not the same as a key holding `undefined` — the merge3 lesson),
- * which is what lets {@link invertBatch} invert an add into a delete.
+ * which is what lets {@link invertBatch} invert an add into a delete. A JSON text transport
+ * collapses an own `prev: undefined` into an absent `prev` (structured-clone and in-process
+ * channels preserve the distinction) — wire-serialized batches were already not invertible,
+ * see {@link invertBatch}.
  *
  * `clear` is a sync-layer intent, not a value change: it retires a per-path register (the
  * observed-remove half of a subtree replace) and contributes NOTHING to a value: {@link applyOps}
@@ -3408,7 +3420,8 @@ type SyncOp = StoreOp & {
  * The wire/journal record. `writer` is an opaque principal pseudonym (natural identity never
  * enters the envelope); `origin` identifies the emitting replica. All ops in one envelope share
  * the envelope stamp, and an envelope carries at most one op per path, so `(origin, hlc)` is a
- * unique dot per path register.
+ * unique dot per path register. Op VALUES are wire data under the JSON-fidelity law — see
+ * {@link wireValueViolation}; emission lints them in dev mode.
  */
 type OpEnvelope = {
     readonly proto: number;
@@ -3809,6 +3822,75 @@ declare function removeElement<T>(container: ContainerNode<T>, key: string): voi
  * reclaim precision after many same-gap inserts. Existing reading order is preserved.
  */
 declare function rebalanceContainer<T extends object>(sync: Pick<OpSync, 'override'>, container: ContainerNode<T>): void;
+/**
+ * An element of a container in the WRAPPED representation: position beside the payload rather than
+ * inside it, so the payload stays a closed record a schema can validate without knowing about
+ * `~pos`. A move writes `[container, key, '~pos']` and a field edit writes
+ * `[container, key, 'value', field]` — still disjoint one-field paths.
+ */
+type ContainerEntry<T> = {
+    readonly [POS_SEGMENT]: string;
+    readonly value: T;
+};
+/** `key` derives an element's key from the value, for payloads carrying their own identity field. */
+type KeyedContainerConfig<T> = {
+    readonly key?: (value: T) => string;
+};
+/** The helpers of one container flavour, with keys supplied by the caller. */
+type KeyedContainer<T extends object, E extends object = T> = {
+    entries(container: Record<string, E>): OrderedEntry<T>[];
+    insert(container: ContainerNode<E>, key: string, value: T, index?: number): string;
+    move(container: ContainerNode<E>, key: string, index: number): string | undefined;
+    remove(container: ContainerNode<E>, key: string): void;
+    rebalance(sync: Pick<OpSync, 'override'>, container: ContainerNode<E>): void;
+};
+/** The same helpers where a configured `key` extractor supplies the key, so `insert` takes none. */
+type SelfKeyedContainer<T extends object, E extends object = T> = Omit<KeyedContainer<T, E>, 'insert'> & {
+    insert(container: ContainerNode<E>, value: T, index?: number): string;
+};
+/**
+ * Binds one container flavour to the whole set of helpers, so every read and write of a container
+ * agrees on how its elements are shaped. Pass the container node itself per call: one flavour
+ * serves every container of a type. Positions live INSIDE the element; for a payload that must
+ * stay a closed record, use {@link wrappedContainer} instead.
+ *
+ * ```typescript
+ * const slots = keyedContainer({ key: (n: Node) => n.id });
+ * slots.insert(node, child, 2); // one set at [container, id]
+ * slots.move(node, 'child-1', 0); // one set at [container, 'child-1', '~pos']
+ * slots.entries(node()); // reading order
+ * ```
+ *
+ * With no extractor, `insert` takes the key: `keyedContainer<Node>()`. A duplicate key OVERWRITES,
+ * taking a fresh position at the requested index. An element's identity field is immutable while it
+ * is resident — re-keying is a remove plus an insert, never an edit.
+ */
+declare function keyedContainer<T extends object>(config: {
+    key: (value: T) => string;
+}): SelfKeyedContainer<T>;
+declare function keyedContainer<T extends object>(config?: {
+    key?: never;
+}): KeyedContainer<T>;
+/**
+ * {@link keyedContainer} storing every element as a {@link ContainerEntry}: the position sits
+ * beside the payload rather than inside it, so a schema that closes the payload record still
+ * validates. `entries` reads back payloads, never wrappers.
+ *
+ * ```typescript
+ * const slots = wrappedContainer({ key: (n: Node) => n.id });
+ * slots.insert(node, child, 2); // one set at [container, id] carrying { '~pos', value }
+ * ```
+ *
+ * A container's representation is fixed when it is created and is never carried on the wire, so
+ * every peer of a synced container must agree on it — converting one after the fact is a data
+ * migration, not a flag.
+ */
+declare function wrappedContainer<T extends object>(config: {
+    key: (value: T) => string;
+}): SelfKeyedContainer<T, ContainerEntry<T>>;
+declare function wrappedContainer<T extends object>(config?: {
+    key?: never;
+}): KeyedContainer<T, ContainerEntry<T>>;
 
 type StoreHistory = {
     readonly canUndo: Signal<boolean>;
@@ -4594,5 +4676,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, 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, pooledKeys, 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 };
+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, keyedContainer, 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, pooledKeys, 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, wrappedContainer };
+export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ContainerEntry, 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, KeepPreviousOptions, KeyedContainer, KeyedContainerConfig, 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, SelfKeyedContainer, 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 };

package/package.json

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