@madronejs/core 1.0.18 → 1.1.1

package/types/auto.d.ts

@@ -1,7 +1,99 @@
 import { MadroneDescriptor, WatcherOptions } from './interfaces';
+/**
+ * Defines a single reactive or computed property on an object.
+ *
+ * If the descriptor has a `get` function, it creates a computed property that
+ * automatically tracks dependencies and caches its result. Otherwise, it creates
+ * a reactive property that triggers updates when changed.
+ *
+ * @param obj - The target object to define the property on
+ * @param key - The property name to define
+ * @param descriptor - Configuration for the property including getter/setter or value
+ * @throws Error if no integration is configured (call `Madrone.use()` first)
+ *
+ * @example
+ * ```ts
+ * const state = { count: 0 };
+ * define(state, 'doubled', {
+ *   get() { return this.count * 2; },
+ *   cache: true
+ * });
+ * ```
+ */
 export declare function define<T extends object>(obj: T, key: string, descriptor: MadroneDescriptor): void;
+/**
+ * Automatically makes all properties on an object reactive.
+ *
+ * Iterates through all own properties of the object and converts them:
+ * - Properties with getters become cached computed properties
+ * - Regular properties become deeply reactive by default
+ *
+ * This is the primary way to create reactive state in Madrone.
+ *
+ * @param obj - The object to make reactive
+ * @param objDescriptors - Optional per-property configuration overrides
+ * @returns The same object, now with reactive properties
+ *
+ * @example
+ * ```ts
+ * const state = auto({
+ *   count: 0,
+ *   get doubled() { return this.count * 2; }
+ * });
+ *
+ * state.count = 5;
+ * console.log(state.doubled); // 10
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With descriptor overrides
+ * const state = auto(
+ *   { items: [] },
+ *   { items: { deep: false } } // Shallow reactivity for items
+ * );
+ * ```
+ */
 export declare function auto<T extends object>(obj: T, objDescriptors?: {
     [K in keyof T]?: MadroneDescriptor;
 }): T;
-export declare function watch<T>(scope: () => T, handler: (val: T, old: T) => any, options?: WatcherOptions): () => void;
+/**
+ * Watches a reactive expression and calls a handler when its value changes.
+ *
+ * The `scope` function is called immediately to establish dependencies.
+ * Whenever any reactive property accessed within `scope` changes, the
+ * function re-runs and `handler` is called with the new and old values.
+ *
+ * @param scope - A function that returns the value to watch. All reactive
+ *                properties accessed within this function 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
+ * const state = auto({ count: 0 });
+ *
+ * const stop = watch(
+ *   () => state.count,
+ *   (newVal, oldVal) => console.log(`Changed from ${oldVal} to ${newVal}`)
+ * );
+ *
+ * state.count = 5; // logs: "Changed from 0 to 5"
+ * stop(); // Stop watching
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Watch with immediate execution
+ * watch(
+ *   () => state.count,
+ *   (val) => console.log(`Count is ${val}`),
+ *   { immediate: true }
+ * );
+ * // Immediately logs: "Count is 0"
+ * ```
+ */
+export declare function watch<T>(scope: () => T, handler: (val: T, old: T) => void, options?: WatcherOptions): (() => void) | undefined;
 //# sourceMappingURL=auto.d.ts.map

package/types/decorate.d.ts

@@ -1,24 +1,137 @@
-import { DecoratorDescriptorType } from './interfaces';
-export declare function classMixin(...mixins: Array<() => any>): (target: () => any) => void;
 /**
- * Configure a getter property to be cached
- * @param target The target to add the computed property to
- * @param key The name of the computed property
- * @param descriptor property descriptors
- * @returns the modified property descriptors
+ * @module decorate
+ *
+ * TypeScript decorators for class-based reactive state management.
+ *
+ * Provides `@reactive` and `@computed` decorators that enable automatic
+ * reactivity on class properties and getters. These decorators lazily
+ * initialize reactive properties on first access, making them efficient
+ * for large class hierarchies.
+ *
+ * @example
+ * ```ts
+ * import { reactive, computed } from '@madronejs/core';
+ *
+ * class Counter {
+ *   @reactive count = 0;
+ *
+ *   @computed get doubled() {
+ *     return this.count * 2;
+ *   }
+ * }
+ * ```
  */
