mutts 1.0.2 → 1.0.4

package/dist/reactive.esm.js

@@ -1,5 +1,5 @@
-export { R as Reactive, h as ReactiveBase, j as ReactiveError, a as activeEffect, b as addBatchCleanup, c as atomic, l as cleanedBy, n as computed, e as effect, g as getState, i as immutables, q as invalidateComputed, d as isNonReactive, f as isReactive, p as profileInfo, r as reactive, o as reactiveOptions, t as trackEffect, s as unreactive, u as untracked, k as unwrap, w as watch } from './chunks/index-DBScoeCX.esm.js';
-import './chunks/decorator-GnHw1Az7.esm.js';
-import './chunks/_tslib-CMEnd0VE.esm.js';
+export { M as ReactiveBase, V as ReactiveError, R as ReadOnlyError, S as Register, j as addBatchCleanup, k as atomic, l as batch, n as biDi, c as buildReactivityGraph, y as cleanedBy, z as cleanup, h as deepWatch, o as defer, A as derived, q as effect, e as enableDevTools, u as getActiveEffect, g as getState, G as immutables, i as isDevtoolsEnabled, H as isNonReactive, L as isReactive, W as isZoneEnabled, D as mapped, F as memoize, P as organize, Q as organized, p as profileInfo, K as project, N as reactive, U as reactiveOptions, E as reduced, T as register, r as registerEffectForDebug, J as registerNativeReactivity, d as registerObjectForDebug, v as root, s as setEffectName, f as setObjectName, X as setZoneEnabled, t as touched, b as touched1, w as trackEffect, B as unreactive, x as untracked, O as unwrap, C as watch } from './chunks/index-79Kk8D6e.esm.js';
+import './chunks/decorator-DqiszP7i.esm.js';
 import './indexable.esm.js';
+import './chunks/_tslib-Mzh1rNsX.esm.js';
 //# sourceMappingURL=reactive.esm.js.map

package/dist/reactive.js

@@ -1,32 +1,54 @@
 'use strict';
 
-var reactive = require('./chunks/index-DOTmXL89.js');
-require('./chunks/decorator-D4DU97Zg.js');
-require('./chunks/_tslib-C-cuVLvZ.js');
+var reactive = require('./chunks/index-GRBSx0mB.js');
+require('./chunks/decorator-DLvrD0UF.js');
 require('./indexable.js');
+require('./chunks/_tslib-BgjropY9.js');
 
 
 
-exports.Reactive = reactive.Reactive;
 exports.ReactiveBase = reactive.ReactiveBase;
 exports.ReactiveError = reactive.ReactiveError;
-Object.defineProperty(exports, "activeEffect", {
-	enumerable: true,
-	get: function () { return reactive.activeEffect; }
-});
+exports.ReadOnlyError = reactive.ReadOnlyError;
+exports.Register = reactive.Register;
 exports.addBatchCleanup = reactive.addBatchCleanup;
 exports.atomic = reactive.atomic;
+exports.batch = reactive.batch;
+exports.biDi = reactive.biDi;
+exports.buildReactivityGraph = reactive.buildReactivityGraph;
 exports.cleanedBy = reactive.cleanedBy;
-exports.computed = reactive.computed;
+exports.cleanup = reactive.cleanup;
+exports.deepWatch = reactive.deepWatch;
+exports.defer = reactive.defer;
+exports.derived = reactive.derived;
 exports.effect = reactive.effect;
+exports.enableDevTools = reactive.enableDevTools;
+exports.getActiveEffect = reactive.getActiveEffect;
 exports.getState = reactive.getState;
 exports.immutables = reactive.immutables;
-exports.invalidateComputed = reactive.invalidateComputed;
+exports.isDevtoolsEnabled = reactive.isDevtoolsEnabled;
 exports.isNonReactive = reactive.isNonReactive;
 exports.isReactive = reactive.isReactive;
