@mmstack/primitives 21.10.4 → 21.11.1

package/package.json

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

package/types/mmstack-primitives.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;
@@ -3541,6 +3554,11 @@ type RegisterCheckpoint = {
     readonly siblings: readonly SyncSibling[];
     readonly water: Readonly<Record<string, Hlc>>;
 };
+/** One register's live siblings, as {@link ConvergingApply.liveUnder} reports them. */
+type LiveRegister = {
+    readonly path: readonly Key[];
+    readonly siblings: readonly SyncSibling[];
+};
 type ConvergingApply = {
     /**
      * Fold an envelope into the per-path registers and return the materialization deltas the
@@ -3573,6 +3591,12 @@ type ConvergingApply = {
     captureFrontier(): DotFrontier;
     /** The live (causally-maximal) siblings at a path: the emission-frontier read. */
     liveAt(path: readonly Key[]): readonly SyncSibling[];
+    /**
+     * The live registers at and under a path, shallow-first: what a reader compares its own
+     * observation frontier against to tell "someone wrote here since I looked" for a whole
+     * subtree (a fork's conflict projection). Registers with no live sibling are omitted.
+     */
+    liveUnder(path: readonly Key[]): readonly LiveRegister[];
     /**
      * Deepest-live-wins materialization of the whole tree from the current register state: the
      * root register's fold value with every live descendant fold grafted on. This is what a
@@ -3699,6 +3723,11 @@ type OpSync<T = unknown> = {
      * never saw. Scoped and synchronous, like {@link override}.
      */
     commitScope(frontier: DotFrontier, fn: () => void): void;
+    /**
+     * Read the live registers at and under a path (see {@link ConvergingApply.liveUnder}). A pure
+     * read of what this peer has applied: pending local writes are not in it until they flush.
+     */
+    liveUnder(path: readonly Key[]): readonly LiveRegister[];
     /** Per-origin latest versions — the handshake watermark. */
     watermark(): Record<string, number>;
     /** The full checkpoint (root + register state + watermark), for answering a peer's hello. */
@@ -4681,4 +4710,4 @@ 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, 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, 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 };
+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, LiveRegister, 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 };