mutts 1.0.10 → 1.0.11

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { c as cleanup, S as ScopedCallback, d as EffectCloser, e as EffectAccess, f as State, a as Evolution, b as EffectCleanup, Z as ZoneAggregator, C as CatchFunction, E as EffectTrigger, g as EffectOptions } from './types-W5vD6m2n.js';
-export { A as AZone, h as CleanupReason, F as FunctionWrapper, P as PropTrigger, R as ReactiveError, i as ReactiveErrorCode, j as Zone, k as ZoneHistory, l as asyncZone, m as formatCleanupReason, n as isReactive, o as objectToProxy, p as proxyToObject, q as reactiveOptions, s as stopped, u as unwrap } from './types-W5vD6m2n.js';
+import { c as EffectAccess, d as EffectCloser, S as ScopedCallback, e as State, a as Evolution, b as EffectCleanup, Z as ZoneAggregator, C as CleanupReason, H as HistoryValue, E as EffectTrigger, f as CatchFunction, g as EffectOptions } from './types-Bx2PhORg.js';
+export { A as AZone, G as GetterWrapper, P as PropTrigger, R as ReactiveError, h as ReactiveErrorCode, i as Zone, j as ZoneHistory, k as asyncZone, l as debugPreset, m as devPreset, n as formatCleanupReason, o as isReactive, p as objectToProxy, q as prodPreset, r as proxyToObject, s as reactiveOptions, u as unwrap } from './types-Bx2PhORg.js';
 
 type Restorer = () => () => void;
 type Hook = () => Restorer;
