@mmstack/primitives 20.5.7 → 20.5.9

package/index.d.ts

@@ -228,6 +228,55 @@ declare function mutable<T>(initial: T, opt?: CreateSignalOptions<T>): MutableSi
  */
 declare function isMutable<T = any>(value: WritableSignal<T>): value is MutableSignal<T>;
 
+/** @internal Narrows `'array'` so it is only assignable when `T` is an array type. */
+type VivifyArray<T> = T extends any[] ? 'array' : never;
+/** @internal Narrows `'object'` so it is only assignable when `T` is an object type. */
+type VivifyObject<T> = T extends object ? 'object' : never;
+/**
+ * Controls **autovivification** — whether, and as what shape, a writable `derived` (or `store`)
+ * creates a missing container when the source value is `null`/`undefined` at the moment of a
+ * write. Without it, writing through a nullish value is a no-op; with it, a deep write such as
+ * `derived(user, 'name', { vivify: 'object' }).set('Ada')` materializes the missing object
+ * instead of silently dropping the write.
+ *
+ * A **present** value is always preserved — updated in place for a `MutableSignal` source,
+ * copied for an immutable one. Vivification only ever *creates*, it never *replaces*.
+ *
+ * Variants:
+ * - `false` — **default.** Off; a write through a nullish source does nothing.
+ * - `true` / `'auto'` — infer the shape from the key: an array (`[]`) for a numeric / index key,
+ *   a plain object (`{}`) otherwise.
+ * - `'object'` — always create a plain object (`{}`). Only assignable when `T` is an object.
+ * - `'array'` — always create an array (`[]`). Only assignable when `T` is an array.
+ * - `() => T` — a factory producing the container to create. Called only on a nullish source,
+ *   once per vivification (a fresh instance each time), so a present value is never clobbered.
+ *   Useful for seeding defaults, e.g. `() => ({ items: [], total: 0 })`.
+ *
+ * @typeParam T - The type of the container that may be created (the source/parent value).
+ *
+ * @example
+ * ```ts
+ * const user = signal<{ name: string } | null>(null);
+ *
+ * derived(user, 'name').set('Ada');                       // off: dropped, user() === null
+ * derived(user, 'name', { vivify: 'object' }).set('Ada'); // user() === { name: 'Ada' }
+ * ```
+ */
+type Vivify<T = any> = 'auto' | boolean | (() => T) | VivifyArray<T> | VivifyObject<T>;
+/**
+ * Options mix-in that adds an optional {@link Vivify} setting to the `options` argument of the
+ * `derived` / `store` key & index overloads.
+ *
+ * @typeParam T - The type of the container that may be vivified (the source/parent value).
+ */
+type WithVivify<T> = {
+    /**
+     * Whether, and as what shape, to create a missing container when the source value is
+     * `null`/`undefined` at write time. Defaults to `false` (no vivification). See {@link Vivify}.
+     */
+    vivify?: Vivify<T>;
+};
+
 /**
  * Options for creating a derived signal using the full `derived` function signature.
  * @typeParam T - The type of the source signal's value (parent).
@@ -290,7 +339,10 @@ declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDerivedOpti
  * @typeParam TKey The key of the property to derive.
  * @param source The source `WritableSignal` (holding an object).
  * @param key The key of the property to derive.
- * @param options Optional signal options for the derived signal.
+ * @param options Optional signal options for the derived signal. Also accepts a
+ * {@link Vivify} `vivify` flag (off by default) that, when set, creates the missing
+ * container instead of dropping a write made through a `null`/`undefined` source —
+ * e.g. `derived(user, 'name', { vivify: 'object' })`. See {@link WithVivify}.
  * @returns A `DerivedSignal` instance.
  *
  * @example
@@ -306,7 +358,7 @@ declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDerivedOpti
  * console.log(user().name); // Outputs: Jane
  * ```
  */
