@zeix/cause-effect 0.17.3 → 0.18.0

package/types/src/graph.d.ts

@@ -0,0 +1,208 @@
+import { type Guard } from './errors';
+type SourceFields<T extends {}> = {
+    value: T;
+    sinks: Edge | null;
+    sinksTail: Edge | null;
+    stop?: Cleanup;
+};
+type OptionsFields<T extends {}> = {
+    equals: (a: T, b: T) => boolean;
+    guard?: Guard<T>;
+};
+type SinkFields = {
+    fn: unknown;
+    flags: number;
+    sources: Edge | null;
+    sourcesTail: Edge | null;
+};
+type OwnerFields = {
+    cleanup: Cleanup | Cleanup[] | null;
+};
+type AsyncFields = {
+    controller: AbortController | undefined;
+    error: Error | undefined;
+};
+type StateNode<T extends {}> = SourceFields<T> & OptionsFields<T>;
+type MemoNode<T extends {}> = SourceFields<T> & OptionsFields<T> & SinkFields & {
+    fn: MemoCallback<T>;
+    error: Error | undefined;
+};
+type TaskNode<T extends {}> = SourceFields<T> & OptionsFields<T> & SinkFields & AsyncFields & {
+    fn: (prev: T, abort: AbortSignal) => Promise<T>;
+};
+type EffectNode = SinkFields & OwnerFields & {
+    fn: EffectCallback;
+};
+type Scope = OwnerFields;
+type SourceNode = SourceFields<unknown & {}>;
+type SinkNode = MemoNode<unknown & {}> | TaskNode<unknown & {}> | EffectNode;
+type OwnerNode = EffectNode | Scope;
+type Edge = {
+    source: SourceNode;
+    sink: SinkNode;
+    nextSource: Edge | null;
+    prevSink: Edge | null;
+    nextSink: Edge | null;
+};
+type Signal<T extends {}> = {
+    get(): T;
+};
+/**
+ * A cleanup function that can be called to dispose of resources.
+ */
+type Cleanup = () => void;
+type MaybeCleanup = Cleanup | undefined | void;
+/**
+ * Options for configuring signal behavior.
+ *
+ * @template T - The type of value in the signal
+ */
+type SignalOptions<T extends {}> = {
+    /**
+     * Optional type guard to validate values.
+     * If provided, will throw an error if an invalid value is set.
+     */
+    guard?: Guard<T>;
+    /**
+     * Optional custom equality function.
+     * Used to determine if a new value is different from the old value.
+     * Defaults to reference equality (===).
+     */
+    equals?: (a: T, b: T) => boolean;
+};
+type ComputedOptions<T extends {}> = SignalOptions<T> & {
+    /**
+     * Optional initial value.
+     * Useful for reducer patterns so that calculations start with a value of correct type.
+     */
+    value?: T;
+};
+/**
+ * A callback function for memos that computes a value based on the previous value.
+ *
+ * @template T - The type of value computed
+ * @param prev - The previous computed value
+ * @returns The new computed value
+ */
+type MemoCallback<T extends {}> = (prev: T | undefined) => T;
+/**
+ * A callback function for tasks that asynchronously computes a value.
+ *
+ * @template T - The type of value computed
+ * @param prev - The previous computed value
+ * @param signal - An AbortSignal that will be triggered if the task is aborted
+ * @returns A promise that resolves to the new computed value
+ */
+type TaskCallback<T extends {}> = (prev: T | undefined, signal: AbortSignal) => Promise<T>;
+/**
+ * A callback function for effects that can perform side effects.
+ *
+ * @param match - A function to register cleanup callbacks that will be called before the effect re-runs or is disposed
+ */
+type EffectCallback = () => MaybeCleanup;
+declare const TYPE_STATE = "State";
+declare const TYPE_MEMO = "Memo";
+declare const TYPE_TASK = "Task";
+declare const TYPE_SENSOR = "Sensor";
+declare const TYPE_LIST = "List";
+declare const TYPE_COLLECTION = "Collection";
+declare const TYPE_STORE = "Store";
+declare const FLAG_CLEAN = 0;
+declare const FLAG_DIRTY: number;
+declare let activeSink: SinkNode | null;
+declare let activeOwner: OwnerNode | null;
+declare let batchDepth: number;
+declare const DEFAULT_EQUALITY: <T extends {}>(a: T, b: T) => boolean;
+/**
+ * Equality function that always returns false, causing propagation on every update.
+ * Use with `createSensor` for observing mutable objects where the reference stays the same
+ * but internal state changes (e.g., DOM elements observed via MutationObserver).
+ *
+ * @example
+ * ```ts
+ * const el = createSensor<HTMLElement>((set) => {
+ *   const node = document.getElementById('box')!;
+ *   set(node);
+ *   const obs = new MutationObserver(() => set(node));
+ *   obs.observe(node, { attributes: true });
+ *   return () => obs.disconnect();
+ * }, { value: node, equals: SKIP_EQUALITY });
+ * ```
+ */
+declare const SKIP_EQUALITY: (_a?: unknown, _b?: unknown) => boolean;
+declare function link(source: SourceNode, sink: SinkNode): void;
+declare function unlink(edge: Edge): Edge | null;
+declare function trimSources(node: SinkNode): void;
+declare function propagate(node: SinkNode, newFlag?: number): void;
+declare function setState<T extends {}>(node: StateNode<T>, next: T): void;
+declare function registerCleanup(owner: OwnerNode, fn: Cleanup): void;
+declare function runCleanup(owner: OwnerNode): void;
+declare function runEffect(node: EffectNode): void;
+declare function refresh(node: SinkNode): void;
+declare function flush(): void;
+/**
+ * Batches multiple signal updates together.
+ * Effects will not run until the batch completes.
+ * Batches can be nested; effects run when the outermost batch completes.
+ *
+ * @param fn - The function to execute within the batch
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * const double = createMemo(() => count.get() * 2);
+ *
+ * batch(() => {
+ *   count.set(1);
+ *   count.set(2);
+ *   count.set(3);
+ *   // Effects run only once at the end with count = 3
+ * });
+ * ```
+ */
+declare function batch(fn: () => void): void;
+/**
+ * Runs a callback without tracking dependencies.
+ * Any signal reads inside the callback will not create edges to the current active sink.
+ *
+ * @param fn - The function to execute without tracking
+ * @returns The return value of the function
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * const label = createState('Count');
+ *
+ * createEffect(() => {
+ *   // Only re-runs when count changes, not when label changes
+ *   const name = untrack(() => label.get());
+ *   console.log(`${name}: ${count.get()}`);
+ * });
+ * ```
+ */
+declare function untrack<T>(fn: () => T): T;
+/**
+ * Creates a new ownership scope for managing cleanup of nested effects and resources.
+ * All effects created within the scope will be automatically disposed when the scope is disposed.
+ * Scopes can be nested - disposing a parent scope disposes all child scopes.
+ *
+ * @param fn - The function to execute within the scope, may return a cleanup function
+ * @returns A dispose function that cleans up the scope
+ *
+ * @example
+ * ```ts
+ * const dispose = createScope(() => {
+ *   const count = createState(0);
+ *
+ *   createEffect(() => {
+ *     console.log(count.get());
+ *   });
+ *
+ *   return () => console.log('Scope disposed');
+ * });
+ *
+ * dispose(); // Cleans up the effect and runs cleanup callbacks
+ * ```
+ */
+declare function createScope(fn: () => MaybeCleanup): Cleanup;
+export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY as defaultEquals, SKIP_EQUALITY, FLAG_CLEAN, FLAG_DIRTY, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_STORE, TYPE_TASK, unlink, untrack, };