+exports.isZoneEnabled = reactive.isZoneEnabled;
+exports.mapped = reactive.mapped;
+exports.memoize = reactive.memoize;
+exports.organize = reactive.organize;
+exports.organized = reactive.organized;
 exports.profileInfo = reactive.profileInfo;
+exports.project = reactive.project;
 exports.reactive = reactive.reactive;
 exports.reactiveOptions = reactive.options;
+exports.reduced = reactive.reduced;
+exports.register = reactive.register;
+exports.registerEffectForDebug = reactive.registerEffectForDebug;
+exports.registerNativeReactivity = reactive.registerNativeReactivity;
+exports.registerObjectForDebug = reactive.registerObjectForDebug;
+exports.root = reactive.root;
+exports.setEffectName = reactive.setEffectName;
+exports.setObjectName = reactive.setObjectName;
+exports.setZoneEnabled = reactive.setZoneEnabled;
+exports.touched = reactive.touched;
+exports.touched1 = reactive.touched1;
 exports.trackEffect = reactive.trackEffect;
 exports.unreactive = reactive.unreactive;
 exports.untracked = reactive.untracked;

package/dist/reactive.js.map

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

package/dist/std-decorators.esm.js

@@ -1,4 +1,4 @@
-import { d as decorator } from './chunks/decorator-GnHw1Az7.esm.js';
+import { d as decorator } from './chunks/decorator-DqiszP7i.esm.js';
 
 // In order to avoid async re-entrance, we could use zone.js or something like that.
 const syncCalculating = [];

package/dist/std-decorators.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var decorator = require('./chunks/decorator-D4DU97Zg.js');
+var decorator = require('./chunks/decorator-DLvrD0UF.js');
 
 // In order to avoid async re-entrance, we could use zone.js or something like that.
 const syncCalculating = [];

package/docs/ai/api-reference.md

