@mmstack/primitives 19.3.7 → 19.3.9

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, mutableStore, opaque, store, toStore, type MutableSignalStore, type Opaque, type SignalStore, type WritableSignalStore, } 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/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/store.d.ts

@@ -1,8 +1,43 @@
 import { Injector, type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
 import { type MutableSignal } from './mutable';
-type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp;
+import { type Vivify } from './util';
+/**
+ * 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}.
+ */
+export 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.
+ */
+export 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>;
+/**
+ * @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 +60,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]>;
-}>);
-export 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]>;
-}>);
-export 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]>;
-}>);
-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>;
+}> & {
+    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<Unwrap<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<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>);
+export 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>);
+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 +136,28 @@ 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>;
+/**
+ * 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 } }));
+ */
+export declare function opaque<T extends object>(value: T): Opaque<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}`;

package/lib/util/vivify.d.ts

@@ -0,0 +1,63 @@
+/** @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' }
+ * ```
+ */
+export 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).
+ */
+export 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>;
+};
+/**
+ * @internal
+ * A resolved vivification function, produced by {@link createVivify}. Given the `current` value
+ * and the `key` about to be written, it returns the container to write into: the current value
+ * when present, or a freshly created one when `current` is `null`/`undefined`.
+ */
+export type VivifyFn<T> = (current: T, key: PropertyKey) => T;
+/**
+ * @internal
+ * Resolves a {@link Vivify} option into a {@link VivifyFn}. The returned function leaves a
+ * present value untouched and only creates a new container — object, array, or factory result —
+ * when the current value is `null`/`undefined`.
+ */
+export declare function createVivify<T>(option: Vivify<T>): VivifyFn<T>;
+export {};

package/package.json

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