package/types/src/nodes/collection.d.ts

@@ -0,0 +1,64 @@
+import { type Cleanup, type Signal } from '../graph';
+import { type DiffResult, type KeyConfig, type List } from './list';
+type CollectionSource<T extends {}> = List<T> | Collection<T>;
+type DeriveCollectionCallback<T extends {}, U extends {}> = ((sourceValue: U) => T) | ((sourceValue: U, abort: AbortSignal) => Promise<T>);
+type Collection<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'Collection';
+    readonly [Symbol.isConcatSpreadable]: true;
+    [Symbol.iterator](): IterableIterator<Signal<T>>;
+    keys(): IterableIterator<string>;
+    get(): T[];
+    at(index: number): Signal<T> | undefined;
+    byKey(key: string): Signal<T> | undefined;
+    keyAt(index: number): string | undefined;
+    indexOfKey(key: string): number;
+    deriveCollection<R extends {}>(callback: (sourceValue: T) => R): Collection<R>;
+    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R>;
+    readonly length: number;
+};
+type CollectionOptions<T extends {}> = {
+    value?: T[];
+    keyConfig?: KeyConfig<T>;
+    createItem?: (key: string, value: T) => Signal<T>;
+};
+type CollectionCallback = (applyChanges: (changes: DiffResult) => void) => Cleanup;
+/**
+ * Creates a derived Collection from a List or another Collection with item-level memoization.
+ * Sync callbacks use createMemo, async callbacks use createTask.
+ * Structural changes are tracked reactively via the source's keys.
+ *
+ * @since 0.18.0
+ * @param source - The source List or Collection to derive from
+ * @param callback - Transformation function applied to each item
+ * @returns A Collection signal
+ */
+declare function deriveCollection<T extends {}, U extends {}>(source: CollectionSource<U>, callback: (sourceValue: U) => T): Collection<T>;
+declare function deriveCollection<T extends {}, U extends {}>(source: CollectionSource<U>, callback: (sourceValue: U, abort: AbortSignal) => Promise<T>): Collection<T>;
+/**
+ * Creates an externally-driven Collection with a watched lifecycle.
+ * Items are managed by the start callback via `applyChanges(diffResult)`.
+ * The collection activates when first accessed by an effect and deactivates when no longer watched.
+ *
+ * @since 0.18.0
+ * @param start - Callback invoked when the collection starts being watched, receives applyChanges helper
+ * @param options - Optional configuration including initial value, key generation, and item signal creation
+ * @returns A read-only Collection signal
+ */
+declare function createCollection<T extends {}>(start: CollectionCallback, options?: CollectionOptions<T>): Collection<T>;
+/**
+ * Checks if a value is a Collection signal.
+ *
+ * @since 0.17.2
+ * @param value - The value to check
+ * @returns True if the value is a Collection
+ */
+declare function isCollection<T extends {}>(value: unknown): value is Collection<T>;
+/**
+ * Checks if a value is a valid Collection source (List or Collection).
+ *
+ * @since 0.17.2
+ * @param value - The value to check
+ * @returns True if the value is a List or Collection
+ */
+declare function isCollectionSource<T extends {}>(value: unknown): value is CollectionSource<T>;
+export { createCollection, deriveCollection, isCollection, isCollectionSource, type Collection, type CollectionCallback, type CollectionOptions, type CollectionSource, type DeriveCollectionCallback, };