-declare function derived<T extends object, TKey extends keyof T>(source: MutableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]> & MutableSignal<T[TKey]>;
+declare function derived<T extends object, TKey extends keyof T>(source: MutableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]> & WithVivify<T>): DerivedSignal<T, T[TKey]> & MutableSignal<T[TKey]>;
 /**
  * Creates a `DerivedSignal` that derives a property from an object held by the source signal.
  * This overload is a convenient shorthand for accessing object properties.
@@ -315,7 +367,10 @@ declare function derived<T extends object, TKey extends keyof T>(source: Mutable
  * @typeParam TKey The key of the property to derive.
  * @param source The source `WritableSignal` (holding an object).
  * @param key The key of the property to derive.
- * @param options Optional signal options for the derived signal.
+ * @param options Optional signal options for the derived signal. Also accepts a
+ * {@link Vivify} `vivify` flag (off by default) that, when set, creates the missing
+ * container instead of dropping a write made through a `null`/`undefined` source —
+ * e.g. `derived(user, 'name', { vivify: 'object' })`. See {@link WithVivify}.
  * @returns A `DerivedSignal` instance.
  *
  * @example
@@ -331,7 +386,7 @@ declare function derived<T extends object, TKey extends keyof T>(source: Mutable
  * console.log(user().name); // Outputs: Jane
  * ```
  */
-declare function derived<T extends object, TKey extends keyof T>(source: WritableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]>;
+declare function derived<T extends object, TKey extends keyof T>(source: WritableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]> & WithVivify<T>): DerivedSignal<T, T[TKey]>;
 /**
  * Creates a `DerivedSignal` that derives its value from another `MutableSignal`.
  * Use mutuable signals with caution, but very useful for deeply nested structures.
@@ -354,7 +409,7 @@ declare function derived<T extends object, TKey extends keyof T>(source: Writabl
  * console.log(user().name); // Outputs: Jane
  * ```
  */
-declare function derived<T, U>(source: MutableSignal<T>, optOrKey: CreateDerivedOptions<T, U> | keyof T, opt?: CreateSignalOptions<U>): DerivedSignal<T, U> & MutableSignal<U>;
+declare function derived<T, U>(source: MutableSignal<T>, optOrKey: CreateDerivedOptions<T, U> | keyof T, opt?: CreateSignalOptions<U> & WithVivify<T>): DerivedSignal<T, U> & MutableSignal<U>;
 /**
  * Creates a `DerivedSignal` from an array, deriving an element by its index.
  * This overload is a convenient shorthand for accessing array elements.
@@ -362,7 +417,10 @@ declare function derived<T, U>(source: MutableSignal<T>, optOrKey: CreateDerived
  * @typeParam T The type of the source signal's value (must be an array).
  * @param source The source `WritableSignal` (holding an array).
  * @param index The index of the element to derive.
- * @param options Optional signal options for the derived signal.
+ * @param options Optional signal options for the derived signal. Also accepts a
+ * {@link Vivify} `vivify` flag (off by default) that, when set, creates the missing
+ * container instead of dropping a write made through a `null`/`undefined` source —
+ * e.g. `derived(user, 'name', { vivify: 'object' })`. See {@link WithVivify}.
  * @returns A `DerivedSignal` instance.
  *
  * @example
@@ -378,7 +436,7 @@ declare function derived<T, U>(source: MutableSignal<T>, optOrKey: CreateDerived
  * console.log(numbers()); // Outputs: [1, 5, 3]
  * ```
  */
-declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]>): DerivedSignal<T, T[number]>;
+declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]> & WithVivify<T>): DerivedSignal<T, T[number]>;
 /**
  * Creates a "fake" `DerivedSignal` from a simple value. This is useful for creating
  * `FormControlSignal` instances that are not directly derived from another signal.
@@ -1938,7 +1996,26 @@ type ResolvableTarget = EventTargetLike | Signal<EventTargetLike | null>;
 declare function signalFromEvent<TEvent extends Event>(target: ResolvableTarget, eventName: string, initial: TEvent | null, opt?: SignalFromEventOptions): Signal<TEvent | null>;
 declare function signalFromEvent<TEvent extends Event, U>(target: ResolvableTarget, eventName: string, initial: U, project: (event: TEvent) => U, opt?: SignalFromEventOptions): Signal<U>;
 
-type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp;
+/**
+ * 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}.
+ */
+declare const OPAQUE: unique symbol;
+/**
+ * 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.
+ */
+type Opaque<T> = T & {
+    readonly [OPAQUE]: true;
+};
+/** @internal Strips the opaque brand from the value a leaf signal carries. */
+type Unwrap<T> = T extends {
+    readonly [OPAQUE]: true;
+} ? Omit<T, typeof OPAQUE> : T;
+type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp | {
+    readonly [OPAQUE]: true;
+};
 type Key = string | number;
 type AnyRecord = Record<Key, any>;
 /**
@@ -1963,28 +2040,75 @@ type MutableArrayStore<T extends any[]> = MutableSignal<T> & {
     readonly length: Signal<number>;
     [Symbol.iterator](): Iterator<MutableSignalStore<T[number]>>;
 };
-type SignalStore<T> = Signal<T> & (NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? SignalArrayStore<NonNullable<T>> : Readonly<{
+/**
+ * @internal Resolves to `true` only for `any`. In a conditional type, `any` distributes across
+ * *both* branches (`unknown | object`), and `unknown | X` collapses to `unknown` — which would
+ * erase a store's property access and `extend`. Guarding on this routes an `any`-typed store to
+ * the full object shape instead.
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * @internal Flattens an intersection (`A & B & C`) into a single object literal so editor
+ * tooltips show the resolved members instead of the raw intersection chain. Display-only —
+ * structurally identical to its input.
+ */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** @internal The object shape of a readonly store: a child store per key, plus `extend`. */
+type SignalStoreObject<T> = Simplify<Readonly<{
     [K in keyof Required<T>]: SignalStore<NonNullable<T>[K]>;
-}>);
-type WritableSignalStore<T> = WritableSignal<T> & {
-    readonly asReadonlyStore: () => SignalStore<T>;
-} & (NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? WritableArrayStore<NonNullable<T>> : Readonly<{
+}> & {
+    readonly extend: {
+        <L extends AnyRecord>(source: Signal<L>): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+        <L extends AnyRecord>(props: L): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+    };
+}>;
+/** @internal The object shape of a writable store. */
+type WritableSignalStoreObject<T> = Simplify<Readonly<{
     [K in keyof Required<T>]: WritableSignalStore<NonNullable<T>[K]>;
-}>);
-type MutableSignalStore<T> = MutableSignal<T> & {
-    readonly asReadonlyStore: () => SignalStore<T>;
-} & (NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? MutableArrayStore<NonNullable<T>> : Readonly<{
+}> & {
+    readonly extend: {
+        <L extends AnyRecord>(source: WritableSignal<L>): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+        <L extends AnyRecord>(props: L): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+    };
+}>;
+/** @internal The object shape of a mutable store. */
+type MutableSignalStoreObject<T> = Simplify<Readonly<{
     [K in keyof Required<T>]: MutableSignalStore<NonNullable<T>[K]>;
-}>);
-declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector): MutableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector): WritableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector): SignalStore<T>;
+}> & {
+    readonly extend: {
+        <L extends AnyRecord>(source: MutableSignal<L>): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+        <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>> & {
+    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>> & {
+    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>;
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
  */
 declare function store<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<T> & {
     injector?: Injector;
+    /**
+     * Opt-in autovivification: when writing through a `null`/`undefined` path, create the
+     * missing intermediate containers instead of dropping the write. Off by default.
+     *
+     * Levels whose current value is a known object/array re-vivify as that same shape — the
+     * knowledge is captured when the path is first accessed and cached, so it holds even after
+     * the value is later nulled. This option governs only genuinely-unknown (currently
+     * `null`/`undefined`) levels: `'auto'` (an array for index keys, an object otherwise), an
+     * explicit `'object'`/`'array'`, or a `() => container` factory. See {@link Vivify}.
+     */
+    vivify?: Vivify;
 }): WritableSignalStore<T>;
 /**
  * Creates a MutableSignalStore from a value.
@@ -1992,7 +2116,30 @@ declare function store<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<
  */
 declare function mutableStore<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<T> & {
     injector?: Injector;
+    /**
+     * Opt-in autovivification: when writing through a `null`/`undefined` path, create the
+     * missing intermediate containers instead of dropping the write. Off by default.
+     *
+     * Levels whose current value is a known object/array re-vivify as that same shape — the
+     * knowledge is captured when the path is first accessed and cached, so it holds even after
+     * the value is later nulled. This option governs only genuinely-unknown (currently
+     * `null`/`undefined`) levels: `'auto'` (an array for index keys, an object otherwise), an
+     * explicit `'object'`/`'array'`, or a `() => container` factory. See {@link Vivify}.
+     */
+    vivify?: Vivify;
 }): 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.
@@ -2421,5 +2568,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, 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, PipeableSignal, ScreenOrientation, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalFromEventOptions, SignalStore, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal, WritableSignalStore };
+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 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 };

package/package.json

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