@@ -0,0 +1,133 @@
+# Mutts API Context
+
+This file contains the aggregated type definitions for the Mutts library.
+AI Agents should read this code block to understand correct function signatures and types.
+
+```typescript
+/**
+ * MUTTS API CONTEXT FILE
+ */
+
+// --------------------------------------------------------------------------------
+// CORE REACTIVITY
+// --------------------------------------------------------------------------------
+
+export declare const Effect: unique symbol;
+export declare const cleanup: unique symbol;
+export declare const getAt: unique symbol;
+export declare const setAt: unique symbol;
+/**
+ * Symbol to check if an object is reactive
+ */
+export declare const Reactive: unique symbol;
+/**
+ * Symbol to map back from a reactive proxy to its original target
+ */
+export declare const Raw: unique symbol;
+export type ScopedCallback = (() => void | (() => void)) & {
+    [cleanup]?: () => void;
+};
+export type DependencyFunction = <T>(fn: () => T) => T;
+export type DependencyAccess = {
+    tracked: DependencyFunction;
+    ascend: DependencyFunction;
+    reaction: boolean;
+};
+
+export declare function reactive<T extends object>(target: T): T;
+export declare function effect(fn: (access: DependencyAccess, ...args: any[]) => (ScopedCallback | undefined | void), ...args: any[]): ScopedCallback;
+export declare function unwrap<T>(obj: T): T;
+export declare function isReactive(obj: any): boolean;
+export declare function isNonReactive(obj: any): boolean;
+export declare function untracked<T>(fn: () => T): T;
+
+// --------------------------------------------------------------------------------
+// REACTIVE HELPERS
+// --------------------------------------------------------------------------------
+
+export declare function atomic<T extends (...args: any[]) => any>(fn: T): T;
+export declare function memoize<Result, Args extends any[]>(fn: (...args: Args) => Result, maxArgs?: number): (...args: Args) => Result;
+export declare function deepWatch(source: any, callback: (path: string[], value: any) => void): () => void;
+export declare function biDi<T>(target: (val: T) => void, source: { get: () => T, set: (v: T) => void }): (val: T) => void;
+
+// --------------------------------------------------------------------------------
+// COLLECTIONS
+// --------------------------------------------------------------------------------
+
+export interface Register<T, K extends PropertyKey = PropertyKey> extends Iterable<T> {
+    length: number;
+    [index: number]: T;
+    get(key: K): T | undefined;
+    set(key: K, value: T): void;
+    hasKey(key: K): boolean;
+    indexOfKey(key: K): number;
+    remove(key: K): void;
+    removeAt(index: number): T | undefined;
+    push(...items: T[]): number;
+    // ... complete array methods are supported
+}
+
+export declare function register<T, K extends PropertyKey = PropertyKey>(keyFn: (item: T) => K, initial?: Iterable<T>): Register<T, K>;
+export declare function mapped<T, U>(inputs: readonly T[], compute: (input: T, index: number, output: U[]) => U): readonly U[];
+export declare function reduced<T, U, R extends object = any>(inputs: readonly T[], compute: (input: T, factor: R) => readonly U[]): readonly U[];
+export declare function project<S, R>(source: S, apply: (access: any, target: any) => any): R;
+export declare function organized<S, T>(source: S, apply: (access: any, target: T) => any, baseTarget?: T): T;
+
+// --------------------------------------------------------------------------------
+// DESTROYABLE
+// --------------------------------------------------------------------------------
+
+export declare const destructor: unique symbol;
+export declare const allocated: unique symbol;
+export declare function Destroyable<T>(base?: T): any;
+export declare class DestructionError extends Error {}
+
+// --------------------------------------------------------------------------------
+// EVENTS
+// --------------------------------------------------------------------------------
+
+export interface EventfulMixin {
+    on(event: string, callback: Function): void;
+    off(event: string, callback: Function): void;
+    emit(event: string, ...args: any[]): void;
+}
+export declare function Eventful<T extends new (...args: any[]) => any>(Base: T): T & (new (...args: any[]) => EventfulMixin);
+
+// --------------------------------------------------------------------------------
+// DECORATORS
+// --------------------------------------------------------------------------------
+
+export declare function cached(target: any, key: string, descriptor: PropertyDescriptor): void;
+export declare function debounce(delay: number): Function;
+export declare function throttle(delay: number): Function;
+export declare function deprecated(message?: string): Function;
+
+// --------------------------------------------------------------------------------
+// INTROSPECTION (AI Debugging)
+// --------------------------------------------------------------------------------
+
+export interface ReactivityGraph {
+    nodes: { id: string, label: string, type: 'effect'|'object' }[];
+    edges: { source: string, target: string, type: string }[];
+}
+
+export interface MutationRecord {
+    type: 'set' | 'add' | 'delete';
+    prop: PropertyKey;
+    oldValue: any;
+    newValue: any;
+    objectName?: string;
+}
+
+export declare function getDependencyGraph(): ReactivityGraph;
+export declare function getMutationHistory(): MutationRecord[];
+export declare const options: {
+    cycleHandling: 'throw' | 'warn' | 'break' | 'strict';
+    introspection: { enableHistory: boolean; historySize: number };
+};
+
+export enum ReactiveErrorCode {
+    CYCLE_DETECTED = 'CYCLE_DETECTED',
+    MAX_DEPTH_EXCEEDED = 'MAX_DEPTH_EXCEEDED',
+}
+```

package/docs/ai/manual.md