package/types/src/nodes/effect.d.ts

@@ -0,0 +1,48 @@
+import { type Cleanup, type EffectCallback, type MaybeCleanup, type Signal } from '../graph';
+type MaybePromise<T> = T | Promise<T>;
+type MatchHandlers<T extends Signal<unknown & {}>[]> = {
+    ok: (values: {
+        [K in keyof T]: T[K] extends Signal<infer V> ? V : never;
+    }) => MaybePromise<MaybeCleanup>;
+    err?: (errors: readonly Error[]) => MaybePromise<MaybeCleanup>;
+    nil?: () => MaybePromise<MaybeCleanup>;
+};
+/**
+ * Creates a reactive effect that automatically runs when its dependencies change.
+ * Effects run immediately upon creation and re-run when any tracked signal changes.
+ * Effects are executed during the flush phase, after all updates have been batched.
+ *
+ * @since 0.1.0
+ * @param fn - The effect function that can track dependencies and register cleanup callbacks
+ * @returns A cleanup function that can be called to dispose of the effect
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * const dispose = createEffect(() => {
+ *   console.log('Count is:', count.get());
+ * });
+ *
+ * count.set(1); // Logs: "Count is: 1"
+ * dispose(); // Stop the effect
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With cleanup
+ * createEffect(() => {
+ *   const timer = setInterval(() => console.log(count.get()), 1000);
+ *   return () => clearInterval(timer);
+ * });
+ * ```
+ */
+declare function createEffect(fn: EffectCallback): Cleanup;
+/**
+ * Runs handlers based on the current values of signals.
+ * Must be called within an active owner (effect or scope) so async cleanup can be registered.
+ *
+ * @since 0.15.0
+ * @throws RequiredOwnerError If called without an active owner.
+ */
+declare function match<T extends Signal<unknown & {}>[]>(signals: T, handlers: MatchHandlers<T>): MaybeCleanup;
+export { type MaybePromise, type MatchHandlers, createEffect, match };

package/types/src/nodes/list.d.ts

@@ -0,0 +1,65 @@
+import { type Cleanup, TYPE_LIST } from '../graph';
+import { type Collection } from './collection';
+import { type State } from './state';
+type UnknownRecord = Record<string, unknown>;
+type DiffResult = {
+    changed: boolean;
+    add: UnknownRecord;
+    change: UnknownRecord;
+    remove: UnknownRecord;
+};
+type KeyConfig<T> = string | ((item: T) => string);
+type ListOptions<T extends {}> = {
+    keyConfig?: KeyConfig<T>;
+    watched?: () => Cleanup;
+};
+type List<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'List';
+    readonly [Symbol.isConcatSpreadable]: true;
+    [Symbol.iterator](): IterableIterator<State<T>>;
+    readonly length: number;
+    get(): T[];
+    set(newValue: T[]): void;
+    update(fn: (oldValue: T[]) => T[]): void;
+    at(index: number): State<T> | undefined;
+    keys(): IterableIterator<string>;
+    byKey(key: string): State<T> | undefined;
+    keyAt(index: number): string | undefined;
+    indexOfKey(key: string): number;
+    add(value: T): string;
+    remove(keyOrIndex: string | number): void;
+    sort(compareFn?: (a: T, b: T) => number): void;
+    splice(start: number, deleteCount?: number, ...items: T[]): T[];
+    deriveCollection<R extends {}>(callback: (sourceValue: T) => R): Collection<R>;
+    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R>;
+};
+/**
+ * Checks if two values are equal with cycle detection
+ *
+ * @since 0.15.0
+ * @param {T} a - First value to compare
+ * @param {T} b - Second value to compare
+ * @param {WeakSet<object>} visited - Set to track visited objects for cycle detection
+ * @returns {boolean} Whether the two values are equal
+ */
+/** Shallow equality check for string arrays */
+declare function keysEqual(a: string[], b: string[]): boolean;
+declare function isEqual<T>(a: T, b: T, visited?: WeakSet<object>): boolean;
+/**
+ * Creates a reactive list with stable keys and per-item reactivity.
+ *
+ * @since 0.18.0
+ * @param initialValue - Initial array of items
+ * @param options - Optional configuration for key generation and watch lifecycle
+ * @returns A List signal
+ */
+declare function createList<T extends {}>(initialValue: T[], options?: ListOptions<T>): List<T>;
+/**
+ * Checks if a value is a List signal.
+ *
+ * @since 0.15.0
+ * @param value - The value to check
+ * @returns True if the value is a List
+ */
+declare function isList<T extends {}>(value: unknown): value is List<T>;
+export { type DiffResult, type KeyConfig, type List, type ListOptions, type UnknownRecord, createList, isEqual, isList, keysEqual, TYPE_LIST, };

package/types/src/nodes/memo.d.ts

@@ -0,0 +1,57 @@
+import { type ComputedOptions, type MemoCallback } from '../graph';
+/**
+ * A derived reactive computation that caches its result.
+ * Automatically tracks dependencies and recomputes when they change.
+ *
+ * @template T - The type of value computed by the memo
+ */
+type Memo<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'Memo';
+    /**
+     * Gets the current value of the memo.
+     * Recomputes if dependencies have changed since last access.
+     * When called inside another reactive context, creates a dependency.
+     * @returns The computed value
+     * @throws UnsetSignalValueError If the memo value is still unset when read.
+     */
+    get(): T;
+};
+/**
+ * Creates a derived reactive computation that caches its result.
+ * The computation automatically tracks dependencies and recomputes when they change.
+ * Uses lazy evaluation - only computes when the value is accessed.
+ *
+ * @since 0.18.0
+ * @template T - The type of value computed by the memo
+ * @param fn - The computation function that receives the previous value
+ * @param options - Optional configuration for the memo
+ * @returns A Memo object with a get() method
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * const doubled = createMemo(() => count.get() * 2);
+ * console.log(doubled.get()); // 0
+ * count.set(5);
+ * console.log(doubled.get()); // 10
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Using previous value
+ * const sum = createMemo((prev) => prev + count.get(), { value: 0, equals: Object.is });
+ * ```
+ */
+declare function createMemo<T extends {}>(fn: (prev: T) => T, options: ComputedOptions<T> & {
+    value: T;
+}): Memo<T>;
+declare function createMemo<T extends {}>(fn: MemoCallback<T>, options?: ComputedOptions<T>): Memo<T>;
+/**
+ * Checks if a value is a Memo signal.
+ *
+ * @since 0.18.0
+ * @param value - The value to check
+ * @returns True if the value is a Memo
+ */
+declare function isMemo<T extends {} = unknown & {}>(value: unknown): value is Memo<T>;
+export { createMemo, isMemo, type Memo };

package/types/src/nodes/sensor.d.ts

@@ -0,0 +1,75 @@
+import { type Cleanup, type ComputedOptions } from '../graph';
+/**
+ * A read-only signal that tracks external input and updates a state value as long as it is active.
+ *
+ * @template T - The type of value produced by the sensor
+ */
+type Sensor<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'Sensor';
+    /**
+     * Gets the current value of the sensor.
+     * Updates its state value if the sensor is active.
+     * When called inside another reactive context, creates a dependency.
+     * @returns The sensor value
+     * @throws UnsetSignalValueError If the sensor value is still unset when read.
+     */
+    get(): T;
+};
+/**
+ * A callback function for sensors when the sensor starts being watched.
+ *
+ * @template T - The type of value observed
+ * @param set - A function to set the observed value
+ * @returns A cleanup function when the sensor stops being watched
+ */
+type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
+/**
+ * Creates a sensor that tracks external input and updates a state value as long as it is active.
+ * Sensors get activated when they are first accessed by an effect and deactivated when they are
+ * no longer watched. This lazy activation pattern ensures resources are only consumed when needed.
+ *
+ * @since 0.18.0
+ * @template T - The type of value stored in the state
+ * @param start - The callback function that starts the sensor and returns a cleanup function.
+ * @param options - Optional options for the sensor.
+ * @param options.value - Optional initial value. Avoids `UnsetSignalValueError` on first read
+ *   before the start callback fires. Essential for the mutable-object observation pattern.
+ * @param options.equals - Optional equality function. Defaults to `Object.is`. Use `SKIP_EQUALITY`
+ *   for mutable objects where the reference stays the same but internal state changes.
+ * @param options.guard - Optional type guard to validate values.
+ * @returns A read-only sensor signal.
+ *
+ * @example Tracking external values
+ * ```ts
+ * const mousePos = createSensor<{ x: number; y: number }>((set) => {
+ *   const handler = (e: MouseEvent) => {
+ *     set({ x: e.clientX, y: e.clientY });
+ *   };
+ *   window.addEventListener('mousemove', handler);
+ *   return () => window.removeEventListener('mousemove', handler);
+ * });
+ * ```
+ *
+ * @example Observing a mutable object
+ * ```ts
+ * import { createSensor, SKIP_EQUALITY } from 'cause-effect';
+ *
+ * const el = createSensor<HTMLElement>((set) => {
+ *   const node = document.getElementById('box')!;
+ *   set(node);
+ *   const obs = new MutationObserver(() => set(node));
+ *   obs.observe(node, { attributes: true });
+ *   return () => obs.disconnect();
+ * }, { value: node, equals: SKIP_EQUALITY });
+ * ```
+ */
+declare function createSensor<T extends {}>(start: SensorCallback<T>, options?: ComputedOptions<T>): Sensor<T>;
+/**
+ * Checks if a value is a Sensor signal.
+ *
+ * @since 0.18.0
+ * @param value - The value to check
+ * @returns True if the value is a Sensor
+ */
+declare function isSensor<T extends {} = unknown & {}>(value: unknown): value is Sensor<T>;
+export { createSensor, isSensor, type Sensor, type SensorCallback };

package/types/src/nodes/state.d.ts

