@mmstack/primitives 22.0.1 → 22.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "22.0.1",
+  "version": "22.0.3",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -2002,6 +2002,58 @@ declare function signalFromEvent<TEvent extends Event, U>(target: ResolvableTarg
  * by {@link opaque} and the type-level brand carried by {@link Opaque}.
  */
 declare const OPAQUE: unique symbol;
+/**
+ * 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 } }));
+ */
+declare function opaque<T extends object>(value: T): Opaque<T>;
+/**
+ * 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
+ * }
+ */
+declare function isOpaque<T = object>(value: unknown): value is Opaque<T>;
+/**
+ * @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}.
+ */
+declare const LEAF: unique symbol;
+/**
+ * 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
+ */
+declare function isLeaf<T = unknown>(value: unknown): value is Signal<T> & {
+    readonly [LEAF]: () => boolean;
+};
 /**
  * An object marked via {@link opaque} — the store treats it as an indivisible leaf
  * (like a `Date`), returning it whole instead of deep-proxying its keys.
@@ -2010,10 +2062,10 @@ type Opaque<T> = T & {
     readonly [OPAQUE]: true;
 };
 /** @internal Strips the opaque brand from the value a leaf signal carries. */
-type Unwrap<T> = T extends {
+type UnwrapOpqaue<T> = T extends {
     readonly [OPAQUE]: true;
 } ? Omit<T, typeof OPAQUE> : T;
-type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp | {
+type BaseType = string | number | boolean | symbol | bigint | undefined | null | Function | Date | RegExp | {
     readonly [OPAQUE]: true;
 };
 type Key = string | number;
@@ -2082,16 +2134,22 @@ type MutableSignalStoreObject<T> = Simplify<Readonly<{
         <L extends AnyRecord>(props: L): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
     };
 }>;
-type SignalStore<T> = Signal<Unwrap<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
-type WritableSignalStore<T> = WritableSignal<Unwrap<T>> & {
+type SignalStore<T> = Signal<UnwrapOpqaue<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends Array<any> ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
+type WritableSignalStore<T> = WritableSignal<UnwrapOpqaue<T>> & {
     readonly asReadonlyStore: () => SignalStore<T>;
-} & (IsAny<T> extends true ? WritableSignalStoreObject<T> : NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
-type MutableSignalStore<T> = MutableSignal<Unwrap<T>> & {
+} & (IsAny<T> extends true ? WritableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends Array<any> ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
+type MutableSignalStore<T> = MutableSignal<UnwrapOpqaue<T>> & {
     readonly asReadonlyStore: () => SignalStore<T>;
-} & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
-declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify): MutableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify): WritableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify): SignalStore<T>;
+} & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends Array<any> ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
+declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): MutableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): WritableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): SignalStore<T>;
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
@@ -2109,6 +2167,14 @@ declare function store<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<
      * explicit `'object'`/`'array'`, or a `() => container` factory. See {@link Vivify}.
      */
     vivify?: Vivify;
+    /**
+     * Performance opt-in: promise that no node ever switches between leaf and substore (i.e. no
+     * unions mixing a primitive with an object/array). With this on, each node's leaf-ness is
+     * resolved once on the first {@link isLeaf} probe and cached as a constant, skipping the
+     * reactive `computed`. If a node's shape does change anyway, {@link isLeaf} keeps its first
+     * answer. Off by default.
+     */
+    noUnionLeaves?: boolean;
 }): WritableSignalStore<T>;
 /**
  * Creates a MutableSignalStore from a value.
@@ -2127,19 +2193,15 @@ declare function mutableStore<T extends AnyRecord>(value: T, opt?: CreateSignalO
      * explicit `'object'`/`'array'`, or a `() => container` factory. See {@link Vivify}.
      */
     vivify?: Vivify;
+    /**
+     * Performance opt-in: promise that no node ever switches between leaf and substore (i.e. no
+     * unions mixing a primitive with an object/array). With this on, each node's leaf-ness is
+     * resolved once on the first {@link isLeaf} probe and cached as a constant, skipping the
+     * reactive `computed`. If a node's shape does change anyway, {@link isLeaf} keeps its first
+     * answer. Off by default.
+     */
+    noUnionLeaves?: boolean;
 }): MutableSignalStore<T>;
-/**
- * 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 } }));
- */
-declare function opaque<T extends object>(value: T): Opaque<T>;
 
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
@@ -2568,5 +2630,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-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 };
 export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PipeableSignal, ScreenOrientation, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalFromEventOptions, SignalStore, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore };