@madronejs/core 1.0.18 → 1.1.1

package/types/interfaces.d.ts

@@ -1,27 +1,194 @@
+/**
+ * @module interfaces
+ *
+ * Core type definitions for Madrone's reactivity system.
+ *
+ * These interfaces define the contracts for property descriptors,
+ * integrations, and configuration options used throughout Madrone.
+ */
+/**
+ * Extended property descriptor with Madrone-specific options.
+ *
+ * Extends the standard JavaScript PropertyDescriptor with additional
+ * options for controlling reactive behavior.
+ */
 export interface MadroneDescriptor extends PropertyDescriptor {
-    /** Cache a computed property */
+    /**
+     * Whether to cache computed property values.
+     *
+     * When true (default), computed values are cached and only recalculated
+     * when dependencies change. Set to false to recalculate on every access.
+     *
+     * @default true
+     */
     cache?: boolean;
-    /** Define a deeply reactive property */
+    /**
+     * Whether to make nested objects/arrays reactive.
+     *
+     * When true (default), all nested objects and arrays within this property
+     * will also be wrapped in reactive proxies. Set to false for shallow
+     * reactivity where only top-level changes trigger updates.
+     *
+     * @default true
+     */
     deep?: boolean;
 }
+/**
+ * Descriptor options for computed (getter-based) properties.
+ *
+ * Computed properties derive their value from other reactive state
+ * and automatically update when dependencies change.
+ */
 export type MadroneComputedDescriptor = Pick<MadroneDescriptor, 'get' | 'set' | 'cache' | 'enumerable' | 'configurable'>;
+/**
+ * Descriptor options for reactive (value-based) properties.
+ *
+ * Reactive properties hold state that triggers updates when changed.
+ */
 export type MadronePropertyDescriptor = Pick<MadroneDescriptor, 'configurable' | 'enumerable' | 'value' | 'deep'>;
+/**
+ * A map of property names to their Madrone descriptors.
+ *
+ * Used when configuring multiple properties at once with `auto()`.
+ */
 export interface MadroneDescriptorMap {
     [key: string]: MadroneDescriptor;
 }
+/**
+ * Descriptor options available for decorator configuration.
+ *
+ * Excludes value-related fields since decorators work with
+ * class property definitions, not initial values.
+ */
 export type DecoratorDescriptorType = Omit<MadroneDescriptor, 'get' | 'set' | 'writable' | 'value'>;
+/**
+ * Configuration options for decorator functions.
+ */
 export type DecoratorOptionType = {
+    /** Property descriptor overrides */
     descriptors?: DecoratorDescriptorType;
 };
+/**
+ * Options for the `watch()` function.
+ */
 export type WatcherOptions = {
+    /**
+     * Whether to call the handler immediately with the current value.
+     *
+     * When true, the handler is invoked once immediately after setting
+     * up the watcher, with the current value and undefined as the old value.
+     *
+     * @default false
+     */
     immediate?: boolean;
 };
