@mmstack/primitives 20.15.3 → 20.15.4

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
@@ -792,6 +792,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

@@ -5121,11 +5121,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 +5148,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 +5226,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).
@@ -7447,5 +7473,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