@mmstack/primitives 19.3.7 → 19.3.9

package/README.md

@@ -69,6 +69,14 @@ const upper = derived(user, {
 
 When the source is a `MutableSignal`, the derived signal is also a `MutableSignal` — `derived(state, 'items').mutate(arr => { arr.push(...); return arr })` propagates correctly.
 
+Pass `vivify` on the key/index form to create a missing container when writing through a `null`/`undefined` source — instead of throwing (mutable / array) or dropping the write. Choose `'object'`, `'array'`, `'auto'` (an array for index keys, an object otherwise), or a `() => container` factory; it defaults to off.
+
+```typescript
+const user = signal<{ name: string } | null>(null);
+derived(user, 'name', { vivify: 'object' }).set('Ada');
+// user() === { name: 'Ada' }
+```
+
 ### `store` / `mutableStore`
 
 Proxies an object (or signal of an object) into a tree of `WritableSignal`s — one per property, lazily created and cached via `WeakRef`. Arrays expose indices as signals plus a `.length` signal and `Symbol.iterator`. Mutability propagates: if the root is a `MutableSignal`, every child is too.
@@ -92,8 +100,52 @@ settings.notifications.mutate((n) => {
 });
 ```
 
+**Autovivification (opt-in).** By default, a write through a `null`/`undefined` path is dropped. Pass `vivify` to create the missing intermediate containers instead:
+
+```typescript
+const form = store(
+  { user: null as { address?: { city: string } } | null },
+  { vivify: 'auto' },
+);
+
+form.user.address.city.set('NYC');
+// form() === { user: { address: { city: 'NYC' } } }
+```
+
+Each level's shape is resolved from what's known: a value that is currently an object/array re-creates as that same shape (resolved per path and cached, so it survives the value later being nulled), while genuinely-unknown levels follow your option — `'auto'` (an array for index keys, an object otherwise), `'object'`, `'array'`, or a `() => container` factory. `false` (the default) keeps writes through `null` as no-ops. Adding a key that simply wasn't present on an existing object always works and needs no `vivify`.
+
 Top-level array support isn't exposed yet — use `indexArray` / `keyArray` for those.
 
+### `extend` (scoped overlay)
+
+`store.extend(seed)` (on any store kind) creates a **scoped overlay** — a child store that **shares** the parent's signals for inherited keys (the same `WritableSignal`: writes go through to the parent and parent changes flow down) while keeping the seed and any new keys in a **local layer** that never propagates upward. No diffing, no syncing — local keys simply aren't wired to the parent.
+
+```typescript
+const app = store({ user: { name: 'Alice' }, theme: 'dark' });
+
+const scope = app.extend({ draft: '' }); // inherits user + theme, adds a local draft
+
+scope.user === app.user; // true — the same signal (shared, two-way)
+scope.user.name.set('Bob'); // writes through to the parent
+scope.draft.set('hello'); // local only — `app` never gains `draft`
+scope(); // { user: { name: 'Bob' }, theme: 'dark', draft: 'hello' }
+```
+
+Resolution per key is **local → parent → local**: a seed key (or one set on the scope before it exists on the parent) is local and _shadows_ the parent — and keeps shadowing even if the parent later grows that key; a key that exists only on the parent writes through to it; a brand-new key lands locally. `scope()` is the merged view (local shadowing), and `Object.keys(scope)` / `key in scope` are the union of both layers. `extend` composes — `a.extend(x).extend(y)` chains parents.
+
+The seed may also be a **signal** of the matching kind, so an existing (externally-owned, reactive) signal becomes the local layer:
+
+```typescript
+const draft = signal({ title: '' });
+const scope = app.extend(draft); // writes to scope.title flow out to `draft`, and back in
+```
+
+A few release notes:
+
+- The local layer is a plain store (vivify off). Inherited paths vivify when the _parent_ was created with `vivify`; to autovivify local keys, seed with a vivify-enabled store — `app.extend(store(seed, { vivify: 'auto' }))`.
+- Reserved names — `extend`, `asReadonlyStore`, and the signal methods (`set` / `update` / `mutate` / `inline` / `asReadonly`) — shadow same-named data keys, as on any store.
+- `scope.asReadonlyStore()` returns a read-only **snapshot view** of the merge (reactive reads, no writes); it does not share sub-store identity.
+
 ### `toWritable`
 
 Turn any read-only `Signal<T>` into a `WritableSignal<T>` by providing custom `set` / `update` implementations. Powers `derived` internally; use it directly when you have a `computed` you want to expose as writable.

package/fesm2022/mmstack-primitives.mjs

@@ -399,37 +399,158 @@ function isMutable(value) {
     return 'mutate' in value && typeof value.mutate === 'function';
 }
 
+/**
+ * @internal
+ * Type guard for an array-index-like property key: a non-empty string that parses to a finite
+ * number (e.g. `'0'`, `'42'`). Used to choose array-vs-object shape during autovivification and
+ * deep store proxying.
+ */
+function isIndexProp(prop) {
+    return typeof prop === 'string' && prop.trim() !== '' && !isNaN(+prop);
+}
+
+// Container resolvers used by createVivify: each returns the current value when present and
+// only creates a new container when it is null/undefined.
+function identity(x) {
+    return x;
+}
+function createArray(cur) {
+    if (cur === null || cur === undefined)
+        return [];
+    return cur;
+}
+function createObject(cur) {
+    if (cur === null || cur === undefined)
+        return {};
+    return cur;
+}
+function createAuto(cur, key) {
+    if (cur === null || cur === undefined) {
+        return typeof key === 'number' || isIndexProp(key)
+            ? []
+            : {};
+    }
+    return cur;
+}
+/**
+ * @internal
+ * Resolves a {@link Vivify} option into a {@link VivifyFn}. The returned function leaves a
+ * present value untouched and only creates a new container — object, array, or factory result —
+ * when the current value is `null`/`undefined`.
+ */
+function createVivify(option) {
+    switch (option) {
+        case false:
+            return identity;
+        case 'array':
+            return createArray;
+        case 'object':
+            return createObject;
+        case 'auto':
+        case true:
+            return createAuto;
+        default:
+            return typeof option === 'function'
+                ? (cur) => cur === null || cur === undefined ? option() : cur
+                : identity;
+    }
+}
+
+function createMutableArrayUpdater(source, index, vivifyFn) {
+    return (next) => source.mutate((cur) => {
+        const vivified = vivifyFn(cur, index);
+        if (vivified === null || vivified === undefined)
+            return vivified;
+        vivified[index] = next;
+        return vivified;
+    });
+}
+function createImmutableArrayUpdater(source, index, vivifyFn) {
+    return (next) => source.update((cur) => {
+        const vivified = vivifyFn(cur, index)?.slice();
+        if (vivified === null || vivified === undefined)
+            return vivified;
+        vivified[index] = next;
+        return vivified;
+    });
+}
+function createMutableObjectUpdater(source, key, vivifyFn) {
+    return (next) => source.mutate((cur) => {
+        const vivified = vivifyFn(cur, key);
+        if (vivified === null || vivified === undefined)
+            return vivified;
+        vivified[key] = next;
+        return vivified;
+    });
+}
+function createImmutableObjectUpdater(source, key, vivifyFn) {
+    return (next) => source.update((cur) => {
+        const vivified = vivifyFn(cur, key);
+        if (vivified === null || vivified === undefined)
+            return vivified;
+        return { ...vivified, [key]: next };
+    });
+}
+function createUpdater(source, key, vivify) {
+    const sample = untracked(source);
+    // fast path for when vivification is off
+    if (!vivify) {
+        if (Array.isArray(sample) && typeof key === 'number') {
+            const idx = key;
+            return isMutable(source)
+                ? (next) => source.mutate((cur) => {
+                    cur[idx] = next;
+                    return cur;
+                })
+                : (next) => source.update((cur) => {
+                    const copy = cur.slice();
+                    copy[idx] = next;
+                    return copy;
+                });
+        }
+        return isMutable(source)
+            ? (next) => source.mutate((cur) => {
+                cur[key] = next;
+                return cur;
+            })
+            : (next) => source.update((cur) => ({
+                ...cur,
+                [key]: next,
+            }));
+    }
+    const present = sample !== null && sample !== undefined;
+    const keyIsIndex = typeof key === 'number' || isIndexProp(key);
+    let vivifyOpt = vivify;
+    if (vivifyOpt === 'auto' || vivifyOpt === true) {
+        vivifyOpt = ((present ? Array.isArray(sample) : keyIsIndex) ? 'array' : 'object');
+    }
+    const vivifyFn = createVivify(vivifyOpt);
+    // Route to the array updater whenever the container is (or will be vivified as) an
+    // array, so the updater and the created container agree on shape for a nullish source.
+    const isArray = vivifyOpt === 'array'
+        ? keyIsIndex
+        : vivifyOpt === 'object'
+            ? false
+            : Array.isArray(sample) && typeof key === 'number';
+    if (isArray)
+        return isMutable(source)
+            ? createMutableArrayUpdater(source, key, vivifyFn)
+            : createImmutableArrayUpdater(source, key, vivifyFn);
+    return isMutable(source)
+        ? createMutableObjectUpdater(source, key, vivifyFn)
+        : createImmutableObjectUpdater(source, key, vivifyFn);
+}
 function derived(source, optOrKey, opt) {
-    const isArray = Array.isArray(untracked(source)) && typeof optOrKey === 'number';
-    const from = typeof optOrKey === 'object' ? optOrKey.from : (v) => v[optOrKey];
+    const vivify = typeof optOrKey === 'object' ? false : (opt?.vivify ?? false);
+    // With vivification the source may legitimately be null/undefined
+    const from = typeof optOrKey === 'object'
+        ? optOrKey.from
+        : vivify
+            ? (v) => v?.[optOrKey]
+            : (v) => v[optOrKey];
     const onChange = typeof optOrKey === 'object'
         ? optOrKey.onChange
-        : isArray
-            ? isMutable(source)
-                ? (next) => {
-                    source.mutate((cur) => {
-                        cur[optOrKey] = next;
-                        return cur;
-                    });
-                }
-                : (next) => {
-                    source.update((cur) => {
-                        const newArray = [...cur];
-                        newArray[optOrKey] = next;
-                        return newArray;
-                    });
-                }
-            : isMutable(source)
-                ? (next) => {
-                    source.mutate((cur) => {
-                        cur[optOrKey] =
-                            next;
-                        return cur;
-                    });
-                }
-                : (next) => {
-                    source.update((cur) => ({ ...cur, [optOrKey]: next }));
-                };
+        : createUpdater(source, optOrKey, vivify);
     const rest = typeof optOrKey === 'object' ? { ...optOrKey, ...opt } : opt;
     const baseEqual = rest?.equal ?? Object.is;
     let cnt = 0;
@@ -2281,7 +2402,19 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
     return untracked(() => state.asReadonly());
 }
 
+/**
+ * Runtime marker + compile-time brand for an opaque value. A `const`-declared `Symbol`
+ * has a `unique symbol` type, so the same symbol serves as both the property key written
+ * by {@link opaque} and the type-level brand carried by {@link Opaque}.
+ */
+const OPAQUE = Symbol('MMSTACK::OPAQUE');
 const IS_STORE = Symbol('MMSTACK::IS_STORE');
+const SCOPE_PARENT = Symbol('MMSTACK::SCOPE_PARENT');
+/**
+ * @internal
+ * Test-only handle on the proxy cache (deliberately NOT re-exported from the public barrel).
+ * Maps a store's backing signal to its lazily-built child proxies, each held via a `WeakRef`.
+ */
 const PROXY_CACHE = new WeakMap();
 const SIGNAL_FN_PROP = new Set([
     'set',
@@ -2290,6 +2423,11 @@ const SIGNAL_FN_PROP = new Set([
     'inline',
     'asReadonly',
 ]);
+/**
+ * @internal
+ * Test-only handle on the finalization registry (deliberately NOT re-exported from the public
+ * barrel). Prunes a cache entry once its proxy is reclaimed by the GC.
+ */
 const PROXY_CLEANUP = new FinalizationRegistry(({ target, prop }) => {
     const storeCache = PROXY_CACHE.get(target);
     if (storeCache)
@@ -2304,20 +2442,37 @@ function isStore(value) {
         value !== null &&
         value[IS_STORE] === true);
 }
-function isIndexProp(prop) {
-    return typeof prop === 'string' && prop.trim() !== '' && !isNaN(+prop);
-}
 function isRecord(value) {
     if (value === null || typeof value !== 'object')
         return false;
+    if (value[OPAQUE] === true)
+        return false; // opaque → leaf
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * @internal
+ * Resolves the vivify shape for a node from its current value: a present record/array is a
+ * certainty we keep (cached in the derivation, so it survives the value being nulled); an
+ * unknown value (`null`/`undefined`) defers to the caller's option. Off stays off.
+ */
+function resolveVivify(sample, option) {
+    if (!option)
+        return false;
+    if (Array.isArray(sample))
+        return 'array';
+    if (isRecord(sample))
+        return 'object';
+    return 'auto';
+}
+function hasOwnKey(value, key) {
+    return value != null && Object.hasOwn(value, key);
+}
 /**
  * @internal
  * Makes an array store
  */
-function toArrayStore(source, injector) {
+function toArrayStore(source, injector, vivify) {
     if (isStore(source))
         return source;
     const isMutableSource = isMutable(source);
@@ -2397,31 +2552,39 @@ function toArrayStore(source, injector) {
                 const value = untracked(target);
                 const valueIsArray = Array.isArray(value);
                 const valueIsRecord = isRecord(value);
+                const nodeVivify = resolveVivify(value, vivify);
+                const vivifyFn = createVivify(nodeVivify);
                 const equalFn = (valueIsRecord || valueIsArray) &&
                     isMutableSource &&
                     typeof value[idx] === 'object'
                     ? () => false
                     : undefined;
                 const computation = valueIsRecord
-                    ? derived(target, idx, { equal: equalFn })
+                    ? derived(target, idx, {
+                        equal: equalFn,
+                        vivify: nodeVivify,
+                    })
                     : derived(target, {
                         from: (v) => v?.[idx],
                         onChange: (newValue) => target.update((v) => {
-                            if (v === null || v === undefined)
-                                return v;
+                            const container = vivifyFn(v, idx);
+                            if (container === null || container === undefined)
+                                return container;
                             try {
-                                v[idx] = newValue;
+                                container[idx] = newValue;
                             }
                             catch (e) {
                                 if (isDevMode())
                                     console.error(`[store] Failed to set property "${String(idx)}"`, e);
                             }
-                            return v;
+                            return container;
                         }),
                     });
-                const proxy = Array.isArray(untracked(computation))
-                    ? toArrayStore(computation, injector)
-                    : toStore(computation, injector);
+                const childSample = untracked(computation);
+                const childVivify = resolveVivify(childSample, vivify);
+                const proxy = Array.isArray(childSample)
+                    ? toArrayStore(computation, injector, childVivify)
+                    : toStore(computation, injector, childVivify);
                 const ref = new WeakRef(proxy);
                 storeCache.set(idx, ref);
                 PROXY_CLEANUP.register(proxy, { target, prop: idx }, ref);
@@ -2438,7 +2601,7 @@ function toArrayStore(source, injector) {
  * const state = store({ user: { name: 'John' } });
  * const nameSignal = state.user.name; // WritableSignal<string>
  */
-function toStore(source, injector) {
+function toStore(source, injector, vivify = false) {
     if (isStore(source))
         return source;
     if (!injector)
@@ -2448,7 +2611,8 @@ function toStore(source, injector) {
         : toWritable(source, () => {
             // noop
         });
-    const isMutableSource = isMutable(writableSource);
+    const isWritableSource = isWritableSignal(source);
+    const isMutableSource = isWritableSource && isMutable(writableSource);
     const s = new Proxy(writableSource, {
         has(_, prop) {
             return Reflect.has(untracked(source), prop);
@@ -2476,10 +2640,16 @@ function toStore(source, injector) {
                 return true;
             if (prop === 'asReadonlyStore')
                 return () => {
-                    if (!isWritableSignal(source))
+                    if (!isWritableSource)
                         return s;
-                    return untracked(() => toStore(source.asReadonly(), injector));
+                    return untracked(() => toStore(source.asReadonly(), injector, vivify));
                 };
+            if (prop === 'extend')
+                return (seed) => scopedStore(s, seed, isMutableSource
+                    ? 'mutable'
+                    : isWritableSource
+                        ? 'writable'
+                        : 'readonly', injector);
             if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
                 return target[prop];
             let storeCache = PROXY_CACHE.get(target);
@@ -2498,31 +2668,36 @@ function toStore(source, injector) {
             const value = untracked(target);
             const valueIsRecord = isRecord(value);
             const valueIsArray = Array.isArray(value);
+            const nodeVivify = resolveVivify(value, vivify);
+            const vivifyFn = createVivify(nodeVivify);
             const equalFn = (valueIsRecord || valueIsArray) &&
                 isMutableSource &&
                 typeof value[prop] === 'object'
                 ? () => false
                 : undefined;
             const computation = valueIsRecord
-                ? derived(target, prop, { equal: equalFn })
+                ? derived(target, prop, { equal: equalFn, vivify: nodeVivify })
                 : derived(target, {
                     from: (v) => v?.[prop],
                     onChange: (newValue) => target.update((v) => {
-                        if (v === null || v === undefined)
-                            return v;
+                        const container = vivifyFn(v, prop);
+                        if (container === null || container === undefined)
+                            return container;
                         try {
-                            v[prop] = newValue;
+                            container[prop] = newValue;
                         }
                         catch (e) {
                             if (isDevMode())
                                 console.error(`[store] Failed to set property "${String(prop)}"`, e);
                         }
-                        return v;
+                        return container;
                     }),
                 });
-            const proxy = Array.isArray(untracked(computation))
-                ? toArrayStore(computation, injector)
-                : toStore(computation, injector);
+            const childSample = untracked(computation);
+            const childVivify = resolveVivify(childSample, vivify);
+            const proxy = Array.isArray(childSample)
+                ? toArrayStore(computation, injector, childVivify)
+                : toStore(computation, injector, childVivify);
             const ref = new WeakRef(proxy);
             storeCache.set(prop, ref);
             PROXY_CLEANUP.register(proxy, { target, prop }, ref);
@@ -2531,19 +2706,119 @@ function toStore(source, injector) {
     });
     return s;
 }
+/**
+ * @internal
+ * Backs `store.extend(...)`. Builds a scoped overlay over `parent`: the local layer (the seed
+ * plus any keys created later) is its own signal and `parent` is its own signal, so the getter
+ * routes each key by consulting BOTH — local first, then parent, else local (so a write to an
+ * as-yet-unknown key lands locally). Inherited keys return the parent's own sub-store (shared
+ * identity + two-way), while local keys never propagate upward. A merged `computed` is derived
+ * only for whole-object reads / `has` / iteration — never for routing.
+ */
+function scopedStore(parent, seed, kind, injector) {
+    const local = isSignal(seed)
+        ? toStore(seed, injector)
+        : kind === 'mutable'
+            ? mutableStore(seed, { injector })
+            : kind === 'readonly'
+                ? store(seed, { injector }).asReadonlyStore()
+                : store(seed, { injector });
+    const localValue = () => untracked(local);
+    const parentValue = () => untracked(parent);
+    const view = computed(() => ({
+        ...parent(),
+        ...local(),
+    }));
+    const splitSet = (next) => {
+        const lv = localValue();
+        const pv = parentValue();
+        for (const key of Reflect.ownKeys(next)) {
+            const layer = hasOwnKey(lv, key)
+                ? local
+                : hasOwnKey(pv, key)
+                    ? parent
+                    : local;
+            layer[key].set(next[key]);
+        }
+    };
+    const base = toWritable(view, kind === 'readonly' ? () => undefined : splitSet, undefined, { pure: false });
+    if (kind === 'mutable') {
+        base.mutate = (updater) => splitSet(updater(untracked(view)));
+        base.inline = (updater) => base.mutate((prev) => {
+            updater(prev);
+            return prev;
+        });
+    }
+    const scope = new Proxy(base, {
+        get(target, prop) {
+            if (prop === IS_STORE)
+                return true;
+            if (prop === SCOPE_PARENT)
+                return parent;
+            if (prop === 'extend')
+                return (childSeed) => scopedStore(scope, childSeed, kind, injector);
+            if (prop === 'asReadonlyStore')
+                return () => toStore(computed(() => ({ ...parent(), ...local() })), injector);
+            if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
+                return target[prop];
+            // Route by consulting both signals: local first, then parent, else local (new → local).
+            if (hasOwnKey(localValue(), prop))
+                return local[prop];
+            if (hasOwnKey(parentValue(), prop))
+                return parent[prop];
+            return local[prop];
+        },
+        has(_, prop) {
+            return hasOwnKey(localValue(), prop) || hasOwnKey(parentValue(), prop);
+        },
+        ownKeys() {
+            return [
+                ...new Set([
+                    ...Reflect.ownKeys(parentValue()),
+                    ...Reflect.ownKeys(localValue()),
+                ]),
+            ];
+        },
+        getOwnPropertyDescriptor(_, prop) {
+            if (hasOwnKey(localValue(), prop) || hasOwnKey(parentValue(), prop))
+                return { enumerable: true, configurable: true };
+            return undefined;
+        },
+        getPrototypeOf() {
+            return Object.prototype;
+        },
+    });
+    return scope;
+}
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
  */
 function store(value, opt) {
-    return toStore(signal(value, opt), opt?.injector);
+    return toStore(signal(value, opt), opt?.injector, opt?.vivify ?? false);
 }
 /**
  * Creates a MutableSignalStore from a value.
  * @see {@link toStore}
  */
 function mutableStore(value, opt) {
-    return toStore(mutable(value, opt), opt?.injector);
+    return toStore(mutable(value, opt), opt?.injector, opt?.vivify ?? false);
+}
+/**
+ * Marks a plain object as opaque so {@link store} treats it as an indivisible leaf
+ * (returned whole, never deep-proxied) — the same way it treats a `Date` or `RegExp`.
+ * The marker is a non-enumerable symbol, so it never appears in spreads or iteration.
+ * Idempotent. Call before freezing (`defineProperty` fails on a frozen object).
+ *
+ * @example
+ * const s = store({ config: opaque({ theme: 'dark', nested: { a: 1 } }) });
+ * s.config();        // the whole object, not a child store
+ * s.config.set(opaque({ theme: 'light', nested: { a: 2 } }));
+ */
+function opaque(value) {
+    if (value[OPAQUE] !== true)
+        Object.defineProperty(value, OPAQUE, { value: true, enumerable: false });
+    return value;
 }
 
 // Internal dummy store for server-side rendering
@@ -3022,5 +3297,5 @@ function withHistory(sourceOrValue, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { batteryStatus, chunked, clipboard, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, geolocation, idle, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, orientation, pageVisibility, pairwise, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export { batteryStatus, chunked, clipboard, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, geolocation, idle, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map