+/**
+ * Integration-specific options passed to property definition methods.
+ *
+ * Different integrations may use these options differently based on
+ * their underlying reactivity implementation.
+ */
+export interface IntegrationOptions {
+    /** Options passed to reactive property creation */
+    reactive?: unknown;
+    /** Options passed to computed property creation */
+    computed?: unknown;
+}
+/**
+ * Interface that all Madrone integrations must implement.
+ *
+ * Integrations provide the actual reactivity implementation. Madrone
+ * ships with `MadroneState` (standalone) and `MadroneVue3` (Vue 3 integration).
+ *
+ * @example
+ * ```ts
+ * // Creating a custom integration
+ * const MyIntegration: Integration = {
+ *   defineProperty(target, name, config, options) {
+ *     // Make the property reactive using your reactivity system
+ *   },
+ *   defineComputed(target, name, config, options) {
+ *     // Create a computed property with caching
+ *   },
+ *   toRaw(target) {
+ *     // Return the unwrapped object
+ *   },
+ *   watch(scope, handler, options) {
+ *     // Set up a reactive watcher
+ *     return () => { };  // cleanup function
+ *   }
+ * };
+ * ```
+ */
+/**
+ * A class constructor type that produces instances of type T.
+ *
+ * Unlike a simple `new (...args) => T` signature, this type also
+ * captures that constructors have a `prototype` property, which is
+ * important for mixin and class composition utilities.
+ *
+ * @typeParam T - The instance type that the constructor creates
+ */
+export type Constructor<T = object> = {
+    new (...args: unknown[]): T;
+    prototype: T;
+};
 export interface Integration {
-    defineProperty: (target: any, name: string, config: MadronePropertyDescriptor, options?: any) => any;
-    defineComputed: (target: any, name: string, config: MadroneComputedDescriptor, options?: any) => any;
-    toRaw?: <T>(target: T) => T;
-    watch?: <T>(scope: () => any, handler: (val: T, old?: T) => any, options?: WatcherOptions) => () => void;
-    describeComputed?: (name: string, config: MadroneComputedDescriptor, options?: any) => PropertyDescriptor;
-    describeProperty?: (name: string, config: MadronePropertyDescriptor, options?: any) => PropertyDescriptor;
+    /**
+     * Defines a reactive property on an object.
+     *
+     * @param target - The object to define the property on
+     * @param name - The property name
+     * @param config - Property configuration
+     * @param options - Integration-specific options
+     */
+    defineProperty: (target: object, name: string, config: MadronePropertyDescriptor, options?: IntegrationOptions) => void;
+    /**
+     * Defines a computed property on an object.
+     *
+     * @param target - The object to define the property on
+     * @param name - The property name
+     * @param config - Computed configuration with getter/setter
+     * @param options - Integration-specific options
+     */
+    defineComputed: (target: object, name: string, config: MadroneComputedDescriptor, options?: IntegrationOptions) => void;
+    /**
+     * Unwraps a reactive proxy to get the raw object.
+     *
+     * @param target - The potentially reactive object
+     * @returns The underlying raw object
+     */
+    toRaw?: <T extends object>(target: T) => T;
+    /**
+     * Creates a watcher that reacts to changes in reactive state.
+     *
+     * @param scope - Function that accesses reactive state to watch
+     * @param handler - Callback invoked when watched state changes
+     * @param options - Watcher configuration
+     * @returns A function to stop watching
+     */
+    watch?: <T>(scope: () => T, handler: (val: T, old?: T) => void, options?: WatcherOptions) => () => void;
+    /**
+     * Creates a property descriptor for a computed property.
+     *
+     * Used when you need the descriptor without immediately defining it.
+     *
+     * @param name - The property name (for debugging)
+     * @param config - Computed configuration
+     * @param options - Integration-specific options
+     * @returns A standard PropertyDescriptor
+     */
+    describeComputed?: (name: string, config: MadroneComputedDescriptor, options?: IntegrationOptions) => PropertyDescriptor;
+    /**
+     * Creates a property descriptor for a reactive property.
+     *
+     * Used when you need the descriptor without immediately defining it.
+     *
+     * @param name - The property name (for debugging)
+     * @param config - Property configuration
+     * @param options - Integration-specific options
+     * @returns A standard PropertyDescriptor
+     */
+    describeProperty?: (name: string, config: MadronePropertyDescriptor, options?: IntegrationOptions) => PropertyDescriptor;
 }
 //# sourceMappingURL=interfaces.d.ts.map

package/types/reactivity/Computed.d.ts

