@mmstack/primitives 20.15.3 → 20.16.0

package/README.md

@@ -21,7 +21,7 @@ npm install @mmstack/primitives
 - [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`, `storeHistory`, `stored`, `persistedStore`, `tabSync`, `opLog`
-- [Sync & convergence](#sync--convergence) — `opSync`, `tabSync(store)`, merge policies (`lww`, `mergeThree`, `keyedArray`, `preserve`), `Conflicted`, keyed containers (`orderedEntries`, `insertElement`, `moveElement`, `rebalanceContainer`), `rebaseOps`, `policyStrategy`, `syncedFork`
+- [Sync & convergence](#sync--convergence) — `opSync`, `tabSync(store)`, merge policies (`lww`, `mergeThree`, `keyedArray`, `preserve`), `Conflicted`, keyed containers (`keyedContainer`, `wrappedContainer`, `orderedEntries`, `posBetween`), `rebaseOps`, `policyStrategy`, `syncedFork`
 - [Observability](#observability) — `provideConcurrencyInstrumentation`, `perfCustomTracks`
 - [Performance helpers](#performance-helpers) — `chunked`, `pooled` / `pooledArray` / `pooledMap` / `pooledSet`
 - [Sensors](#sensors) — `sensor()` facade + browser-state signals
@@ -369,8 +369,11 @@ The foundation of stale-while-revalidate. Wraps a signal so it **holds its last
 import { keepPrevious } from '@mmstack/primitives';
 
 const held = keepPrevious(resource.value); // drops to undefined mid-reload → keeps last value
+const rows = keepPrevious(resource.value, { fallback: [] }); // [] only until the first value lands
 ```
 
+`fallback` is yielded only while nothing has ever been defined; after the first defined value the previous value covers every gap, never the fallback. Like any linked signal the hold is lazy: it carries a value it has computed with, so place it over the value your readers read — reading is what feeds it. `@mmstack/resource` does exactly that for its `keepPrevious` option.
+
 If the source is writable, `set` / `update` / `asReadonly` (and `mutate` / `inline` / `from` for mutable / derived sources) are forwarded through, so it stays a drop-in replacement. `@mmstack/resource` uses it under the hood for its `keepPrevious` option.
 
 ### Keep-alive — `MmActivity` / `injectPaused` / `providePaused`
@@ -792,6 +795,24 @@ const board = tabSync(store({ title: 'Board', todos: [] }), {
 
 A **merge policy** decides the result when two peers change one path at once: `lww` (default), `mergeThree` (three-way against the common ancestor), `keyedArray(idFn)` (list reconcile by identity), or `preserve` (both sides survive as a `Conflicted` value; `isConflicted(v)` narrows it, resolution is a later write). `rebaseOps(root, pending, remote, policies)` is the pure invert-apply-reapply routine behind optimistic updates and offline queues, and `policyStrategy(policies)` gives a `forkStore` the same per-path resolution. This is what [`@mmstack/mesh`](https://www.npmjs.com/package/@mmstack/mesh) wraps for multiplayer.
 
+### Keyed containers
+
+**A list several peers reorder is a record keyed by element id, never an array.** Each element carries a fractional position at `~pos`, so an insert is one write at `[list, id]` and a move is one write at `[list, id, '~pos']` — two peers inserting into the same list at once keep both elements, where one whole-array write would have folded over the other.
+
+```typescript
+import { keyedContainer } from '@mmstack/primitives';
+
+const board = store<{ todos: Record<string, Todo> }>({ todos: {} });
+const todos = keyedContainer({ key: (t: Todo) => t.id }); // or pass the key to insert
+
+todos.insert(board.todos, { id: 't1', title: 'Ship it' }, 0);
+todos.move(board.todos, 't1', 3); // writes the position and nothing else
+todos.entries(board.todos()); // reading order: by ~pos, key breaking ties
+todos.rebalance(sync, board.todos); // authority sweep when positions grow long
+```
+
+Reading order is a pure function of the materialized value, so every replica agrees without consulting the op log. `wrappedContainer` stores elements as `{ '~pos', value }` instead, keeping the payload a closed record a schema can validate; the choice is fixed when the container is created and never inferred from data, so peers of a synced container must agree on it. `posBetween(before, after)` is the fractional index underneath.
+
 ## Observability
 
 An optional listener seam on the concurrency layer. `provideConcurrencyInstrumentation(listener)` receives events as transition scopes coordinate pending, suspense, and transaction windows; with no listener the taps are no-ops. `perfCustomTracks()` is a ready listener that writes each window to a Chrome DevTools Performance track, and the window hooks are span-shaped, so forwarding to [`@mmstack/telemetry-core`](https://www.npmjs.com/package/@mmstack/telemetry-core) is a direct mapping.

package/fesm2022/mmstack-primitives.mjs

@@ -1917,18 +1917,27 @@ function createSetter(source) {
 
 function keepPrevious(src, opt) {
     const mutableSrc = isWritableSignal(src) && isMutable(src);
+    const { fallback, ...signalOpt } = opt ?? {};
     let cnt = 0;
     const baseEqual = opt?.equal;
     const equal = mutableSrc
         ? (a, b) => cnt > 0 ? false : baseEqual ? baseEqual(a, b) : Object.is(a, b)
         : baseEqual;
-    const persisted = linkedSignal(...(ngDevMode ? [{ debugName: "persisted", ...opt,
+    const persisted = linkedSignal(...(ngDevMode ? [{ debugName: "persisted", ...signalOpt,
             source: () => src(),
-            computation: (next, prev) => next === undefined && prev !== undefined ? prev.value : next,
+            computation: (next, prev) => {
+                if (next !== undefined)
+                    return next;
+                return prev !== undefined ? prev.value : fallback;
+            },
             equal }] : [{
-            ...opt,
+            ...signalOpt,
             source: () => src(),
-            computation: (next, prev) => next === undefined && prev !== undefined ? prev.value : next,
+            computation: (next, prev) => {
+                if (next !== undefined)
+                    return next;
+                return prev !== undefined ? prev.value : fallback;
+            },
             equal,
         }]));
     if (isWritableSignal(src)) {
@@ -5121,11 +5130,14 @@ const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
  * deterministic on every replica.
  */
 function orderedEntries(container) {
+    return entriesOf(container, (element) => element);
+}
+function entriesOf(container, payloadOf) {
     const entries = [];
     for (const key of Object.keys(container)) {
-        const value = container[key];
-        const raw = isRecord(value) ? value[POS_SEGMENT] : undefined;
-        entries.push({ key, pos: typeof raw === 'string' ? raw : '', value });
+        const element = container[key];
+        const raw = isRecord(element) ? element[POS_SEGMENT] : undefined;
+        entries.push({ key, pos: typeof raw === 'string' ? raw : '', value: payloadOf(element) });
     }
     entries.sort((a, b) => a.pos < b.pos ? -1 : a.pos > b.pos ? 1 : a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
     return entries;
@@ -5145,12 +5157,18 @@ const neighborPositions = (entries, index) => {
  * layer diffs on its own. Returns the assigned position. Re-inserting an existing key overwrites it.
  */
 function insertElement(container, key, value, index) {
+    return insertInto(container, key, value, index, inlineElement);
+}
+const inlineElement = (value, pos) => {
     if (POS_SEGMENT in value)
-        devError(`insertElement: '${POS_SEGMENT}' is managed, drop it from the value`);
+        devError(`insert: '${POS_SEGMENT}' is managed, drop it from the value`);
+    return { ...value, [POS_SEGMENT]: pos };
+};
+function insertInto(container, key, value, index, elementOf) {
     const entries = orderedEntries(container()).filter((e) => e.key !== key);
     const [before, after] = neighborPositions(entries, index ?? entries.length);
     const pos = posBetween(before, after);
-    container.update((c) => ({ ...c, [key]: { ...value, [POS_SEGMENT]: pos } }));
+    container.update((c) => ({ ...c, [key]: elementOf(value, pos) }));
     return pos;
 }
 /**
@@ -5217,6 +5235,23 @@ function evenPositions(n) {
     }
     return out;
 }
+function keyedContainer(config = {}) {
+    return helpersFor(config.key, inlineElement, (element) => element);
+}
+function wrappedContainer(config = {}) {
+    return helpersFor(config.key, (value, pos) => ({ [POS_SEGMENT]: pos, value }), (element) => element.value);
+}
+function helpersFor(extract, elementOf, payloadOf) {
+    return {
+        entries: (container) => entriesOf(container, payloadOf),
+        insert: (container, a, b, c) => extract
+            ? insertInto(container, extract(a), a, b, elementOf)
+            : insertInto(container, a, b, c, elementOf),
+        move: (container, key, index) => moveElement(container, key, index),
+        remove: (container, key) => removeElement(container, key),
+        rebalance: (sync, container) => rebalanceContainer(sync, container),
+    };
+}
 
 /**
  * Wire protocol version. Version 2 ops carry `cites` + `epoch` (the dot-citation register).
@@ -5306,6 +5341,81 @@ function validateEnvelope(env) {
     }
     return null;
 }
+function wireValueViolation(value) {
+    return violationAt(value, false, []);
+}
+function violationAt(value, nested, ancestors) {
+    if (value === undefined)
+        return nested ? 'undefined-in-container' : null;
+    if (value === null)
+        return null;
+    const t = typeof value;
+    if (t === 'boolean' || t === 'string')
+        return null;
+    if (t === 'number') {
+        if (!Number.isFinite(value))
+            return 'non-finite-number';
+        return Object.is(value, -0) ? 'negative-zero' : null;
+    }
+    if (t === 'bigint')
+        return 'bigint';
+    if (t === 'function')
+        return 'function';
+    if (t === 'symbol')
+        return 'symbol';
+    if (ancestors.includes(value))
+        return 'cycle';
+    ancestors.push(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                if (!Object.hasOwn(value, i))
+                    return 'sparse-array';
+                const reason = violationAt(value[i], true, ancestors);
+                if (reason)
+                    return reason;
+            }
+            const keys = Object.keys(value);
+            if (keys.length !== value.length)
+                return 'array-named-property';
+            for (const key of keys) {
+                const idx = Number(key);
+                if (String(idx) !== key ||
+                    !Number.isInteger(idx) ||
+                    idx < 0 ||
+                    idx >= value.length) {
+                    return 'array-named-property';
+                }
+            }
+            return null;
+        }
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null)
+            return 'non-plain-object';
+        for (const key of Object.keys(value)) {
+            const reason = violationAt(value[key], true, ancestors);
+            if (reason)
+                return reason;
+        }
+        return null;
+    }
+    finally {
+        ancestors.pop();
+    }
+}
+// dev-only: one warning per offending batch names the first violating op, then stops
+const lintWireValues = (ops) => {
+    for (const op of ops) {
+        const reason = (op.kind === 'set' ? wireValueViolation(op.next) : null) ??
+            (op.kind !== 'clear' && Object.hasOwn(op, 'prev')
+                ? wireValueViolation(op.prev)
+                : null);
+        if (!reason)
+            continue;
+        console.warn(`[@mmstack/primitives] op value at "${op.path.join('.')}" will not survive a JSON transport (${reason}): peers materialize a different value than this emitter, and the room can diverge. Op values must round-trip JSON unchanged; encode rich leaves as strings.`);
+        return;
+    }
+};
 const lww = (_ancestor, mine) => mine;
 const mergeThree = (ancestor, mine, theirs) => merge3(ancestor, mine, theirs);
 const preserve = (ancestor, mine, theirs) => ({
@@ -6059,6 +6169,8 @@ function opSync(source, opt) {
     const emitLocal = (ops) => {
         const frontier = scopeFrontier;
         const stamped = conv.stamp(ops, { bump: bumping, frontier });
+        if (isDevMode())
+            lintWireValues(stamped);
         const nextVersion = (versions.get(origin) ?? 0) + 1;
         const env = {
             proto: OP_PROTO_VERSION,
@@ -7447,5 +7559,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-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 { 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 };
 //# sourceMappingURL=mmstack-primitives.mjs.map