@@ -634,49 +634,11 @@ declare function chainPromise<T>(given: Promise<T> | T): PromiseChain<T>;
  * attend(() => Object.keys(record), (key) => { ... })
  * ```
  */
-declare function attend<T>(source: readonly T[], callback: (index: number) => EffectCloser | undefined): ScopedCallback;
-declare function attend<K, V>(source: Map<K, V>, callback: (key: K) => EffectCloser | undefined): ScopedCallback;
-declare function attend<T>(source: Set<T>, callback: (value: T) => EffectCloser | undefined): ScopedCallback;
-declare function attend<S extends Record<PropertyKey, any>>(source: S, callback: (key: keyof S & string) => EffectCloser | undefined): ScopedCallback;
-declare function attend<Key>(enumerate: () => Iterable<Key>, callback: (key: Key) => EffectCloser | undefined): ScopedCallback;
-/**
- * Result of a reactive scan, which is a reactive array of accumulated values
- * with an attached cleanup function.
- */
-type ScanResult<Output> = readonly Output[] & {
-    [cleanup]: ScopedCallback;
-};
-/**
- * Perform a reactive scan over an array of items.
- *
- * This implementation is highly optimized for performance and fine-grained reactivity:
- * - **Incremental Updates**: Changes to an item only trigger re-computation from that
- *   point onwards in the result chain.
- * - **Move Optimization**: If items are moved within the array, their accumulated
- *   values are reused as long as their predecessor remains the same.
- * - **Duplicate Support**: Correctly handles multiple occurrences of the same object
- *   instance using an internal occurrence tracking mechanism.
- * - **Memory Efficient**: Uses `WeakMap` for caching intermediates, which are
- *   automatically cleared when source items are garbage collected.
- *
- * @example
- * ```typescript
- * const source = reactive([{ val: 1 }, { val: 2 }, { val: 3 }])
- * const sum = scan(source, (acc, item) => acc + item.val, 0)
- *
- * expect([...sum]).toEqual([1, 3, 6])
- *
- * // Modifying an item only re-computes subsequent sums
- * source[1].val = 10
- * expect([...sum]).toEqual([1, 11, 14])
- * ```
- *
- * @param source The source array of objects (will be made reactive)
- * @param callback The accumulator function called with (accumulator, currentItem)
- * @param initialValue The starting value for the accumulation
- * @returns A reactive array of accumulated values, with a [cleanup] property to stop the tracking
- */
-declare function scan<Input extends object, Output>(source: readonly Input[], callback: (acc: Output, val: Input) => Output, initialValue: Output): ScanResult<Output>;
+declare function attend<T>(source: readonly T[], callback: (index: number, access: EffectAccess) => EffectCloser | void): ScopedCallback;
+declare function attend<K, V>(source: Map<K, V>, callback: (key: K, access: EffectAccess) => EffectCloser | void): ScopedCallback;
+declare function attend<T>(source: Set<T>, callback: (value: T, access: EffectAccess) => EffectCloser | void): ScopedCallback;
+declare function attend<S extends object>(source: S, callback: (key: keyof S & string, access: EffectAccess) => EffectCloser | void): ScopedCallback;
+declare function attend<Key>(enumerate: () => Iterable<Key>, callback: (key: Key, access: EffectAccess) => EffectCloser | void): ScopedCallback;
 /**
  * Lifts a callback that returns an array into a reactive array that automatically
  * synchronizes with the source array returned by the callback.
@@ -698,9 +660,7 @@ declare function scan<Input extends object, Output>(source: readonly Input[], ca
  * @param cb Callback function that returns an array
  * @returns A reactive array synchronized with the callback's result, with a [cleanup] property to stop tracking
  */
-declare function lift<Output extends any[]>(cb: (access: EffectAccess) => Output): Output & {
-    [cleanup]: ScopedCallback;
-};
+declare function lift<Output extends any[]>(cb: (access: EffectAccess) => Output): Output;
 /**
  * Lifts a callback that returns an object into a reactive object that automatically
  * synchronizes with the source object returned by the callback.
@@ -729,9 +689,7 @@ declare function lift<Output extends any[]>(cb: (access: EffectAccess) => Output
  * @param cb Callback function that returns an object
  * @returns A reactive object synchronized with the callback's result, with a [cleanup] property to stop tracking
  */
-declare function lift<Output extends object>(cb: (access: EffectAccess) => Output): Output & {
-    [cleanup]: ScopedCallback;
-};
+declare function lift<Output extends object>(cb: (access: EffectAccess) => Output): Output;
 /**
  * Options for `morph` and its variants.
  *
@@ -751,16 +709,10 @@ type MorphOptions<I> = {
  * @see morphRecord
  */
 type Morph = {
-    <I, O>(source: readonly I[] | (() => readonly I[]), fn: (arg: I) => O, options?: MorphOptions<I>): readonly O[] & {
-        [cleanup]: ScopedCallback;
-    };
-    <K, V, O>(source: Map<K, V>, fn: (arg: V) => O, options?: MorphOptions<V>): Map<K, O> & {
-        [cleanup]: ScopedCallback;
-    };
-    <S extends Record<PropertyKey, any>, O>(source: S, fn: (arg: S[keyof S]) => O, options?: MorphOptions<S[keyof S]>): {
+    <I, O>(source: readonly I[] | (() => readonly I[]), fn: (arg: I, access?: EffectAccess) => O, options?: MorphOptions<I>): readonly O[];
+    <K, V, O>(source: Map<K, V>, fn: (arg: V, key: K, access?: EffectAccess) => O, options?: MorphOptions<V>): Map<K, O>;
+    <S extends Record<PropertyKey, any>, O>(source: S, fn: (arg: S[keyof S], key: keyof S, access?: EffectAccess) => O, options?: MorphOptions<S[keyof S]>): {
         [K in keyof S]: O;
-    } & {
-        [cleanup]: ScopedCallback;
     };
     pure: Morph;
 };
@@ -829,19 +781,38 @@ declare function deepWatch<T extends object>(target: T, callback: (value: T) =>
 declare const effectAggregator: ZoneAggregator;
 declare function getActiveEffect(): ScopedCallback;
 /**
- * ADD a cleanup function to an object using the cleanup symbol.
- * The cleanup function will be called when the object needs to be disposed.
+ * Attach cleanup dependencies to an object. When `unlink(obj)` is called,
+ * each dependency is disposed: functions are invoked with the cleanup reason,
+ * objects are recursively `unlink`ed. This forms a cleanup tree.
+ *
+ * @param obj - The owner object
+ * @param cleanupFns - Cleanup callbacks and/or child objects to unlink recursively
+ * @returns The owner object (for chaining)
+ *
+ * @example
+ * ```ts
+ * // Functions are called with CleanupReason
+ * link(parent, () => console.log('disposed'))
  *
- * Note: most of the time, you don't need to use this function directly.
- * The main use if for the cleanup function to be stored with the object, as GC calls the cleanup function when the *function* is garbage collected.
+ * // Objects are recursively unlinked
+ * link(parent, childA, childB)
  *
- * @param obj - The object to attach the cleanup function to
- * @param cleanupFn - The cleanup function to attach
- * @returns The object with the cleanup function attached
+ * // Mixed
+ * link(parent, childObj, () => timer.clear())
+ *
+ * unlink(parent) // disposes childA, childB, calls the function
+ * ```
  */
-declare function cleanedBy<T extends object>(obj: T, cleanupFn: ScopedCallback): T & {
-    [cleanup]: ScopedCallback;
-};
+declare function link<T extends object>(obj: T, ...cleanupFns: (ScopedCallback | object | undefined)[]): T;
+/**
+ * Dispose an object's cleanup dependencies. Functions are called with the
+ * reason; linked objects are recursively unlinked. The cleanup set is removed
+ * so calling `unlink` twice is safe (second call is a no-op).
+ *
+ * @param obj - The object to dispose
+ * @param reason - Optional cleanup reason propagated to callbacks
+ */
+declare function unlink(obj: object, reason?: CleanupReason): void;
 
 interface ActivationRecord {
     effect: EffectTrigger;
@@ -898,6 +869,17 @@ declare function reset(): void;
  * Decorator that makes methods atomic - batches all effects triggered within the method
  */
 declare const atomic: LegacyPropertyDecorator<any> & ModernMethodDecorator<any> & (<Args extends any[], Return>(original: (...args: Args) => Return) => (...args: Args) => Return);
+/**
+ * Wraps `fn` so it runs within `effect`'s zone context when invoked later.
+ *
+ * Useful for deferred callbacks (event listeners, `DOMContentLoaded`, etc.)
+ * that need sub-effects parented to the original effect.
+ *
+ * @param prev - The effect whose context should be restored, or `undefined` for root context
+ * @param fn - The function to wrap
+ * @returns A function with the same signature that restores the effect context before calling `fn`
+ */
+declare function captured<Args extends any[], Return>(prev: HistoryValue<EffectTrigger> | undefined, fn: (...args: Args) => Return): (...args: Args) => Return;
 /**
  * Runs `fn` atomically and **always immediately**, batching all reactive effects
  * triggered inside it so they fire only once after `fn` completes.
@@ -921,16 +903,23 @@ declare function atom<T>(fn: () => T): any;
  * @param fn - The effect function to run - provides the cleaner
  * @returns The cleanup function
  */
+/**
+ * Reactive effect function with chainable flavor modifiers.
+ */
+interface Effect {
+    (fn: (access: EffectAccess) => EffectCloser | undefined | void | Promise<any>, effectOptions?: EffectOptions): EffectCleanup;
+    /** Opaque flavor: bypasses deep-touch optimizations */
+    readonly opaque: Effect;
+    /** Named flavor: assigns a debug name */
+    named(name: string): Effect;
+}
 /**
  * Creates a reactive effect that automatically re-runs when dependencies change
  * @param fn - The effect function that provides dependencies and may return a cleanup function or Promise
  * @param options - Options for effect execution
  * @returns A cleanup function to stop the effect
  */
-declare const effect: ((fn: (access: EffectAccess) => EffectCloser | undefined | void | Promise<any>, effectOptions?: EffectOptions) => EffectCleanup) & {
-    readonly opaque: any;
-    named(name: string): any;
-};
+declare const effect: Effect;
 /**
  * Executes a function without tracking dependencies but maintains parent cleanup relationship
  * Effects created inside will still be cleaned up when the parent effect is destroyed
@@ -1014,7 +1003,12 @@ declare const memoize: ReturnType<typeof makeMemoizeDecorator> & {
     readonly lenient: ReturnType<typeof makeMemoizeDecorator>;
 };
 
-declare const immutables: Set<(tested: any) => boolean>;
+/**
+ * Add unreactive properties to a prototype.
+ * If no set is provided, marks the entire object/prototype as non-reactive (sets [unreactiveProperties] = true).
+ * If a set is provided, merges with existing unreactive properties (never overrides true).
+ */
+declare function addUnreactiveProps<T extends object>(proto: T, set?: Iterable<PropertyKey>): T;
 declare function isNonReactive(obj: any): boolean;
 
 type SubProxy = {
@@ -1081,13 +1075,7 @@ target: Target) => EffectCloser | undefined;
  * The result type of the organized function, combining the target object with cleanup capability.
  * @template Target - The type of the target object
  */
-type OrganizedResult<Target extends object> = Target & {
-    /**
-     * Cleanup function to dispose of all reactive bindings created by organized().
-     * This is automatically called when the effect that created the organized binding is disposed.
-     */
-    [cleanup]: ScopedCallback;
-};
+type OrganizedResult<Target extends object> = Target;
 /**
  * Organizes a source object's properties into a target object using a callback function.
  * This creates a reactive mapping between source properties and a target object,
@@ -1153,129 +1141,6 @@ declare function organize<T>(target: object, property: PropertyKey, access: {
     set?(value: T): boolean;
 }): () => boolean;
 
-type KeyFunction<T, K extends PropertyKey> = (item: T) => K;
-/**
- * Events emitted by the Register for CRUD operations
- */
-interface RegisterEvents<T, K extends PropertyKey> {
-    /**
-     * Emitted when a new item is added to the register
-     */
-    add: (item: T, key: K, index: number) => void;
-    /**
-     * Emitted when an item is removed from the register
-     */
-    delete: (item: T, key: K, index: number) => void;
-    /**
-     * Emitted when an item's value is updated (same key, new value)
-     */
-    update: (oldItem: T, newItem: T, key: K, index: number) => void;
-    /**
-     * Emitted when an item's key changes (rekey operation)
-     */
-    rekey: (item: T, oldKey: K, newKey: K, index: number) => void;
-    /**
-     * Index signature for EventsBase compatibility
-     */
-    [key: string]: (...args: any[]) => void;
-}
-interface RegisterInstance<T> extends ArrayReadForward<T> {
-    [index: number]: T;
-}
-declare const RegisterClass_base: new () => ArrayReadForward<any> & {
-    [x: number]: any;
-    toArray(): any[];
-};
-declare class RegisterClass<T, K extends PropertyKey = PropertyKey> extends RegisterClass_base implements RegisterInstance<T> {
-    #private;
-    protected get [forwardArray](): readonly T[];
-    /**
-     * Register event listeners for CRUD operations
-     */
-    on(events: Partial<RegisterEvents<T, K>>): void;
-    on<EventType extends keyof RegisterEvents<T, K>>(event: EventType, cb: RegisterEvents<T, K>[EventType]): () => void;
-    /**
-     * Remove event listeners
-     */
-    off(events: Partial<RegisterEvents<T, K>>): void;
-    off<EventType extends keyof RegisterEvents<T, K>>(event: EventType, cb?: RegisterEvents<T, K>[EventType]): void;
-    /**
-     * Register a global hook that receives all events
-     */
-    hook(cb: <EventType extends keyof RegisterEvents<T, K>>(event: EventType, ...args: Parameters<RegisterEvents<T, K>[EventType]>) => void): () => void;
-    constructor(keyFn: KeyFunction<T, K>, initial?: Iterable<T>);
-    private ensureKey;
-    private assertValidKey;
-    private setKeyValue;
-    private cleanupValue;
-    private disposeKeyEffects;
-    private incrementUsage;
-    private decrementUsage;
-    private normalizeIndex;
-    private assignAt;
-    private insertKeyValue;
-    private rebuildFrom;
-    get length(): number;
-    [getAt](index: number): T | undefined;
-    [setAt](index: number, value: T): void;
-    push(...items: T[]): number;
-    pop(): T | undefined;
-    shift(): T | undefined;
-    unshift(...items: T[]): number;
-    splice(start: number, deleteCount?: number, ...items: T[]): T[];
-    clear(): void;
-    get(key: K): T | undefined;
-    set(key: K, value: T): void;
-    remove(key: K): void;
-    removeAt(index: number): T | undefined;
-    /**
-     * Keep only the items for which the predicate returns true.
-     * Items for which the predicate returns false are removed.
-     *
-     * The predicate is evaluated once per distinct key; duplicate keys
-     * will follow the same keep/remove decision.
-     */
-    keep(predicate: (value: T) => boolean): void;
-    hasKey(key: K): boolean;
-    indexOfKey(key: K): number;
-    mapKeys(): IterableIterator<K>;
-    update(...values: T[]): void;
-    upsert(insert: (value: T) => void, ...values: T[]): void;
-    entries(): IterableIterator<[number, T]>;
-    [Symbol.iterator](): IterableIterator<T>;
-    toString(): string;
-    at(index: number): T | undefined;
-    reverse(): this;
-    sort(compareFn?: ((a: T, b: T) => number) | undefined): this;
-    fill(value: T, start?: number, end?: number): this;
-    copyWithin(target: number, start: number, end?: number): this;
-}
-type Register<T, K extends PropertyKey = PropertyKey> = RegisterClass<T, K> & T[];
-declare const Register: new <T, K extends PropertyKey = PropertyKey>(keyFn: KeyFunction<T, K>, initial?: Iterable<T>) => Register<T, K>;
-/**
- * Creates a reactive Register - an ordered, array-like collection with stable key-based identity.
- *
- * Register combines array semantics (indexable access, ordering, iteration) with Map-like
- * key-based lookups. Items with the same key share the same value instance, making it ideal
- * for UI lists keyed by IDs or when you need to preserve identity across reorders.
- *
- * @param keyFn - Function that extracts the key from each item
- * @param initial - Optional initial items to populate the register
- * @returns A reactive Register instance
- *
- * @example
- * ```typescript
- * const users = register(
- *   (user: User) => user.id,
- *   [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
- * )
- *
- * users.push({ id: 3, name: 'Charlie' })
- * const bob = users.get(2) // Get by key
- * ```
- */
-declare function register<T, K extends PropertyKey = PropertyKey>(keyFn: KeyFunction<T, K>, initial?: Iterable<T>): Register<T, K>;
-
 /**
  * Options for the watch function
  */
@@ -1328,7 +1193,8 @@ interface Resource<T> {
     loading: boolean;
     error: any;
     latest: T | undefined;
-    reload: () => void;
+    reload(): void;
+    promise: Promise<void>;
 }
 /**
  * Creates a reactive resource that automatically tracks async state.
@@ -1336,10 +1202,16 @@ interface Resource<T> {
  * @param options - Resource options (initialValue)
  * @returns Reactive Resource object with value, loading, error, latest properties
  */
-declare function resource<T>(fetcher: (dep: EffectAccess) => Promise<T> | T, options?: {
+declare function resource<T>(fetcher: (access: EffectAccess) => Promise<T> | T, options?: {
     initialValue?: T;
 }): Resource<T>;
 
+/**
+ * Executes a function and throws if any reactive dependencies are tracked during execution.
+ * Used to assert that code runs in an untracked context.
+ */
+declare function assertUntracked<T>(fn: () => T): T;
+
 /**
  * Object containing internal reactive system state for debugging and profiling
  */
@@ -1442,6 +1314,9 @@ declare function tag<T extends object>(name: string, obj: T): T;
  * @returns The function with the new name
  */
 declare function named<T extends Function>(name: string, fn: T): T;
+declare const isDev: boolean;
+declare const isProd: boolean;
+declare const isTest: boolean;
 
-export { ArrayReadForward, DecoratorError, Destroyable, DestructionError, EffectAccess, EffectCleanup, EffectCloser, EffectOptions, EffectTrigger, Eventful, Evolution, Indexable, IterableWeakMap, IterableWeakSet, ReactiveBase, Register, ScopedCallback, ZoneAggregator, addBatchCleanup, allocated, allocatedValues, arrayDiff, arrayEquals, asyncHook, asyncHooks, atom, atomic, attend, biDi, cache, cached, callOnGC, caught, chainPromise, cleanedBy, cleanup, createFlavor, debounce, decorator, deepCompare, deepWatch, defer, deprecated, descriptor, destructor, effect, effectAggregator, flavorOptions, flavored, forwardArray, getActivationLog, getActiveEffect, getAt, getState, hooks$1 as hooks, immutables, isCached, isConstructor, isNonReactive, isObject, legacyDecorator, lift, memoize, mixin, modernDecorator, morph, named, onEffectThrow, organize, organized, profileInfo, morph as project, reactive, register, reset, resource, root, scan, setAt, tag, throttle, touched, touched1, unreactive, untracked, watch, when, zip };
-export type { ArrayDiffResult, ContextManager, Decorator, DecoratorDescription, DecoratorFactory, EventsBase, GenericClassDecorator, Hook, LegacyClassDecorator, LegacyPropertyDecorator, Memoizable, MemoizableArgument, MixinClass, MixinFunction, ModernAccessorDecorator, ModernClassDecorator, ModernGetterDecorator, ModernMethodDecorator, ModernSetterDecorator, PromiseChain, Resource, Restorer, ScanResult };
+export { ArrayReadForward, CleanupReason, DecoratorError, Destroyable, DestructionError, EffectAccess, EffectCleanup, EffectCloser, EffectOptions, EffectTrigger, Eventful, Evolution, HistoryValue, Indexable, IterableWeakMap, IterableWeakSet, ReactiveBase, ScopedCallback, ZoneAggregator, addBatchCleanup, addUnreactiveProps, allocated, allocatedValues, arrayDiff, arrayEquals, assertUntracked, asyncHook, asyncHooks, atom, atomic, attend, biDi, cache, cached, callOnGC, captured, caught, chainPromise, createFlavor, debounce, decorator, deepCompare, deepWatch, defer, deprecated, descriptor, destructor, effect, effectAggregator, flavorOptions, flavored, forwardArray, getActivationLog, getActiveEffect, getAt, getState, hooks$1 as hooks, isCached, isConstructor, isDev, isNonReactive, isObject, isProd, isTest, legacyDecorator, lift, link, memoize, mixin, modernDecorator, morph, named, onEffectThrow, organize, organized, profileInfo, morph as project, reactive, reset, resource, root, setAt, tag, throttle, touched, touched1, unlink, unreactive, untracked, watch, when, zip };
+export type { ArrayDiffResult, ContextManager, Decorator, DecoratorDescription, DecoratorFactory, EventsBase, GenericClassDecorator, Hook, LegacyClassDecorator, LegacyPropertyDecorator, Memoizable, MemoizableArgument, MixinClass, MixinFunction, ModernAccessorDecorator, ModernClassDecorator, ModernGetterDecorator, ModernMethodDecorator, ModernSetterDecorator, PromiseChain, Resource, Restorer };