mutts 1.0.5 → 1.0.6

package/README.md

@@ -171,6 +171,7 @@ A comprehensive reactivity system. See the **[Introduction](./docs/reactive/core
 - **Back-Reference System**: Efficient change propagation through object hierarchies
 - **Type Safety**: Full TypeScript support with proper type inference
 - **Performance Optimized**: Lazy back-reference creation and efficient dependency tracking
+- **Debugging & Development**: Built-in tools like cycle detection and memoization discrepancy check
 
 **Use Cases:**
 - State management systems

package/dist/chunks/{_tslib-Mzh1rNsX.esm.js → _tslib-MCKDzsSq.esm.js}

@@ -71,5 +71,5 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
-export { __classPrivateFieldGet as _, __setFunctionName as a, __esDecorate as b, __runInitializers as c, __classPrivateFieldSet as d };
-//# sourceMappingURL=_tslib-Mzh1rNsX.esm.js.map
+export { __setFunctionName as _, __esDecorate as a, __runInitializers as b, __classPrivateFieldSet as c, __classPrivateFieldGet as d };
+//# sourceMappingURL=_tslib-MCKDzsSq.esm.js.map

package/dist/chunks/_tslib-MCKDzsSq.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_tslib-MCKDzsSq.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/chunks/decorator-BGILvPtN.esm.js

@@ -0,0 +1,627 @@
+// biome-ignore-all lint/suspicious/noConfusingVoidType: Type 'void' is not assignable to type 'ScopedCallback | undefined'.
+// Argument of type '() => void' is not assignable to parameter of type '(dep: DependencyFunction) => ScopedCallback | undefined'.
+// Track native reactivity
+const nativeReactive = Symbol('native-reactive');
+/**
+ * Symbol to mark individual objects as non-reactive
+ */
+const nonReactiveMark = Symbol('non-reactive');
+/**
+ * Symbol to mark class properties as non-reactive
+ */
+const unreactiveProperties = Symbol('unreactive-properties');
+/**
+ * Symbol for prototype forwarding in reactive objects
+ */
+const prototypeForwarding = Symbol('prototype-forwarding');
+/**
+ * Symbol representing all properties in reactive tracking
+ */
+const allProps = Symbol('all-props');
+/**
+ * Symbol for accessing projection information on reactive objects
+ */
+const projectionInfo = Symbol('projection-info');
+/**
+ * Symbol to check if an effect is stopped
+ */
+const stopped = Symbol('stopped');
+/**
+ * Symbol to access effect cleanup function
+ */
+const cleanup = Symbol('cleanup');
+// Symbol to mark functions with their root function
+const rootFunction = Symbol('root-function');
+/**
+ * Structured error codes for machine-readable diagnosis
+ */
+var ReactiveErrorCode;
+(function (ReactiveErrorCode) {
+    ReactiveErrorCode["CycleDetected"] = "CYCLE_DETECTED";
+    ReactiveErrorCode["MaxDepthExceeded"] = "MAX_DEPTH_EXCEEDED";
+    ReactiveErrorCode["MaxReactionExceeded"] = "MAX_REACTION_EXCEEDED";
+    ReactiveErrorCode["WriteInComputed"] = "WRITE_IN_COMPUTED";
+    ReactiveErrorCode["TrackingError"] = "TRACKING_ERROR";
+})(ReactiveErrorCode || (ReactiveErrorCode = {}));
+/**
+ * Error class for reactive system errors
+ */
+class ReactiveError extends Error {
+    constructor(message, debugInfo) {
+        super(message);
+        this.debugInfo = debugInfo;
+        this.name = 'ReactiveError';
+    }
+}
+// biome-ignore-start lint/correctness/noUnusedFunctionParameters: Interface declaration with empty defaults
+/**
+ * Global options for the reactive system
+ */
+const options = {
+    /**
+     * Debug purpose: called when an effect is entered
+     * @param effect - The effect that is entered
+     */
+    enter: (_effect) => { },
+    /**
+     * Debug purpose: called when an effect is left
+     * @param effect - The effect that is left
+     */
+    leave: (_effect) => { },
+    /**
+     * Debug purpose: called when an effect is chained
+     * @param target - The effect that is being triggered
+     * @param caller - The effect that is calling the target
+     */
+    chain: (_targets, _caller) => { },
+    /**
+     * Debug purpose: called when an effect chain is started
+     * @param target - The effect that is being triggered
+     */
+    beginChain: (_targets) => { },
+    /**
+     * Debug purpose: called when an effect chain is ended
+     */
+    endChain: () => { },
+    garbageCollected: (_fn) => { },
+    /**
+     * Debug purpose: called when an object is touched
+     * @param obj - The object that is touched
+     * @param evolution - The type of change
+     * @param props - The properties that changed
+     * @param deps - The dependencies that changed
+     */
+    touched: (_obj, _evolution, _props, _deps) => { },
+    /**
+     * Debug purpose: called when an effect is skipped because it's already running
+     * @param effect - The effect that is already running
+     * @param runningChain - The array of effects from the detected one to the currently running one
+     */
+    skipRunningEffect: (_effect, _runningChain) => { },
+    /**
+     * Debug purpose: maximum effect chain (like call stack max depth)
+     * Used to prevent infinite loops
+     * @default 100
+     */
+    maxEffectChain: 100,
+    /**
+     * Maximum number of times an effect can be triggered by the same cause in a single batch
+     * Used to detect aggressive re-computation or infinite loops
+     * @default 10
+     */
+    maxTriggerPerBatch: 10,
+    /**
+     * Debug purpose: maximum effect reaction (like call stack max depth)
+     * Used to prevent infinite loops
+     * @default 'throw'
+     */
+    maxEffectReaction: 'throw',
+    /**
+     * Callback called when a memoization discrepancy is detected (debug only)
+     * When defined, memoized functions will run a second time (untracked) to verify consistency.
+     * If the untracked run returns a different value than the cached one, this callback is triggered.
+     *
+     * This is the primary tool for detecting missing reactive dependencies in computed values.
+     *
+     * @param cached - The value currently in the memoization cache
+     * @param fresh - The value obtained by re-running the function untracked
+     * @param fn - The memoized function itself
+     * @param args - Arguments passed to the function
+     *
+     * @example
+     * ```typescript
+     * reactiveOptions.onMemoizationDiscrepancy = (cached, fresh, fn, args) => {
+     *   throw new Error(`Memoization discrepancy in ${fn.name}!`);
+     * };
+     * ```
+     */
+    onMemoizationDiscrepancy: undefined,
+    /**
+     * How to handle cycles detected in effect batches
+     * - 'throw': Throw an error with cycle information (default, recommended for development)
+     * - 'warn': Log a warning and break the cycle by executing one effect
+     * - 'break': Silently break the cycle by executing one effect (recommended for production)
+     * - 'strict': Prevent cycle creation by checking graph before execution (throws error)
+     * @default 'throw'
+     */
+    cycleHandling: 'throw',
+    /**
+     * Internal flag used by memoization discrepancy detector to avoid counting calls in tests
+     * @warning Do not modify this flag manually, this flag is given by the engine
+     */
+    isVerificationRun: false,
+    /**
+     * Maximum depth for deep watching traversal
+     * Used to prevent infinite recursion in circular references
+     * @default 100
+     */
+    maxDeepWatchDepth: 100,
+    /**
+     * Only react on instance members modification (not inherited properties)
+     * For instance, do not track class methods
+     * @default true
+     */
+    instanceMembers: true,
+    /**
+     * Ignore accessors (getters and setters) and only track direct properties
+     * @default true
+     */
+    ignoreAccessors: true,
+    /**
+     * Enable recursive touching when objects with the same prototype are replaced
+     * When enabled, replacing an object with another of the same prototype triggers
+     * recursive diffing instead of notifying parent effects
+     * @default true
+     */
+    recursiveTouching: true,
+    /**
+     * Default async execution mode for effects that return Promises
+     * - 'cancel': Cancel previous async execution when dependencies change (default, enables async zone)
+     * - 'queue': Queue next execution to run after current completes (enables async zone)
+     * - 'ignore': Ignore new executions while async work is running (enables async zone)
+     * - false: Disable async zone and async mode handling (effects run concurrently)
+     *
+     * **When truthy:** Enables async zone (Promise.prototype wrapping) for automatic context
+     * preservation in Promise callbacks. Warning: This modifies Promise.prototype globally.
+     * Only enable if no other library modifies Promise.prototype.
+     *
+     * **When false:** Async zone is disabled. Use `tracked()` manually in Promise callbacks.
+     *
+     * Can be overridden per-effect via EffectOptions
+     * @default 'cancel'
+     */
+    asyncMode: 'cancel',
+    // biome-ignore lint/suspicious/noConsole: This is the whole point here
+    warn: (...args) => console.warn(...args),
+    /**
+     * Configuration for the introspection system
+     */
+    introspection: {
+        /**
+         * Whether to keep a history of mutations for debugging
+         * @default false
+         */
+        enableHistory: false,
+        /**
+         * Number of mutations to keep in history
+         * @default 50
+         */
+        historySize: 50,
+    },
+    /**
+     * Configuration for zone hooks - control which async APIs are hooked
+     * Each option controls whether the corresponding async API is wrapped to preserve effect context
+     * Only applies when asyncMode is enabled (truthy)
+     */
+    zones: {
+        /**
+         * Hook setTimeout to preserve effect context
+         * @default true
+         */
+        setTimeout: true,
+        /**
+         * Hook setInterval to preserve effect context
+         * @default true
+         */
+        setInterval: true,
+        /**
+         * Hook requestAnimationFrame (runs in untracked context when hooked)
+         * @default true
+         */
+        requestAnimationFrame: true,
+        /**
+         * Hook queueMicrotask to preserve effect context
+         * @default true
+         */
+        queueMicrotask: true,
+    },
+};
+
+/**
+ * Combines multiple arrays into an array of tuples, stopping at the shortest array length
+ * @param args - Arrays to zip together
+ * @returns Array of tuples containing elements from each input array
+ */
+function zip(...args) {
+    if (!args.length)
+        return [];
+    const minLength = Math.min(...args.map((arr) => arr.length));
+    const result = [];
+    for (let i = 0; i < minLength; i++) {
+        const tuple = args.map((arr) => arr[i]);
+        result.push(tuple);
+    }
+    return result;
+}
+/**
+ * Checks if two arrays are strictly equal (shallow comparison)
+ * @param a - First value
+ * @param b - Second value
+ * @returns True if arrays are equal or values are strictly equal
+ */
+function arrayEquals(a, b) {
+    if (a === b)
+        return true;
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+const nativeConstructors = new Set([
+    Object,
+    Array,
+    Date,
+    Function,
+    Set,
+    Map,
+    WeakMap,
+    WeakSet,
+    Promise,
+    Error,
+    TypeError,
+    ReferenceError,
+    SyntaxError,
+    RangeError,
+    URIError,
+    EvalError,
+    Reflect,
+    Proxy,
+    RegExp,
+    String,
+    Number,
+    Boolean,
+]);
+/**
+ * Checks if a function is a constructor (class or constructor function)
+ * @param fn - The function to check
+ * @returns True if the function is a constructor
+ */
+function isConstructor(fn) {
+    return (fn &&
+        typeof fn === 'function' &&
+        (nativeConstructors.has(fn) || fn.toString?.().startsWith('class ')));
+}
+/**
+ * Renames a function with a new name
+ * @param fct - The function to rename
+ * @param name - The new name for the function
+ * @returns The function with the new name
+ */
+function renamed(fct, name) {
+    return Object.defineProperties(fct, {
+        name: {
+            value: name,
+        },
+    });
+}
+function ReflectGet(obj, prop, receiver) {
+    // Check if Node is available and obj is an instance of Node
+    if (typeof Node !== 'undefined' && obj instanceof Node)
+        return obj[prop];
+    return Reflect.get(obj, prop, receiver);
+}
+function ReflectSet(obj, prop, value, receiver) {
+    // Check if Node is available and obj is an instance of Node
+    if (typeof Node !== 'undefined' && obj instanceof Node) {
+        obj[prop] = value;
+        return true;
+    }
+    if (!(obj instanceof Object) && !Reflect.has(obj, prop)) {
+        Object.defineProperty(obj, prop, {
+            value,
+            configurable: true,
+            writable: true,
+            enumerable: true,
+        });
+        return true;
+    }
+    return Reflect.set(obj, prop, value, receiver);
+}
+function isOwnAccessor(obj, prop) {
+    const opd = Object.getOwnPropertyDescriptor(obj, prop);
+    return !!(opd?.get || opd?.set);
+}
+/**
+ * Deeply compares two values.
+ * For objects, compares prototypes with === and then own properties recursively.
+ * Uses a cache to handle circular references.
+ * @param a - First value
+ * @param b - Second value
+ * @param cache - Map for circular reference protection (internal use)
+ * @returns True if values are deeply equal
+ */
+function deepCompare(a, b, cache = new Map()) {
+    // Unwrap mutts proxies if present
+    while (a && typeof a === 'object' && prototypeForwarding in a) {
+        a = a[prototypeForwarding];
+    }
+    while (b && typeof b === 'object' && prototypeForwarding in b) {
+        b = b[prototypeForwarding];
+    }
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+        return a === b;
+    }
+    // Prototype check
+    const protoA = Object.getPrototypeOf(a);
+    const protoB = Object.getPrototypeOf(b);
+    if (protoA !== protoB) {
+        console.warn(`[deepCompare] prototype mismatch:`, { nameA: a?.constructor?.name, nameB: b?.constructor?.name });
+        return false;
+    }
+    // Circular reference protection
+    let compared = cache.get(a);
+    if (compared?.has(b))
+        return true;
+    if (!compared) {
+        compared = new Set();
+        cache.set(a, compared);
+    }
+    compared.add(b);
+    // Handle specific object types
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b)) {
+            console.warn(`[deepCompare] B is not an array`);
+            return false;
+        }
+        if (a.length !== b.length) {
+            console.warn(`[deepCompare] array length mismatch:`, { lenA: a.length, lenB: b.length });
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (!deepCompare(a[i], b[i], cache)) {
+                console.warn(`[deepCompare] array element mismatch at index ${i}`);
+                return false;
+            }
+        }
+        return true;
+    }
+    if (a instanceof Date) {
+        const match = b instanceof Date && a.getTime() === b.getTime();
+        if (!match)
+            console.warn(`[deepCompare] Date mismatch`);
+        return match;
+    }
+    if (a instanceof RegExp) {
+        const match = b instanceof RegExp && a.toString() === b.toString();
+        if (!match)
+            console.warn(`[deepCompare] RegExp mismatch`);
+        return match;
+    }
+    if (a instanceof Set) {
+        if (!(b instanceof Set) || a.size !== b.size) {
+            console.warn(`[deepCompare] Set size mismatch`);
+            return false;
+        }
+        for (const val of a) {
+            let found = false;
+            for (const bVal of b) {
+                if (deepCompare(val, bVal, cache)) {
+                    found = true;
+                    break;
+                }
+            }
+            if (!found) {
+                console.warn(`[deepCompare] missing Set element`);
+                return false;
+            }
+        }
+        return true;
+    }
+    if (a instanceof Map) {
+        if (!(b instanceof Map) || a.size !== b.size) {
+            console.warn(`[deepCompare] Map size mismatch`);
+            return false;
+        }
+        for (const [key, val] of a) {
+            if (!b.has(key)) {
+                let foundMatch = false;
+                for (const [bKey, bVal] of b) {
+                    if (deepCompare(key, bKey, cache) && deepCompare(val, bVal, cache)) {
+                        foundMatch = true;
+                        break;
+                    }
+                }
+                if (!foundMatch) {
+                    console.warn(`[deepCompare] missing Map key`);
+                    return false;
+                }
+            }
+            else {
+                if (!deepCompare(val, b.get(key), cache)) {
+                    console.warn(`[deepCompare] Map value mismatch for key`);
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    // Compare own properties
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) {
+        console.warn(`[deepCompare] keys length mismatch:`, { lenA: keysA.length, lenB: keysB.length, keysA, keysB, a, b });
+        return false;
+    }
+    for (const key of keysA) {
+        if (!Object.prototype.hasOwnProperty.call(b, key)) {
+            console.warn(`[deepCompare] missing key ${String(key)} in B`);
+            return false;
+        }
+        if (!deepCompare(a[key], b[key], cache)) {
+            console.warn(`[deepCompare] value mismatch for key ${String(key)}:`, { valA: a[key], valB: b[key] });
+            return false;
+        }
+    }
+    return true;
+}
+
+// biome-ignore-all lint/suspicious/noConfusingVoidType: We *love* voids
+// Standardized decorator system that works with both Legacy and Modern decorators
+/**
+ * Error thrown when decorator operations fail
+ */
+class DecoratorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DecoratorException';
+    }
+}
+/**
+ * Creates a decorator that works with Legacy decorator proposals
+ * @param description - The decorator description object
+ * @returns A decorator function compatible with Legacy decorators
+ */
+function legacyDecorator(description) {
+    return function (target, propertyKey, descriptor, ...args) {
+        if (propertyKey === undefined) {
+            if (isConstructor(target)) {
+                if (!('class' in description))
+                    throw new Error('Decorator cannot be applied to a class');
+                return description.class(target);
+            }
+        }
+        else if (typeof target === 'object' && ['string', 'symbol'].includes(typeof propertyKey)) {
+            if (!descriptor)
+                throw new Error('Decorator cannot be applied to a field');
+            else if (typeof descriptor === 'object' && 'configurable' in descriptor) {
+                if ('get' in descriptor || 'set' in descriptor) {
+                    if (!('getter' in description || 'setter' in description))
+                        throw new Error('Decorator cannot be applied to a getter or setter');
+                    if ('getter' in description) {
+                        const newGetter = description.getter(descriptor.get, target, propertyKey);
+                        if (newGetter)
+                            descriptor.get = newGetter;
+                    }
+                    if ('setter' in description) {
+                        const newSetter = description.setter(descriptor.set, target, propertyKey);
+                        if (newSetter)
+                            descriptor.set = newSetter;
+                    }
+                    return descriptor;
+                }
+                else if (typeof descriptor.value === 'function') {
+                    if (!('method' in description))
+                        throw new Error('Decorator cannot be applied to a method');
+                    const newMethod = description.method(descriptor.value, target, propertyKey);
+                    if (newMethod)
+                        descriptor.value = newMethod;
+                    return descriptor;
+                }
+            }
+        }
+        if (!('default' in description))
+            throw new Error('Decorator do not have a default implementation');
+        return description.default.call(this, target, propertyKey, descriptor, ...args);
+    };
+}
+/**
+ * Creates a decorator that works with Modern decorator proposals
+ * @param description - The decorator description object
+ * @returns A decorator function compatible with Modern decorators
+ */
+function modernDecorator(description) {
+    /*return function (target: any, context?: DecoratorContext, ...args: any[]) {*/
+    return function (target, context, ...args) {
+        if (!context?.kind || typeof context.kind !== 'string') {
+            if (!('default' in description))
+                throw new Error('Decorator do not have a default implementation');
+            return description.default.call(this, target, context, ...args);
+        }
+        switch (context.kind) {
+            case 'class':
+                if (!('class' in description))
+                    throw new Error('Decorator cannot be applied to a class');
+                return description.class(target);
+            case 'field':
+                throw new Error('Decorator cannot be applied to a field');
+            case 'getter':
+                if (!('getter' in description))
+                    throw new Error('Decorator cannot be applied to a getter');
+                return description.getter(target, target, context.name);
+            case 'setter':
+                if (!('setter' in description))
+                    throw new Error('Decorator cannot be applied to a setter');
+                return description.setter(target, target, context.name);
+            case 'method':
+                if (!('method' in description))
+                    throw new Error('Decorator cannot be applied to a method');
+                return description.method(target, target, context.name);
+            case 'accessor': {
+                if (!('getter' in description || 'setter' in description))
+                    throw new Error('Decorator cannot be applied to a getter or setter');
+                const rv = {};
+                if ('getter' in description) {
+                    const newGetter = description.getter(target.get, target, context.name);
+                    if (newGetter)
+                        rv.get = newGetter;
+                }
+                if ('setter' in description) {
+                    const newSetter = description.setter(target.set, target, context.name);
+                    if (newSetter)
+                        rv.set = newSetter;
+                }
+                return rv;
+            }
+            //return description.accessor?.(target, context.name, target)
+        }
+    };
+}
+/**
+ * Detects if the decorator is being called in modern (Modern) or legacy (Legacy) mode
+ * based on the arguments passed to the decorator function
+ */
+function detectDecoratorMode(_target, contextOrKey, _descriptor) {
+    // Modern decorators have a context object as the second parameter
+    // Legacy decorators have a string/symbol key as the second parameter
+    if (typeof contextOrKey === 'object' &&
+        contextOrKey !== null &&
+        typeof contextOrKey.kind === 'string') {
+        return 'modern';
+    }
+    return 'legacy';
+}
+/**
+ * Main decorator factory that automatically detects and works with both Legacy and Modern decorator proposals
+ * @param description - The decorator description object
+ * @returns A decorator that works in both Legacy and Modern environments
+ */
+const decorator = (description) => {
+    const modern = modernDecorator(description);
+    const legacy = legacyDecorator(description);
+    return ((target, contextOrKey, ...args) => {
+        const mode = detectDecoratorMode(target, contextOrKey, args[0]);
+        return mode === 'modern'
+            ? modern(target, contextOrKey, ...args)
+            : legacy(target, contextOrKey, ...args);
+    });
+};
+
+export { DecoratorError as D, ReactiveError as R, ReflectGet as a, ReflectSet as b, arrayEquals as c, decorator as d, deepCompare as e, isOwnAccessor as f, rootFunction as g, allProps as h, isConstructor as i, ReactiveErrorCode as j, cleanup as k, legacyDecorator as l, modernDecorator as m, nonReactiveMark as n, options as o, nativeReactive as p, prototypeForwarding as q, renamed as r, stopped as s, projectionInfo as t, unreactiveProperties as u, zip as z };
+//# sourceMappingURL=decorator-BGILvPtN.esm.js.map