@@ -0,0 +1,78 @@
+import { type SignalOptions } from '../graph';
+/**
+ * A callback function for states that updates a value based on the previous value.
+ *
+ * @template T - The type of value
+ * @param prev - The previous state value
+ * @returns The new state value
+ */
+type UpdateCallback<T extends {}> = (prev: T) => T;
+/**
+ * A mutable reactive state container.
+ * Changes to the state will automatically propagate to dependent computations and effects.
+ *
+ * @template T - The type of value stored in the state
+ */
+type State<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'State';
+    /**
+     * Gets the current value of the state.
+     * When called inside a memo, task, or effect, creates a dependency.
+     * @returns The current value
+     */
+    get(): T;
+    /**
+     * Sets a new value for the state.
+     * If the new value is different (according to the equality function), all dependents will be notified.
+     * @param next - The new value to set
+     */
+    set(next: T): void;
+    /**
+     * Updates the state with a new value computed by a callback function.
+     * The callback receives the current value as an argument.
+     * @param fn - The callback function to compute the new value
+     */
+    update(fn: UpdateCallback<T>): void;
+};
+/**
+ * Creates a mutable reactive state container.
+ *
+ * @since 0.9.0
+ * @template T - The type of value stored in the state
+ * @param value - The initial value
+ * @param options - Optional configuration for the state
+ * @returns A State object with get() and set() methods
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * count.set(1);
+ * console.log(count.get()); // 1
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With type guard
+ * const count = createState(0, {
+ *   guard: (v): v is number => typeof v === 'number'
+ * });
+ * ```
+ */
+declare function createState<T extends {}>(value: T, options?: SignalOptions<T>): State<T>;
+/**
+ * Checks if a value is a State signal.
+ *
+ * @since 0.9.0
+ * @param value - The value to check
+ * @returns True if the value is a State
+ *
+ * @example
+ * ```ts
+ * const state = createState(0);
+ * if (isState(state)) {
+ *   state.set(1); // TypeScript knows state has set()
+ * }
+ * ```
+ */
+declare function isState<T extends {} = unknown & {}>(value: unknown): value is State<T>;
+export { createState, isState, type State, type UpdateCallback };

package/types/src/nodes/store.d.ts

@@ -0,0 +1,51 @@
+import { type Cleanup, TYPE_STORE } from '../graph';
+import { type List, type UnknownRecord } from './list';
+import { type State } from './state';
+type StoreOptions = {
+    watched?: () => Cleanup;
+};
+type BaseStore<T extends UnknownRecord> = {
+    readonly [Symbol.toStringTag]: 'Store';
+    readonly [Symbol.isConcatSpreadable]: false;
+    [Symbol.iterator](): IterableIterator<[
+        string,
+        State<T[keyof T] & {}> | Store<UnknownRecord> | List<unknown & {}>
+    ]>;
+    keys(): IterableIterator<string>;
+    byKey<K extends keyof T & string>(key: K): T[K] extends readonly (infer U extends {})[] ? List<U> : T[K] extends UnknownRecord ? Store<T[K]> : T[K] extends unknown & {} ? State<T[K] & {}> : State<T[K] & {}> | undefined;
+    get(): T;
+    set(newValue: T): void;
+    update(fn: (oldValue: T) => T): void;
+    add<K extends keyof T & string>(key: K, value: T[K]): K;
+    remove(key: string): void;
+};
+type Store<T extends UnknownRecord> = BaseStore<T> & {
+    [K in keyof T]: T[K] extends readonly (infer U extends {})[] ? List<U> : T[K] extends UnknownRecord ? Store<T[K]> : T[K] extends unknown & {} ? State<T[K] & {}> : State<T[K] & {}> | undefined;
+};
+/**
+ * Creates a reactive store with deeply nested reactive properties.
+ * Each property becomes its own signal (State for primitives, nested Store for objects, List for arrays).
+ * Properties are accessible directly via proxy.
+ *
+ * @since 0.15.0
+ * @param initialValue - Initial object value of the store
+ * @param options - Optional configuration for watch lifecycle
+ * @returns A Store with reactive properties
+ *
+ * @example
+ * ```ts
+ * const user = createStore({ name: 'Alice', age: 30 });
+ * user.name.set('Bob'); // Only name subscribers react
+ * console.log(user.get()); // { name: 'Bob', age: 30 }
+ * ```
+ */
+declare function createStore<T extends UnknownRecord>(initialValue: T, options?: StoreOptions): Store<T>;
+/**
+ * Checks if a value is a Store signal.
+ *
+ * @since 0.15.0
+ * @param value - The value to check
+ * @returns True if the value is a Store
+ */
+declare function isStore<T extends UnknownRecord>(value: unknown): value is Store<T>;
+export { createStore, isStore, type Store, type StoreOptions, TYPE_STORE };