@mmstack/primitives 19.3.6 → 19.3.8

package/index.d.ts

@@ -6,12 +6,12 @@ export * from './lib/mappers';
 export * from './lib/mutable';
 export * from './lib/pipeable/public_api';
 export * from './lib/pooled';
-export * from './lib/provided-pools';
 export * from './lib/sensors';
-export * from './lib/store';
+export { isStore, store, mutableStore, toStore, type SignalStore, type WritableSignalStore, type MutableSignalStore, } from './lib/store';
 export * from './lib/stored';
 export { tabSync } from './lib/tabSync';
 export * from './lib/throttled';
 export * from './lib/to-writable';
 export * from './lib/until';
+export type { Vivify, WithVivify } from './lib/util';
 export * from './lib/with-history';

package/lib/derived.d.ts

@@ -1,5 +1,6 @@
 import { type CreateSignalOptions, type WritableSignal } from '@angular/core';
 import { type MutableSignal } from './mutable';
+import { type WithVivify } from './util';
 /**
  * Options for creating a derived signal using the full `derived` function signature.
  * @typeParam T - The type of the source signal's value (parent).
@@ -62,7 +63,10 @@ export declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDeri
  * @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
@@ -78,7 +82,7 @@ export declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDeri
  * console.log(user().name); // Outputs: Jane
  * ```
  */
-export 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]>;
+export 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.
@@ -87,7 +91,10 @@ export declare function derived<T extends object, TKey extends keyof T>(source:
  * @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
@@ -103,7 +110,7 @@ export declare function derived<T extends object, TKey extends keyof T>(source:
  * console.log(user().name); // Outputs: Jane
  * ```
  */
-export declare function derived<T extends object, TKey extends keyof T>(source: WritableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]>;
+export 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.
@@ -126,7 +133,7 @@ export declare function derived<T extends object, TKey extends keyof T>(source:
  * console.log(user().name); // Outputs: Jane
  * ```
  */
-export declare function derived<T, U>(source: MutableSignal<T>, optOrKey: CreateDerivedOptions<T, U> | keyof T, opt?: CreateSignalOptions<U>): DerivedSignal<T, U> & MutableSignal<U>;
+export 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.
@@ -134,7 +141,10 @@ export declare function derived<T, U>(source: MutableSignal<T>, optOrKey: Create
  * @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
@@ -150,7 +160,7 @@ export declare function derived<T, U>(source: MutableSignal<T>, optOrKey: Create
  * console.log(numbers()); // Outputs: [1, 5, 3]
  * ```
  */
-export declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]>): DerivedSignal<T, T[number]>;
+export 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.

package/lib/mappers/key-array.d.ts

@@ -15,7 +15,30 @@ import { type Signal } from '@angular/core';
  * @param mapFn The mapping function. Receives the item and its index as a Signal.
  * @param options Optional configuration:
  *  - `onDestroy`: A callback invoked when a mapped item is removed from the array.
+ *  - `key`: A custom key extractor for identity matching (e.g. `(item) => item.id`)
+ *    when item references change but conceptual identity is preserved.
  * @returns A `Signal<U[]>` containing the mapped array.
+ *
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ * ]);
+ *
+ * const rows = keyArray(
+ *   users,
+ *   (user, index) => ({
+ *     label: computed(() => `#${index()} ${user.name}`),
+ *     id: user.id,
+ *   }),
+ *   { key: (u) => u.id },
+ * );
+ *
+ * // Reordering users() rebuilds index signals only — `rows` entries
+ * // are matched by id and reused, not re-created.
+ * users.set([users()[1], users()[0]]);
+ * ```
  */
 export declare function keyArray<T, U, K>(source: Signal<T[]> | (() => T[]), mapFn: (v: T, i: Signal<number>) => U, options?: {
     onDestroy?: (value: U) => void;

package/lib/mappers/map-object.d.ts

@@ -3,12 +3,71 @@ import { type MutableSignal } from '../mutable';
 type MappedObject<T extends object, U> = {
     [K in keyof T]: U;
 };
+/**
+ * Reactively maps each property of an object signal into a new object,
+ * preserving the same set of keys. For each key, `mapFn` receives a stable
+ * per-key signal — outputs for keys that haven't been added or removed are
+ * reused on subsequent reads. Sibling to {@link indexArray} / {@link keyArray}
+ * but for object records.
+ *
+ * The type of per-key signal passed into `mapFn` depends on the source:
+ * - `MutableSignal<T>` source → `MutableSignal<T[K]>` (in-place mutation)
+ * - `WritableSignal<T>` source → `WritableSignal<T[K]>` (two-way binding)
+ * - read-only `Signal<T>` or `() => T` source → read-only `Signal<T[K]>`
+ *
+ * @typeParam T The object type held by the source signal.
+ * @typeParam U The type produced for each key by `mapFn`.
+ *
+ * @param source A `MutableSignal<T>` whose properties are mapped with full
+ *   in-place mutation capability via the per-key `MutableSignal`.
+ * @param mapFn Receives each key and its per-key `MutableSignal<T[K]>`.
+ * @param options Optional `onDestroy(value)` callback fired when a key is
+ *   removed from the source.
+ * @returns A read-only signal of the mapped object.
+ *
+ * @example
+ * ```ts
+ * const state = mutable({ name: 'Alice', age: 30 });
+ * const view = mapObject(state, (key, prop) => ({
+ *   label: key,
+ *   current: computed(() => prop()),
+ *   onInput: (next: any) => prop.set(next),
+ * }));
+ * view().age.onInput(31);
+ * state(); // { name: 'Alice', age: 31 }
+ * ```
+ */
 export declare function mapObject<T extends object, U>(source: MutableSignal<T>, mapFn: <K extends keyof T>(key: K, value: MutableSignal<T[K]>) => U, options?: {
     onDestroy?: (value: U) => void;
 }): Signal<MappedObject<T, U>>;
+/**
+ * Reactively maps each property of a `WritableSignal<T>` into a new object.
+ * Each key's per-property signal supports `.set` / `.update` for two-way
+ * binding back into the parent object.
+ *
+ * @example
+ * ```ts
+ * const user = signal({ name: 'Alice', age: 30 });
+ * const inputs = mapObject(user, (key, prop) => ({
+ *   value: prop,
+ *   setValue: (v: any) => prop.set(v),
+ * }));
+ * ```
+ */
 export declare function mapObject<T extends object, U>(source: WritableSignal<T>, mapFn: <K extends keyof T>(key: K, value: WritableSignal<T[K]>) => U, options?: {
     onDestroy?: (value: U) => void;
 }): Signal<MappedObject<T, U>>;
+/**
+ * Reactively maps each property of a read-only `Signal<T>` (or plain `() => T`
+ * accessor) into a new object. Per-key signals are read-only.
+ *
+ * @example
+ * ```ts
+ * const config = computed(() => ({ theme: 'dark', density: 'compact' }));
+ * const view = mapObject(config, (key, prop) => `${key}: ${prop()}`);
+ * view(); // { theme: 'theme: dark', density: 'density: compact' }
+ * ```
+ */
 export declare function mapObject<T extends object, U>(source: (() => T) | Signal<T>, mapFn: <K extends keyof T>(key: K, value: Signal<T[K]>) => U, options?: {
     onDestroy?: (value: U) => void;
 }): Signal<MappedObject<T, U>>;

package/lib/pipeable/operators.d.ts

@@ -1,25 +1,133 @@
 import { type CreateSignalOptions, type Injector, type Signal } from '@angular/core';
 import { type Operator } from './types';
-/** Project with optional equality. Pure & sync. */
+/**
+ * Synchronous projection of a signal value with optional `CreateSignalOptions`
+ * (custom `equal`, `debugName`, etc.). Equivalent to `map` plus the ability to
+ * pass signal options through to the underlying `computed()`.
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, name: 'Alice' });
+ * const name = user.pipe(select((u) => u.name));
+ * name(); // 'Alice'
+ * ```
+ */
 export declare const select: <I, O>(projector: (v: I) => O, opt?: CreateSignalOptions<O>) => Operator<I, O>;
-/** Combine with another signal using a projector. */
+/**
+ * Combine the piped signal with another `Signal` using a projector. The result
+ * recomputes whenever either source changes.
+ *
+ * @example
+ * ```ts
+ * const price = piped(10);
+ * const quantity = signal(3);
+ * const total = price.pipe(combineWith(quantity, (p, q) => p * q));
+ * total(); // 30
+ * ```
+ */
 export declare const combineWith: <A, B, R>(other: Signal<B>, project: (a: A, b: B) => R, opt?: CreateSignalOptions<R>) => Operator<A, R>;
-/** Only re-emit when equal(prev, next) is false. */
+/**
+ * Suppress emissions while consecutive values are considered equal. The
+ * comparator defaults to `Object.is`; pass a custom one for structural or
+ * key-based equality (e.g. compare by `id` only).
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, lastSeen: Date.now() });
+ * const byId = user.pipe(distinct((a, b) => a.id === b.id));
+ * // byId only re-emits when `id` changes, not on every `lastSeen` update
+ * ```
+ */
 export declare const distinct: <T>(equal?: (a: T, b: T) => boolean) => Operator<T, T>;
-/** map to new value */
+/**
+ * Pure synchronous transform from input to output. Equivalent to a `computed()`
+ * that reads the source and returns `fn(value)`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(2);
+ * const doubled = count.pipe(map((n) => n * 2));
+ * doubled(); // 4
+ * ```
+ */
 export declare const map: <I, O>(fn: (v: I) => O) => Operator<I, O>;
-/** filter values, keeping the last value if it was ever available, if first value is filtered will return undefined */
+/**
+ * Keep only values that pass the predicate. The result holds the last passing
+ * value across emissions; before any value passes, the result is `undefined` —
+ * see {@link filterWith} when you need a non-`undefined` seed.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const clicks = event.pipe(filter((e): e is MouseEvent => e?.type === 'click'));
+ * clicks(); // undefined until a click happens, then the last MouseEvent
+ * ```
+ */
 export declare const filter: <T>(predicate: (v: T) => boolean) => Operator<T, T | undefined>;
-/** tap into the value */
+/**
+ * Run a side effect on every emission without altering the signal value. Wraps
+ * Angular's `effect()`, so it must run in an injection context or receive an
+ * explicit `injector`. Use for logging / analytics — not for setting other
+ * signals (that's what regular `effect()` is for).
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * count.pipe(tap((n) => console.log('count:', n)));
+ * count.set(1); // logs 'count: 1'
+ * ```
+ */
 export declare const tap: <T>(fn: (v: T) => void, injector?: Injector) => Operator<T, T>;
 /**
- * Like {@link filter}, but emits `initial` until a value passes the predicate
- * for the first time. Avoids the `T | undefined` return type.
+ * Like {@link filter}, but emits `initial` until a value first passes the
+ * predicate. Eliminates the `T | undefined` return type at the cost of an
+ * explicit seed value.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const lastClick = event.pipe(filterWith((e) => e?.type === 'click', null));
+ * lastClick(); // null until the first click, then the most recent click event
+ * ```
  */
 export declare const filterWith: <T>(predicate: (v: T) => boolean, initial: T) => Operator<T, T>;
-/** Emits `initial` first, then mirrors source. */
+/**
+ * Emit `initial` on the first read, then mirror the source on every subsequent
+ * read. Useful for giving a pipeline a sensible seed value before the source
+ * is ready (e.g. loading state).
+ *
+ * @example
+ * ```ts
+ * const data = piped<User | null>(null);
+ * const view = data.pipe(startWith<User | null, 'loading'>('loading'));
+ * view(); // 'loading' on first read, then User | null afterward
+ * ```
+ */
 export declare const startWith: <T, U>(initial: U) => Operator<T, T | U>;
-/** Emits `[prev, curr]` pairs. The first emission has prev = undefined. */
+/**
+ * Emit `[prev, curr]` tuples so consumers can react to transitions instead of
+ * raw values. On the first emission `prev` is `undefined`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * const delta = count.pipe(pairwise(), map(([prev, curr]) => curr - (prev ?? 0)));
+ * count.set(5);
+ * delta(); // 5
+ * ```
+ */
 export declare const pairwise: <T>() => Operator<T, [T | undefined, T]>;
-/** Reduce-like accumulator across emissions. */
+/**
+ * Reduce-like accumulator that folds each emission into a running result.
+ * Behaves like `Array.prototype.reduce` but applied over time, with the
+ * accumulator persisted across emissions.
+ *
+ * @example
+ * ```ts
+ * const delta = piped(0);
+ * const total = delta.pipe(scan((acc, n) => acc + n, 0));
+ * delta.set(5); // total() === 5
+ * delta.set(3); // total() === 8
+ * ```
+ */
 export declare const scan: <T, R>(reducer: (acc: R, curr: T) => R, seed: R) => Operator<T, R>;

package/lib/pooled/index.d.ts

@@ -0,0 +1,2 @@
+export * from './pooled';
+export * from './provided-pools';

package/lib/{provided-pools.d.ts → pooled/provided-pools.d.ts}

@@ -1,5 +1,5 @@
 import type { CreateSignalOptions, Signal } from '@angular/core';
-import { type Computation, type CreatePooledOptions } from './pooled';
+import { type Computation, type CreatePooledOptions } from '.';
 /**
  * Options for the preset pool helpers. Same shape as
  * {@link CreatePooledOptions}, with `create` and `reset` made optional — each

package/lib/sensors/battery-status.d.ts

@@ -10,5 +10,14 @@ export type BatteryStatus = {
  * Battery Status API. Returns `null` until the underlying `getBattery()`
  * promise resolves, or permanently when the API is unsupported (Firefox /
  * Safari at the time of writing). SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const battery = batteryStatus();
+ * effect(() => {
+ *   const b = battery();
+ *   if (b) console.log(`${Math.round(b.level * 100)}% • charging: ${b.charging}`);
+ * });
+ * ```
  */
 export declare function batteryStatus(debugName?: string): Signal<BatteryStatus | null>;

package/lib/sensors/focus-within.d.ts

@@ -7,6 +7,15 @@ type FocusWithinTarget = ElementRef<Element> | Element | Signal<ElementRef<Eleme
  * Defaults `target` to the current `ElementRef` so it can be used inline in a
  * component's `class` field. SSR-safe — returns a constant `false` signal on
  * the server.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MenuComponent {
+ *   // Defaults to the host element — flips true when focus is inside.
+ *   readonly hasFocus = focusWithin();
+ * }
+ * ```
  */
 export declare function focusWithin(target?: FocusWithinTarget): Signal<boolean>;
 export {};

package/lib/sensors/idle.d.ts

@@ -23,5 +23,13 @@ export type IdleSignal = Signal<boolean> & {
  * activity) resets the timer and flips the signal back to `false`.
  *
  * SSR-safe — always `false` with a frozen `since` date on the server.
+ *
+ * @example
+ * ```ts
+ * const isAway = idle({ ms: 30_000 });
+ * effect(() => {
+ *   if (isAway()) console.log('idle since', isAway.since());
+ * });
+ * ```
  */
 export declare function idle(opt?: IdleOptions): IdleSignal;

package/lib/sensors/network-status.d.ts

@@ -16,5 +16,13 @@ export type NetworkStatusSignal = Signal<boolean> & {
  *
  * @param debugName Optional debug name for the signal.
  * @returns A `NetworkStatusSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const online = networkStatus();
+ * effect(() => {
+ *   if (!online()) console.log('offline since', online.since());
+ * });
+ * ```
  */
 export declare function networkStatus(debugName?: string): NetworkStatusSignal;

package/lib/sensors/orientation.d.ts

@@ -10,5 +10,14 @@ export type ScreenOrientation = {
  *
  * SSR-safe — returns a constant `portrait-primary / 0°` signal on the server
  * and in environments without `screen.orientation` support.
+ *
+ * @example
+ * ```ts
+ * const screenOrientation = orientation();
+ * effect(() => {
+ *   const { type, angle } = screenOrientation();
+ *   console.log(`${type} at ${angle}°`);
+ * });
+ * ```
  */
 export declare function orientation(debugName?: string): Signal<ScreenOrientation>;

package/lib/sensors/sensor.d.ts

@@ -226,5 +226,26 @@ type SensorsOptions<TKey extends keyof SensorTypedOptions> = {
 type Sensors<TKey extends keyof SensorTypedOptions> = {
     [K in TKey]: SensorTypedOptions[K]['returnType'];
 };
+/**
+ * Bulk sensor factory — creates several sensor signals at once and returns
+ * them keyed by sensor type. Convenient when a single consumer needs to react
+ * to multiple browser signals; for a single sensor prefer {@link sensor}
+ * directly.
+ *
+ * @typeParam TType The union of sensor keys being requested.
+ * @param track Array of sensor type keys to create.
+ * @param opt Optional per-sensor options keyed by sensor type.
+ * @returns A record `{ [key]: <SensorReturnType> }` for each requested key.
+ *
+ * @example
+ * ```ts
+ * const { windowSize, networkStatus } = sensors(
+ *   ['windowSize', 'networkStatus'],
+ *   { windowSize: { throttle: 200 } },
+ * );
+ *
+ * effect(() => console.log(windowSize(), networkStatus()));
+ * ```
+ */
 export declare function sensors<const TType extends keyof SensorTypedOptions>(track: TType[], opt?: SensorsOptions<TType>): Sensors<TType>;
 export {};

package/lib/store.d.ts

@@ -1,8 +1,24 @@
 import { Injector, type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
 import { type MutableSignal } from './mutable';
+import { type Vivify } from './util';
 type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp;
 type Key = string | number;
 type AnyRecord = Record<Key, any>;
+/**
+ * @internal
+ * Test-only handle on the proxy cache (deliberately NOT re-exported from the public barrel).
+ * Maps a store's backing signal to its lazily-built child proxies, each held via a `WeakRef`.
+ */
+export declare const PROXY_CACHE: WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
+/**
+ * @internal
+ * Test-only handle on the finalization registry (deliberately NOT re-exported from the public
+ * barrel). Prunes a cache entry once its proxy is reclaimed by the GC.
+ */
+export declare const PROXY_CLEANUP: FinalizationRegistry<{
+    target: object;
+    prop: PropertyKey;
+}>;
 /**
  * @internal
  * Validates whether a value is a Signal Store.
@@ -25,28 +41,75 @@ type MutableArrayStore<T extends any[]> = MutableSignal<T> & {
     readonly length: Signal<number>;
     [Symbol.iterator](): Iterator<MutableSignalStore<T[number]>>;
 };
-export 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>>;
+    };
+}>;
+export 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>);
 export 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>);
 export 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]>;
-}>);
-export declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector): MutableSignalStore<T>;
-export declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector): WritableSignalStore<T>;
-export 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>);
+export declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify): MutableSignalStore<T>;
+export declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify): WritableSignalStore<T>;
+export declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify): SignalStore<T>;
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
  */
 export 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.
@@ -54,5 +117,16 @@ export declare function store<T extends AnyRecord>(value: T, opt?: CreateSignalO
  */
 export 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>;
 export {};

package/lib/util/index.d.ts

@@ -0,0 +1,2 @@
+export * from './is-index-prop';
+export * from './vivify';

package/lib/util/is-index-prop.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @internal
+ * Type guard for an array-index-like property key: a non-empty string that parses to a finite
+ * number (e.g. `'0'`, `'42'`). Used to choose array-vs-object shape during autovivification and
+ * deep store proxying.
+ */
+export declare function isIndexProp(prop: PropertyKey): prop is `${number}`;