@@ -1,8 +1,51 @@
+/**
+ * @module Computed
+ *
+ * Creates cached, auto-updating computed values from reactive dependencies.
+ */
 import { ObservableOptions } from './Observer';
 /**
- * Create a new computed instance
- * @param options the computed options
- * @returns the created instance
+ * Creates a computed value that caches its result and auto-updates when dependencies change.
+ *
+ * A computed value is defined by a getter function. The result is cached and only
+ * recalculated when one of its reactive dependencies changes. This provides efficient
+ * derived state that stays in sync with source data.
+ *
+ * @typeParam T - The type of the computed value
+ * @param options - Configuration for the computed value
+ * @param options.get - Getter function that computes the value
+ * @param options.set - Optional setter function for writable computed values
+ * @param options.name - Optional name for debugging
+ * @param options.cache - Whether to cache the value (default: true)
+ * @returns An ObservableItem with a `.value` property
+ *
+ * @example
+ * ```ts
+ * import { Reactive, Computed } from '@madronejs/core';
+ *
+ * const state = Reactive({ firstName: 'John', lastName: 'Doe' });
+ *
+ * const fullName = Computed({
+ *   get: () => `${state.firstName} ${state.lastName}`,
+ *   name: 'fullName'
+ * });
+ *
+ * console.log(fullName.value); // 'John Doe'
+ *
+ * state.firstName = 'Jane';
+ * console.log(fullName.value); // 'Jane Doe' (automatically updated)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Writable computed
+ * const doubleCount = Computed({
+ *   get: () => state.count * 2,
+ *   set: (val) => { state.count = val / 2; }
+ * });
+ *
+ * doubleCount.value = 10; // Sets state.count to 5
+ * ```
  */
 export default function Computed<T>(options: ObservableOptions<T>): import("./Observer").ObservableItem<T>;
 //# sourceMappingURL=Computed.d.ts.map

package/types/reactivity/Observer.d.ts

@@ -1,30 +1,98 @@
-export declare function getCurrentObserver(): ObservableItem<any>;
+/**
+ * @module Observer
+ *
+ * Low-level observable implementation with dependency tracking.
+ *
+ * Observer is the foundation of Madrone's reactivity system. It tracks
+ * which reactive properties are accessed during computation and schedules
+ * updates when those dependencies change.
+ */
+/**
+ * Returns the currently running Observer, if any.
+ *
+ * Used internally to track which Observer should be notified when
+ * reactive properties are accessed.
+ *
+ * @returns The current Observer or undefined if none is running
+ * @internal
+ */
+export declare function getCurrentObserver(): ObservableItem<unknown> | undefined;
+/**
+ * Lifecycle hooks that can be called on an Observer.
+ */
 export declare enum OBSERVER_HOOK {
+    /** Called when the computed value is read */
     onGet = "onGet",
+    /** Called when a writable computed is set */
     onSet = "onSet",
+    /** Called asynchronously after dependencies change */
     onChange = "onChange",
+    /** Called synchronously when dependencies change (before async scheduling) */
     onImmediateChange = "onImmediateChange"
 }
+/**
+ * Type for Observer lifecycle hook callbacks.
+ * @typeParam T - The type of the observed value
+ */
 export type ObservableHookType<T> = (obs: ObservableItem<T>) => void;
+/**
+ * Collection of lifecycle hooks for an Observer.
+ * @typeParam T - The type of the observed value
+ */
 export type ObservableHooksType<T> = {
+    /** Called when the value is accessed */
     onGet?: ObservableHookType<T>;
+    /** Called when the value is set (writable computed only) */
     onSet?: ObservableHookType<T>;
+    /** Called asynchronously after dependencies change */
     onChange?: ObservableHookType<T>;
+    /** Called synchronously when dependencies change */
     onImmediateChange?: ObservableHookType<T>;
 };
+/**
+ * Configuration options for creating an Observer.
+ * @typeParam T - The type of the observed value
+ */
 export type ObservableOptions<T> = {
+    /** Getter function that computes the value */
     get: () => T;
+    /** Optional name for debugging */
     name?: string;
+    /** Optional setter for writable computed values */
     set?: (val: T) => void;
+    /** Whether to cache the computed value (default: true) */
     cache?: boolean;
 } & ObservableHooksType<T>;