-export declare function computed(target: any, key: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+import { DecoratorDescriptorType, Constructor } from './interfaces';
+/**
+ * Class decorator that mixes in methods from other classes.
+ *
+ * Copies all prototype properties from the mixin classes onto the
+ * decorated class. Useful for composing behavior from multiple sources.
+ *
+ * @param mixins - Classes whose prototypes will be mixed in
+ * @returns A class decorator function
+ *
+ * @example
+ * ```ts
+ * class Timestamped {
+ *   createdAt = Date.now();
+ * }
+ *
+ * class Serializable {
+ *   toJSON() { return JSON.stringify(this); }
+ * }
+ *
+ * @classMixin(Timestamped, Serializable)
+ * class Model {
+ *   name: string;
+ * }
+ *
+ * const model = new Model();
+ * model.toJSON(); // Works - mixed in from Serializable
+ * ```
+ */
+export declare function classMixin(...mixins: Constructor[]): (target: Constructor) => void;
+/**
+ * Decorator that creates a cached computed property from a getter.
+ *
+ * When applied to a getter, the computed value is cached and only recalculated
+ * when its reactive dependencies change. This provides efficient derived state
+ * that automatically stays in sync with source data.
+ *
+ * The decorator lazily initializes the computed property on first access,
+ * so it works correctly with class inheritance and instance creation.
+ *
+ * @param target - The class prototype
+ * @param key - The property name
+ * @param descriptor - The property descriptor containing the getter
+ * @returns Modified property descriptor with caching behavior
+ *
+ * @example
+ * ```ts
+ * import { reactive, computed } from '@madronejs/core';
+ *
+ * class ShoppingCart {
+ *   @reactive items: Array<{ price: number }> = [];
+ *
+ *   @computed get total() {
+ *     return this.items.reduce((sum, item) => sum + item.price, 0);
+ *   }
+ *
+ *   @computed get isEmpty() {
+ *     return this.items.length === 0;
+ *   }
+ * }
+ *
+ * const cart = new ShoppingCart();
+ * cart.items.push({ price: 10 });
+ * console.log(cart.total); // 10 (computed once)
+ * console.log(cart.total); // 10 (cached, no recalculation)
+ * ```
+ */
+export declare function computed(target: object, key: string, descriptor: PropertyDescriptor): PropertyDescriptor;
 export declare namespace computed {
-    var configure: (descriptorOverrides: DecoratorDescriptorType) => (target: any, key: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+    var configure: (descriptorOverrides: DecoratorDescriptorType) => (target: object, key: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 }
 /**
- * Configure a reactive property
- * @param target The target to add the reactive property to
- * @param key The name of the reactive property
+ * Decorator that makes a class property reactive.
+ *
+ * When the property value changes, any computed properties or watchers
+ * that depend on it will automatically update. By default, reactivity
+ * is deep - nested objects and arrays will also be reactive.
+ *
+ * The decorator lazily initializes reactivity on first access, making
+ * it efficient for classes with many properties that may not all be used.
+ *
+ * @param target - The class prototype (or constructor for static properties)
+ * @param key - The property name
+ *
+ * @example
+ * ```ts
+ * import { reactive, computed, watch } from '@madronejs/core';
+ *
+ * class User {
+ *   @reactive name = 'Anonymous';
+ *   @reactive preferences = { theme: 'dark' };
+ *
+ *   @computed get greeting() {
+ *     return `Hello, ${this.name}!`;
+ *   }
+ * }
+ *
+ * const user = new User();
+ *
+ * watch(
+ *   () => user.name,
+ *   (name) => console.log(`Name changed to ${name}`)
+ * );
+ *
+ * user.name = 'Alice'; // Triggers watcher, updates greeting
+ * user.preferences.theme = 'light'; // Deep reactivity works
+ * ```
  */
-export declare function reactive(target: any, key: string): void;
+export declare function reactive(target: object, key: string): void;
 export declare namespace reactive {
-    var shallow: (target: any, key: string) => void;
-    var configure: (descriptorOverrides: DecoratorDescriptorType) => (target: any, key: string) => void;
+    var shallow: (target: object, key: string) => void;
+    var configure: (descriptorOverrides: DecoratorDescriptorType) => (target: object, key: string) => void;
 }
 //# sourceMappingURL=decorate.d.ts.map

package/types/global.d.ts

@@ -1,12 +1,146 @@
+/**
+ * @module global
+ *
+ * Global state management for Madrone integrations and reactive object tracking.
+ *
+ * Madrone uses a plugin architecture where "integrations" provide the actual
+ * reactivity implementation. This module manages the global integration registry
+ * and provides utilities for tracking object access patterns.
+ */
 import { Integration } from './interfaces';
+/**
+ * Returns all currently registered integrations.
+ *
+ * Integrations are the pluggable backends that provide reactivity.
+ * Multiple integrations can be registered, though typically only one is used.
+ *
+ * @returns An array of all registered Integration instances
+ *
+ * @example
+ * ```ts
+ * import { getIntegrations } from '@madronejs/core';
+ *
+ * const integrations = getIntegrations();
+ * console.log(`${integrations.length} integrations registered`);
+ * ```
+ */
 export declare function getIntegrations(): Array<Integration>;
+/**
+ * Registers a new integration with Madrone.
+ *
+ * The most recently added integration becomes the active one used by
+ * `auto()`, `define()`, and other reactive primitives. Integrations
+ * provide methods for creating reactive properties, computed values,
+ * and watchers.
+ *
+ * @param integration - The integration to register
+ *
+ * @example
+ * ```ts
+ * import Madrone, { MadroneState } from '@madronejs/core';
+ *
+ * // Register the built-in state integration
+ * Madrone.use(MadroneState);
+ *
+ * // Or register directly
+ * addIntegration(MadroneState);
+ * ```
+ */
 export declare function addIntegration(integration: Integration): void;
-export declare function removeIntegration(integration: any): void;
-export declare function getIntegration(): Integration;
-/** Get the raw value of an object (without the proxy) */
-export declare function toRaw<T>(obj: T): T;
-/** Mark an object as accessed */
+/**
+ * Removes a previously registered integration.
+ *
+ * After removal, the most recently added remaining integration becomes active.
+ * If no integrations remain, reactive operations will throw errors.
+ *
+ * @param integration - The integration to remove
+ *
+ * @example
+ * ```ts
+ * import { removeIntegration, MadroneState } from '@madronejs/core';
+ *
+ * // Remove when switching integrations or cleaning up
+ * removeIntegration(MadroneState);
+ * ```
+ */
+export declare function removeIntegration(integration: Integration): void;
+/**
+ * Returns the currently active integration.
+ *
+ * This is the integration that will be used by `auto()`, `define()`,
+ * `watch()`, and other reactive primitives. Returns undefined if no
+ * integration has been registered.
+ *
+ * @returns The current active Integration, or undefined if none registered
+ *
+ * @example
+ * ```ts
+ * import { getIntegration } from '@madronejs/core';
+ *
+ * const integration = getIntegration();
+ * if (!integration) {
+ *   console.warn('No integration configured - call Madrone.use() first');
+ * }
+ * ```
+ */
+export declare function getIntegration(): Integration | undefined;
+/**
+ * Unwraps a reactive proxy to get the underlying raw object.
+ *
+ * When you create reactive state with `auto()` or `Reactive()`, the returned
+ * object is actually a Proxy. This function returns the original object
+ * without the reactive wrapper, which is useful for:
+ * - Comparing object identity
+ * - Passing to external libraries that don't work with Proxies
+ * - Debugging reactive behavior
+ *
+ * @typeParam T - The type of the object
+ * @param obj - The potentially reactive object to unwrap
+ * @returns The raw underlying object without reactive proxy
+ *
+ * @example
+ * ```ts
+ * import { auto, toRaw } from '@madronejs/core';
+ *
+ * const original = { count: 0 };
+ * const reactive = auto(original);
+ *
+ * console.log(reactive === original); // false (reactive is a Proxy)
+ * console.log(toRaw(reactive) === original); // true
+ * ```
+ */
+export declare function toRaw<T extends object>(obj: T): T;
+/**
+ * Records that a reactive object was accessed at the current time.
+ *
+ * This is called internally by reactive getters to track when objects
+ * are read. Used for debugging and performance analysis.
+ *
+ * @param obj - The object that was accessed
+ * @internal
+ */
 export declare function objectAccessed(obj: object): void;
-/** The last time any reactive property was accessed on a given object */
-export declare function lastAccessed(obj: object): number;
+/**
+ * Returns the timestamp of when a reactive object was last accessed.
+ *
+ * Useful for debugging reactive behavior or implementing features like
+ * "last viewed" timestamps without additional tracking code.
+ *
+ * @param obj - The reactive object to check
+ * @returns Unix timestamp (milliseconds) of last access, or undefined if never accessed
+ *
+ * @example
+ * ```ts
+ * import { auto, lastAccessed } from '@madronejs/core';
+ *
+ * const state = auto({ count: 0 });
+ *
+ * console.log(lastAccessed(state)); // undefined (not accessed yet)
+ *
+ * const value = state.count; // access the property
+ *
+ * console.log(lastAccessed(state)); // 1702345678901 (timestamp)
+ * ```
+ */
+export declare function lastAccessed(obj: object): number | undefined;
 //# sourceMappingURL=global.d.ts.map

package/types/integrations/MadroneState.d.ts

@@ -1,25 +1,106 @@
-import { Integration, MadroneComputedDescriptor, MadronePropertyDescriptor } from '../interfaces';
+/**
+ * @module MadroneState
+ *
+ * Standalone reactivity integration using Madrone's built-in reactive system.
+ *
+ * This is the default integration for Madrone, providing a complete reactivity
+ * implementation based on JavaScript Proxies. It's the recommended integration
+ * for non-Vue applications.
+ *
+ * @example
+ * ```ts
+ * import Madrone, { MadroneState, auto } from '@madronejs/core';
+ *
+ * // Initialize with the integration
+ * Madrone.use(MadroneState);
+ *
+ * // Now use reactive features
+ * const state = auto({ count: 0 });
+ * ```
+ */
+import { Integration, IntegrationOptions, MadroneComputedDescriptor, MadronePropertyDescriptor } from '../interfaces';
 import { ReactiveOptions } from '../reactivity/interfaces';
 import { ObservableHooksType } from '../reactivity/Observer';
-type MadroneStateOptions<T = any> = {
+/**
+ * Configuration options for MadroneState integration.
+ *
+ * Allows customizing the behavior of reactive properties and computed values.
+ *
+ * @typeParam T - The type of computed values (for typing onChange callbacks)
+ */
+export type MadroneStateOptions<T = unknown> = {
+    /** Options passed to Reactive() for property creation */
     reactive?: ReactiveOptions;
+    /** Hooks for computed property lifecycle events */
     computed?: ObservableHooksType<T>;
 };
-export declare function describeComputed<T = any>(name: string, config: MadroneComputedDescriptor, options?: MadroneStateOptions<T>): {
-    enumerable: boolean;
-    configurable: boolean;
-    get: any;
-    set: any;
-};
-export declare function describeProperty(name: string, config: MadronePropertyDescriptor, options?: MadroneStateOptions): {
-    configurable: boolean;
-    enumerable: boolean;
-    get: () => any;
-    set: (val: any) => void;
-};
-export declare function defineComputed(target: any, name: string, config: MadroneComputedDescriptor, options: any): void;
-export declare function defineProperty(target: any, name: string, config: MadronePropertyDescriptor, options?: any): void;
+/**
+ * Creates a property descriptor for a computed property.
+ *
+ * The descriptor can be used with Object.defineProperty or stored
+ * for later use. If caching is enabled, creates a Computed observable
+ * that tracks dependencies automatically.
+ *
+ * @typeParam T - The computed value type
+ * @param name - Property name (used for debugging)
+ * @param config - Computed property configuration
+ * @param options - Optional hooks for lifecycle events
+ * @returns A PropertyDescriptor with reactive getter/setter
+ */
+export declare function describeComputed<T = unknown>(name: string, config: MadroneComputedDescriptor, options?: MadroneStateOptions<T>): PropertyDescriptor;
+/**
+ * Creates a property descriptor for a reactive property.
+ *
+ * The descriptor can be used with Object.defineProperty or stored
+ * for later use. Creates a Reactive proxy internally to track changes.
+ *
+ * @param name - Property name (used for debugging)
+ * @param config - Reactive property configuration
+ * @param options - Optional hooks for lifecycle events
+ * @returns A PropertyDescriptor with reactive getter/setter
+ */
+export declare function describeProperty(name: string, config: MadronePropertyDescriptor, options?: MadroneStateOptions): PropertyDescriptor;
+/**
+ * Defines a computed property directly on an object.
+ *
+ * Shorthand for calling describeComputed and Object.defineProperty.
+ *
+ * @param target - The object to define the property on
+ * @param name - The property name
+ * @param config - Computed configuration
+ * @param options - Integration-specific options
+ */
+export declare function defineComputed(target: object, name: string, config: MadroneComputedDescriptor, options?: IntegrationOptions): void;
+/**
+ * Defines a reactive property directly on an object.
+ *
+ * Shorthand for calling describeProperty and Object.defineProperty.
+ *
+ * @param target - The object to define the property on
+ * @param name - The property name
+ * @param config - Reactive property configuration
+ * @param options - Integration-specific options
+ */
+export declare function defineProperty(target: object, name: string, config: MadronePropertyDescriptor, options?: IntegrationOptions): void;
+/**
+ * The standalone MadroneState integration.
+ *
+ * Provides a complete reactivity system using JavaScript Proxies.
+ * This is the recommended integration for non-Vue applications.
+ *
+ * @example
+ * ```ts
+ * import Madrone, { MadroneState } from '@madronejs/core';
+ *
+ * Madrone.use(MadroneState);
+ * ```
+ */
 declare const MadroneState: Integration;
 export default MadroneState;
+/**
+ * Creates a watcher that reacts to changes in reactive expressions.
+ *
+ * Re-exported from the reactivity module for convenience.
+ */
 export { Watcher as watch } from '../reactivity';
 //# sourceMappingURL=MadroneState.d.ts.map

package/types/integrations/MadroneVue3.d.ts

@@ -1,3 +1,66 @@
+/**
+ * @module MadroneVue3
+ *
+ * Vue 3 integration for Madrone, bridging Madrone's reactivity with Vue's system.
+ *
+ * This integration allows you to use Madrone's composition patterns and decorators
+ * while having reactivity work seamlessly with Vue 3's rendering system. Vue
+ * components will automatically re-render when Madrone state changes.
+ *
+ * @example
+ * ```ts
+ * import Madrone from '@madronejs/core';
+ * import { MadroneVue3 } from '@madronejs/core';
+ * import { reactive, toRaw } from '../../node_modules/vue3';
+ *
+ * // Initialize with Vue 3's reactive system
+ * Madrone.use(MadroneVue3({ reactive, toRaw }));
+ *
+ * // Now Madrone state works with Vue components
+ * const store = auto({
+ *   count: 0,
+ *   get doubled() { return this.count * 2; }
+ * });
+ * ```
+ */
 import type { Integration } from '../interfaces';
-export default function MadroneVue3({ reactive, toRaw }?: any): Integration;
+/**
+ * Options for creating a Vue 3 integration.
+ */
+export interface MadroneVue3Options {
+    /** Vue's `reactive()` function from '../../node_modules/vue3' */
+    reactive: <T extends object>(target: T) => unknown;
+    /** Vue's `toRaw()` function from '../../node_modules/vue3' */
+    toRaw: <T>(proxy: T) => T;
+}
+/**
+ * Creates a Vue 3-compatible integration for Madrone.
+ *
+ * This factory function creates an integration that bridges Madrone's
+ * reactivity with Vue 3's reactive system. Changes to Madrone state
+ * will trigger Vue component re-renders.
+ *
+ * For simpler setup, use the pre-configured `madrone/integrations/vue` module instead.
+ *
+ * @param options - Vue 3 reactivity functions
+ * @param options.reactive - Vue's `reactive()` function from '../../node_modules/vue3'
+ * @param options.toRaw - Vue's `toRaw()` function from '../../node_modules/vue3'
+ * @returns An Integration compatible with Madrone.use()
+ * @throws Error if reactive function is not provided
+ *
+ * @example
+ * ```ts
+ * // Option 1: Use the pre-configured module (recommended)
+ * import Madrone from '@madronejs/core';
+ * import { MadroneVue } from '@madronejs/core';
+ * Madrone.use(MadroneVue);
+ *
+ * // Option 2: Manual configuration
+ * import Madrone from '@madronejs/core';
+ * import { MadroneVue3 as createMadroneVue3 } from '@madronejs/core';
+ * import { reactive, toRaw } from '../../node_modules/vue3';
+ * Madrone.use(createMadroneVue3({ reactive, toRaw }));
+ * ```
+ */
+export default function MadroneVue3(options: MadroneVue3Options): Integration;
 //# sourceMappingURL=MadroneVue3.d.ts.map

package/types/integrations/vue.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @module vue
+ *
+ * Pre-configured Vue 3 integration for Madrone.
+ *
+ * This module automatically imports Vue's reactivity functions, so you don't
+ * need to pass them manually. Just import and use directly.
+ *
+ * @example
+ * ```ts
+ * import Madrone from '@madronejs/core';
+ * import { MadroneVue } from '@madronejs/core';
+ *
+ * Madrone.use(MadroneVue);
+ *
+ * // That's it! Madrone now works with Vue's reactivity
+ * ```
+ */
+/**
+ * Pre-configured Vue 3 integration.
+ *
+ * Uses Vue's `reactive` and `toRaw` functions automatically.
+ * This is the recommended way to use Madrone with Vue 3.
+ *
+ * @example
+ * ```ts
+ * import Madrone from '@madronejs/core';
+ * import { MadroneVue } from '@madronejs/core';
+ *
+ * // Simple one-liner setup
+ * Madrone.use(MadroneVue);
+ *
+ * // Create reactive state that works with Vue components
+ * const store = auto({
+ *   count: 0,
+ *   get doubled() { return this.count * 2; }
+ * });
+ * ```
+ */
+declare const MadroneVue: import("..").Integration;
+export default MadroneVue;
+//# sourceMappingURL=vue.d.ts.map