@mmstack/primitives 21.0.24 → 21.0.26

package/package.json

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

package/types/mmstack-primitives.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.
@@ -1963,28 +2021,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]>;
-}>);
+}> & {
+    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]>;
+}> & {
+    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]>;
+}> & {
+    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<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<T> & {
     readonly asReadonlyStore: () => SignalStore<T>;
-} & (NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? WritableArrayStore<NonNullable<T>> : Readonly<{
-    [K in keyof Required<T>]: WritableSignalStore<NonNullable<T>[K]>;
-}>);
+} & (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<T> & {
     readonly asReadonlyStore: () => SignalStore<T>;
-} & (NonNullable<T> extends BaseType ? unknown : NonNullable<T> extends Array<any> ? MutableArrayStore<NonNullable<T>> : 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>;
+} & (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,6 +2097,17 @@ 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>;
 
 /**
@@ -2422,4 +2538,4 @@ 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 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, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore };