@mmstack/primitives 20.15.4 → 20.16.1

package/README.md

@@ -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`

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)) {
@@ -5332,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) => ({
@@ -5880,6 +5964,17 @@ function createConvergingApply(opt) {
             const reg = registers.get(keyOf$1(path));
             return reg ? liveOf(reg) : [];
         },
+        liveUnder: (path) => {
+            const key = keyOf$1(path);
+            const out = [];
+            const at = registers.get(key);
+            for (const reg of at ? [at, ...descendantsOf(key)] : descendantsOf(key)) {
+                const siblings = liveOf(reg);
+                if (siblings.length)
+                    out.push({ path: reg.path, siblings });
+            }
+            return out;
+        },
         materialize: () => {
             const root = registers.get('');
             const res = root?.result;
@@ -6085,6 +6180,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,
@@ -6189,6 +6286,7 @@ function opSync(source, opt) {
             log.flush(); // fold pending base writes in first, so they count as observed
             return conv.captureFrontier();
         },
+        liveUnder: (path) => conv.liveUnder(path),
         commitScope: (frontier, fn) => {
             log.flush(); // earlier pending writes emit against the live frontier, not this one
             scopeFrontier = frontier;