+/**
+ * Core observable class that tracks dependencies and caches computed values.
+ *
+ * ObservableItem wraps a getter function and automatically tracks which
+ * reactive properties are accessed when the getter runs. When those
+ * dependencies change, the cached value is invalidated and change hooks
+ * are called.
+ *
+ * @typeParam T - The type of the observed value
+ */
 declare class ObservableItem<T> {
+    /**
+     * Factory method to create a new ObservableItem.
+     * @internal
+     */
     static create<CType>(...args: ConstructorParameters<typeof ObservableItem<CType>>): ObservableItem<CType>;
+    /**
+     * Creates a new ObservableItem.
+     * @param options - Configuration options
+     */
     constructor(options: ObservableOptions<T>);
+    /** Name for debugging purposes */
     name: string;
+    /** Whether this observer is still active */
     alive: boolean;
+    /** Whether the cached value needs to be recomputed */
     dirty: boolean;
+    /** The previous value (available during onChange) */
     prev: T;
+    /** Whether to cache the computed value */
     cache: boolean;
     private cachedVal;
     private hooks;
@@ -45,5 +113,27 @@ declare class ObservableItem<T> {
     set value(val: T);
 }
 export { ObservableItem };
-export default function Observer<T = any>(...args: Parameters<typeof ObservableItem.create<T>>): ObservableItem<T>;
+/**
+ * Creates a new Observer that tracks dependencies and caches computed values.
+ *
+ * This is the low-level API for creating reactive computations. Most users
+ * should use `Computed` or `Watcher` instead, which provide more convenient
+ * interfaces on top of Observer.
+ *
+ * @typeParam T - The type of the observed value
+ * @param args - Configuration options for the observer
+ * @returns An ObservableItem instance
+ *
+ * @example
+ * ```ts
+ * const obs = Observer({
+ *   get: () => state.count * 2,
+ *   onChange: (o) => console.log('Changed to:', o.value)
+ * });
+ *
+ * console.log(obs.value); // Runs getter, tracks dependencies
+ * state.count = 5; // Triggers onChange
+ * ```
+ */
+export default function Observer<T = unknown>(...args: Parameters<typeof ObservableItem.create<T>>): ObservableItem<T>;
 //# sourceMappingURL=Observer.d.ts.map

package/types/reactivity/Reactive.d.ts

@@ -1,15 +1,55 @@
+/**
+ * @module Reactive
+ *
+ * Core reactivity primitive that wraps objects in reactive Proxies.
+ */
 import { ReactiveOptions } from './interfaces';
 /**
- * Observe an object
- * @param {Object} target the object to observe
- * @param {Object} options the observation options
- * @returns {Proxy} a proxied version of the object that can be observed
+ * Wraps an object in a reactive Proxy that tracks property access and mutations.
+ *
+ * When properties are read, they become dependencies of any active Observer.
+ * When properties are written, all dependent Observers are notified to update.
+ *
+ * Supports objects, arrays, Maps, and Sets. By default, reactivity is deep -
+ * nested objects are also wrapped in Proxies when accessed.
+ *
+ * @typeParam T - The type of object being made reactive
+ * @param target - The object to make reactive
+ * @param options - Configuration options for reactive behavior
+ * @returns A reactive Proxy wrapping the target object
+ *
+ * @example
+ * ```ts
+ * import { Reactive, Watcher } from '@madronejs/core';
+ *
+ * const state = Reactive({ count: 0, nested: { value: 1 } });
+ *
+ * // Watcher tracks `count` as a dependency
+ * Watcher(
+ *   () => state.count,
+ *   (val) => console.log(`Count: ${val}`)
+ * );
+ *
+ * state.count = 5; // Triggers watcher
+ * state.nested.value = 2; // Also reactive (deep by default)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With Maps and Sets
+ * const set = Reactive(new Set([1, 2, 3]));
+ * const map = Reactive(new Map([['key', 'value']]));
+ *
+ * // All operations are reactive
+ * set.add(4);
+ * map.set('newKey', 'newValue');
+ * ```
  */
 declare function Reactive<T extends object>(target: T, options?: ReactiveOptions<T>): T;
 declare namespace Reactive {
-    var getStringType: (obj: any) => any;
-    var hasHandler: (type: any) => boolean;
-    var typeHandler: (type: any, hooks: any) => any;
+    var getStringType: (obj: unknown) => string;
+    var hasHandler: (type: string) => boolean;
+    var typeHandler: (type: string, hooks: ReactiveOptions) => ProxyHandler<object>;
 }
 export default Reactive;
 //# sourceMappingURL=Reactive.d.ts.map

package/types/reactivity/Watcher.d.ts

@@ -1,10 +1,59 @@
+/**
+ * @module Watcher
+ *
+ * Watches reactive expressions and runs callbacks when they change.
+ */
 import { WatcherOptions } from '../interfaces';
 /**
- * Watch an observable for changes
- * @param get the getter function returning the item to watch
- * @param handler the callback whenever the value returned from `get` changes
- * @param {Boolean} [options.deep] deeply watch the value
- * @returns a disposer
+ * Watches a reactive expression and calls a handler when its value changes.
+ *
+ * The getter function is called immediately to establish dependencies.
+ * Whenever any reactive property accessed within the getter changes,
+ * the function re-runs and the handler is called with the new and old values.
+ *
+ * @typeParam T - The type of the watched value
+ * @param get - Function that returns the value to watch. All reactive
+ *              properties accessed become dependencies.
+ * @param handler - Callback invoked when the watched value changes
+ * @param options - Optional configuration
+ * @param options.immediate - If true, calls handler immediately with current value
+ * @returns A disposer function that stops watching when called
+ *
+ * @example
+ * ```ts
+ * import { Reactive, Watcher } from '@madronejs/core';
+ *
+ * const state = Reactive({ count: 0 });
+ *
+ * // Watch a single property
+ * const stop = Watcher(
+ *   () => state.count,
+ *   (newVal, oldVal) => console.log(`Count: ${oldVal} → ${newVal}`)
+ * );
+ *
+ * state.count = 5; // logs: "Count: 0 → 5"
+ * stop(); // Stop watching
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Watch a computed expression
+ * const stop = Watcher(
+ *   () => state.items.filter(i => i.active).length,
+ *   (count) => console.log(`${count} active items`)
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Immediate execution
+ * Watcher(
+ *   () => state.count,
+ *   (val) => console.log(`Count is ${val}`),
+ *   { immediate: true }
+ * );
+ * // Immediately logs: "Count is 0"
+ * ```
  */
-export default function Watcher<T>(get: () => T, handler: (val?: T, old?: T) => any, options?: WatcherOptions): () => void;
+export default function Watcher<T>(get: () => T, handler: (val?: T, old?: T) => unknown, options?: WatcherOptions): () => void;
 //# sourceMappingURL=Watcher.d.ts.map

package/types/reactivity/global.d.ts

@@ -1,51 +1,91 @@
+/**
+ * @module reactivity/global
+ *
+ * Global state and dependency tracking for the reactivity system.
+ *
+ * This module manages the core data structures that enable automatic
+ * dependency tracking and change notification. It maintains mappings
+ * between reactive proxies, their targets, and the observers that
+ * depend on them.
+ *
+ * @internal
+ */
 import { ObservableItem } from './Observer';
+/** Symbol used to track when an object's keys change */
 export declare const KEYS_SYMBOL: unique symbol;
+/** Symbol used for observer dependency tracking */
 export declare const OBSERVER_SYMBOL: unique symbol;
-/** Check if the current target has a proxy associated with it */
-export declare const isReactiveTarget: (target: any) => boolean;
-/** Check if the current proxy has a target object */
-export declare const isReactive: (trk: any) => boolean;
-export declare const getReactive: (target: any) => any;
-export declare const getTarget: (tracker: any) => any;
-export declare const getProxy: (targetOrProxy: any) => any;
-export declare const toRaw: (targetOrProxy: any) => any;
-export declare const getDependencies: (observer: any) => Map<string | symbol | ObservableItem<any>, Set<any>>;
-/** Get the list of items that are observing a given proxy */
-export declare const getObservers: (tracker: any) => Map<string | symbol | ObservableItem<any>, Set<ObservableItem<any>>>;
-export declare const addReactive: (target: any, proxy: any) => void;
-export declare const schedule: (task: any) => void;
-/**
- * Clear all of the current dependencies an observer has
- * @param {Observable} obs the observable to clear it's dependencies
- * @param {String} key the key to clear
- * @returns {void}
- */
-export declare const observerClear: (obs: ObservableItem<any>, key: string | symbol | ObservableItem<any>) => void;
+type DependencyKey = string | symbol | ObservableItem<unknown>;
+/** Checks if the given object has a reactive proxy associated with it */
+export declare const isReactiveTarget: (target: object) => boolean;
+/** Checks if the given object is a reactive proxy */
+export declare const isReactive: (trk: object) => boolean;
+/** Gets the reactive proxy for a target object */
+export declare const getReactive: <T extends object>(target: T) => T | undefined;
+/** Gets the underlying target for a reactive proxy */
+export declare const getTarget: <T extends object>(tracker: T) => T | undefined;
+/** Gets the proxy for an object, whether passed a target or proxy */
+export declare const getProxy: <T extends object>(targetOrProxy: T) => T | undefined;
+/**
+ * Unwraps a reactive proxy to get the raw underlying object.
+ *
+ * If the object is not a proxy, returns it unchanged.
+ */
+export declare const toRaw: <T extends object>(targetOrProxy: T) => T;
+/** Gets all dependencies for an observer */
+export declare const getDependencies: (observer: ObservableItem<unknown>) => Map<DependencyKey, Set<object>>;
+/** Gets all observers watching a given proxy */
+export declare const getObservers: (tracker: object) => Map<DependencyKey, Set<ObservableItem<unknown>>>;
+/**
+ * Registers a target/proxy pair in the tracking system.
+ * @internal
+ */
+export declare const addReactive: <T extends object>(target: T, proxy: T) => void;
+/**
+ * Schedules a task to run asynchronously in the next microtask.
+ *
+ * Tasks are batched and executed together. Used to batch multiple
+ * change notifications into a single update cycle.
+ *
+ * @param task - The function to execute
+ * @internal
+ */
+export declare const schedule: (task: () => void) => void;
+/**
+ * Clear a specific dependency key for an observer
+ * @param obs the observable to clear dependencies for
+ * @param key the key to clear
+ */
+export declare const observerClear: (obs: ObservableItem<unknown>, key: DependencyKey) => void;
+/**
+ * Clear ALL dependencies for an observer.
+ * Called before re-running to ensure stale dependencies are removed.
+ * @param obs the observable to clear all dependencies for
+ */
+export declare const observerClearAll: (obs: ObservableItem<unknown>) => void;
 /**
  * Make an observer depend on a trackable item
- * @param {trackable} trk the trackable item we're depending on
- * @param {String} key the key to depend on
- * @returns {void}
+ * @param trk the trackable item we're depending on
+ * @param key the key to depend on
  */
-export declare const dependTracker: (trk: object, key: string | symbol | ObservableItem<any>) => void;
+export declare const dependTracker: (trk: object, key: DependencyKey) => void;
 /**
  * Make an observer depend on a raw target
  * @param target the target to depend on
  * @param key the key to depend on
- * @returns {void}
  */
 export declare const dependTarget: (target: object, key: string | symbol) => void;
 /**
  * Tell all observers of a trackable that the trackable changed
  * @param trk the trackable that changed
  * @param key the key on the trackable that changed
- * @return {void}
  */
-export declare const trackerChanged: (trk: any, key: any) => void;
+export declare const trackerChanged: (trk: object, key: DependencyKey) => void;
 /**
  * Tell all observers listening to this target that this changed
  * @param target the target that changed
  * @param key the key on the trackable that changed
  */
-export declare const targetChanged: (target: any, key: string | symbol) => void;
+export declare const targetChanged: (target: object, key: string | symbol) => void;
+export {};
 //# sourceMappingURL=global.d.ts.map