@mmstack/primitives 19.3.9 → 19.3.11

package/fesm2022/mmstack-primitives.mjs

@@ -2407,9 +2407,120 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
  * 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');
+const OPAQUE = Symbol('@mmstack/primitives::store/OPAQUE');
+/**
+ * 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;
+}
+/**
+ * Type guard companion to {@link opaque}: returns `true` when `value` carries the
+ * {@link OPAQUE} brand, narrowing it to {@link Opaque}. This is the same check the
+ * store uses to route opaque values to its leaf branch (alongside `Date`/`RegExp`).
+ *
+ * @internal Exposed for advanced/niche interop only — not part of the supported public
+ * surface and may change without a major version bump. Reach for {@link opaque} for
+ * normal usage.
+ *
+ * @example
+ * if (isOpaque(value)) {
+ *   // value: Opaque<object> — `store` would treat it as an indivisible leaf
+ * }
+ */
+function isOpaque(value) {
+    return (typeof value === 'object' &&
+        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');
 /**
  * @internal
  * Test-only handle on the proxy cache (deliberately NOT re-exported from the public barrel).
@@ -2443,10 +2554,8 @@ function isStore(value) {
         value[IS_STORE] === true);
 }
 function isRecord(value) {
-    if (value === null || typeof value !== 'object')
+    if (value === null || typeof value !== 'object' || isOpaque(value))
         return false;
-    if (value[OPAQUE] === true)
-        return false; // opaque → leaf
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
@@ -2472,7 +2581,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);
@@ -2582,9 +2691,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);
@@ -2601,7 +2711,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)
@@ -2642,7 +2752,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
@@ -2695,9 +2805,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);
@@ -2772,12 +2883,7 @@ function scopedStore(parent, seed, kind, injector) {
             return hasOwnKey(localValue(), prop) || hasOwnKey(parentValue(), prop);
         },
         ownKeys() {
-            return [
-                ...new Set([
-                    ...Reflect.ownKeys(parentValue()),
-                    ...Reflect.ownKeys(localValue()),
-                ]),
-            ];
+            return Reflect.ownKeys(untracked(view));
         },
         getOwnPropertyDescriptor(_, prop) {
             if (hasOwnKey(localValue(), prop) || hasOwnKey(parentValue(), prop))
@@ -2795,30 +2901,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);
-}
-/**
- * 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;
+    return toStore(mutable(value, opt), opt?.injector, opt?.vivify ?? false, opt?.noUnionLeaves ?? false);
 }
 
 // Internal dummy store for server-side rendering
@@ -3297,5 +3387,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, 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