@mmstack/primitives 21.0.28 → 21.0.29

package/fesm2022/mmstack-primitives.mjs

@@ -2440,6 +2440,82 @@ function isOpaque(value) {
         value !== null &&
         value[OPAQUE] === true);
 }
+/**
+ * @internal Runtime brand carrying a store node's lazily-built leaf probe. Exported (like
+ * {@link OPAQUE}) only so the `{ readonly [LEAF]: () => boolean }` brand on the store types is
+ * nameable in the emitted declarations — not part of the supported surface; use {@link isLeaf}.
+ */
+const LEAF = Symbol('@mmstack/primitives::store/LEAF');
+/**
+ * @internal Whether a value is a terminal leaf: a concrete non-record/non-array value always is;
+ * `null`/`undefined` is a leaf only when vivification is disabled (with vivify on it can still
+ * materialize a container, so it stays a descendable substore).
+ */
+function isLeafValue(value, vivifyEnabled) {
+    if (value == null)
+        return !vivifyEnabled;
+    if (isOpaque(value))
+        return true; // opaque always wins — even arrays
+    return !Array.isArray(value) && !isRecord(value);
+}
+/**
+ * @internal Constant leaf probes for nodes whose leaf-ness is statically known, so the reactive
+ * `computed` can be skipped entirely.
+ */
+function alwaysTrue() {
+    return true;
+}
+function alwaysFalse() {
+    return false;
+}
+/**
+ * @internal Attaches a lazy, memoized leaf probe to a store node. The probe (`() => boolean`)
+ * closes over the node's value signal and its (stable) vivify setting, building the backing
+ * `computed` on first call so leaf-ness tracks the live value reactively without taxing every
+ * node access. Idempotent.
+ */
+function markAsLeaf(sig, value, vivifyEnabled, noUnionLeaves) {
+    if (typeof sig[LEAF] !== 'function') {
+        let memo;
+        const probe = () => {
+            if (memo)
+                return memo();
+            const v = untracked(value);
+            memo =
+                isOpaque(v) || (v == null && !vivifyEnabled) || noUnionLeaves
+                    ? isLeafValue(v, vivifyEnabled)
+                        ? alwaysTrue
+                        : alwaysFalse
+                    : computed(() => isLeafValue(value(), vivifyEnabled));
+            return memo();
+        };
+        Object.defineProperty(sig, LEAF, {
+            value: probe,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    return sig;
+}
+/**
+ * Reports whether a store node is currently a **leaf** — a terminal value the store does not
+ * descend into (a primitive, `Date`, `RegExp`, {@link opaque} object, class instance, or a
+ * `null`/`undefined` hole when vivification is off) rather than a record/array substore.
+ *
+ * Leaf-ness reflects the node's **live** value: the probe is reactive and memoized, so calling
+ * `isLeaf` inside a `computed`/`effect` re-evaluates when the node's shape changes.
+ *
+ * @internal Exposed for advanced/niche interop only — not part of the supported public surface
+ * and may change without a major version bump.
+ *
+ * @example
+ * const s = store({ name: 'Ada', address: { city: 'London' } });
+ * isLeaf(s.name);    // true
+ * isLeaf(s.address); // false — a substore
+ */
+function isLeaf(value) {
+    return isStore(value) && value[LEAF]?.() === true;
+}
 const IS_STORE = Symbol('@mmstack/primitives::store/IS_STORE');
 const SCOPE_PARENT = Symbol('@mmstack/primitives::store/SCOPE_PARENT');
 /**
@@ -2502,7 +2578,7 @@ function hasOwnKey(value, key) {
  * @internal
  * Makes an array store
  */
-function toArrayStore(source, injector, vivify) {
+function toArrayStore(source, injector, vivify, noUnionLeaves = false) {
     if (isStore(source))
         return source;
     const isMutableSource = isMutable(source);
@@ -2612,9 +2688,10 @@ function toArrayStore(source, injector, vivify) {
                     });
                 const childSample = untracked(computation);
                 const childVivify = resolveVivify(childSample, vivify);
-                const proxy = Array.isArray(childSample)
-                    ? toArrayStore(computation, injector, childVivify)
-                    : toStore(computation, injector, childVivify);
+                const proxy = Array.isArray(childSample) && !isOpaque(childSample)
+                    ? toArrayStore(computation, injector, childVivify, noUnionLeaves)
+                    : toStore(computation, injector, childVivify, noUnionLeaves);
+                markAsLeaf(proxy, computation, childVivify !== false, noUnionLeaves);
                 const ref = new WeakRef(proxy);
                 storeCache.set(idx, ref);
                 PROXY_CLEANUP.register(proxy, { target, prop: idx }, ref);
@@ -2631,7 +2708,7 @@ function toArrayStore(source, injector, vivify) {
  * const state = store({ user: { name: 'John' } });
  * const nameSignal = state.user.name; // WritableSignal<string>
  */
-function toStore(source, injector, vivify = false) {
+function toStore(source, injector, vivify = false, noUnionLeaves = false) {
     if (isStore(source))
         return source;
     if (!injector)
@@ -2672,7 +2749,7 @@ function toStore(source, injector, vivify = false) {
                 return () => {
                     if (!isWritableSource)
                         return s;
-                    return untracked(() => toStore(source.asReadonly(), injector, vivify));
+                    return untracked(() => toStore(source.asReadonly(), injector, vivify, noUnionLeaves));
                 };
             if (prop === 'extend')
                 return (seed) => scopedStore(s, seed, isMutableSource
@@ -2725,9 +2802,10 @@ function toStore(source, injector, vivify = false) {
                 });
             const childSample = untracked(computation);
             const childVivify = resolveVivify(childSample, vivify);
-            const proxy = Array.isArray(childSample)
-                ? toArrayStore(computation, injector, childVivify)
-                : toStore(computation, injector, childVivify);
+            const proxy = Array.isArray(childSample) && !isOpaque(childSample)
+                ? toArrayStore(computation, injector, childVivify, noUnionLeaves)
+                : toStore(computation, injector, childVivify, noUnionLeaves);
+            markAsLeaf(proxy, computation, childVivify !== false, noUnionLeaves);
             const ref = new WeakRef(proxy);
             storeCache.set(prop, ref);
             PROXY_CLEANUP.register(proxy, { target, prop }, ref);
@@ -2820,14 +2898,14 @@ function scopedStore(parent, seed, kind, injector) {
  * @see {@link toStore}
  */
 function store(value, opt) {
-    return toStore(signal(value, opt), opt?.injector, opt?.vivify ?? false);
+    return toStore(signal(value, opt), opt?.injector, opt?.vivify ?? false, opt?.noUnionLeaves ?? false);
 }
 /**
  * Creates a MutableSignalStore from a value.
  * @see {@link toStore}
  */
 function mutableStore(value, opt) {
-    return toStore(mutable(value, opt), opt?.injector, opt?.vivify ?? false);
+    return toStore(mutable(value, opt), opt?.injector, opt?.vivify ?? false, opt?.noUnionLeaves ?? false);
 }
 
 // Internal dummy store for server-side rendering
@@ -3304,5 +3382,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, isOpaque, 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 };
+export { batteryStatus, chunked, clipboard, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, filterWith, focusWithin, geolocation, idle, indexArray, isDerivation, isLeaf, isMutable, isOpaque, 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