@@ -0,0 +1,105 @@
+# Mutts AI Agent Manual
+
+> [!IMPORTANT]
+> **Identity**: You are an AI Agent. This document is written for **YOU**.
+> **Purpose**: This file defines the protocols, schemas, and capabilities available to you when working with the `mutts` reactivity system.
+>
+> For exact TypeScript signatures of the entire library, consult the **[API Reference for Agents](./api-reference.md)**.
+
+## 1. Introspection Capability
+When you encounter reactivity bugs (infinite loops, unexpected updates), **DO NOT GUESS**. Use the introspection API to "see" the system state.
+
+### Enabling Introspection
+Introspection is often disabled by default for performance. Enable it before debugging.
+```typescript
+import { enableIntrospection, options } from 'mutts/introspection'
+
+// Enable history tracking (memory expensive, use only for debugging)
+enableIntrospection({ historySize: 50 })
+```
+
+### Dependency Graph
+Understanding "Who depends on What".
+```typescript
+import { getDependencyGraph } from 'mutts/introspection'
+
+const graph = getDependencyGraph()
+// Returns: { nodes: { id: string, type: 'effect'|'object', label: string }[], edges: { from: string, to: string, type: 'dependency' }[] }
+```
+**Agent Protocol**: If valid code is behaving unexpectedly, inspect the graph to ensure dependencies are actually linked as you expect.
+
+### Mutation History
+Understanding "What just happened".
+```typescript
+import { getMutationHistory } from 'mutts/introspection'
+
+const history = getMutationHistory()
+/*
+ Returns Array<{
+   id: number,
+   type: 'set' | 'add' | 'delete',
+   prop: string | symbol,
+   oldValue: any,
+   newValue: any,
+   objectName: string,   // "Human readable name"
+   source: string,       // "Effect X" or "External"
+   timestamp: number
+ }>
+*/
+```
+**Agent Protocol**: When diagnosing "why is this value wrong?", check the *last mutation* of that property in history.
+
+## 2. Structured Error Handling
+`mutts` throws `ReactiveError` instances. These are designed to be machine-parseable.
+
+### ReactiveErrorCode
+Always check `error.debugInfo.code`.
+```typescript
+enum ReactiveErrorCode {
+    CycleDetected = 'CYCLE_DETECTED',
+    MaxDepthExceeded = 'MAX_DEPTH_EXCEEDED',
+    MaxReactionExceeded = 'MAX_REACTION_EXCEEDED',
+    WriteInComputed = 'WRITE_IN_COMPUTED',
+    TrackingError = 'TRACKING_ERROR'
+}
+```
+
+### Debugging Protocols
+
+#### Protocol: Handling `CycleDetected` / `MaxDepthExceeded`
+**Symptom**: `ReactiveError` with code `CycleDetected` or `MaxDepthExceeded`.
+**Action**:
+1.  Read `error.debugInfo.cycle` (Array of effect names).
+2.  **CRITICAL**: Read `error.debugInfo.causalChain`.
+    *   It tells you the *logical path*: `Effect A` -> (modifies `x`) -> `Effect B` -> (modifies `y`) -> `Effect A`.
+3.  **CRITICAL**: Read `error.debugInfo.creationStack`.
+    *   This gives you the **File path and Line number** where the problematic effect was defined.
+
+**Example Error Object**:
+```json
+{
+  "message": "[reactive] Max effect chain reached...",
+  "debugInfo": {
+    "code": "MAX_DEPTH_EXCEEDED",
+    "causalChain": [
+      "Effect(Anonymous) -> (set 'count') -> Effect(Display)",
+      "Effect(Display) -> (set 'dummy') -> Effect(Anonymous)"
+    ],
+    "creationStack": "    at tests/my-test.ts:45:10\n    at ...",
+    "cycle": ["Effect(Anonymous)", "Effect(Display)"]
+  }
+}
+```
+
+## 3. Strict Mode
+If you are writing new code that might be complex, verify it with "Strict Mode".
+This forces a graph check *before* execution, preventing infinite loops from hanging the runtime.
+```typescript
+import { options } from 'mutts/introspection'
+options.cycleHandling = 'strict'
+```
+
+## 4. Architecture Constraints for Agents
+1.  **Do not** access properties starting with `_mutts_` directly unless instructed. These are internal implementation details.
+2.  **Do not** rely on `batchQueue` global state in your reasoning; it is ephemeral.
+3.  **Do** name your effects when possible (`effect(() => {}, { name: 'MyEffect' })`) to make your own future debugging easier.