@madronejs/core 1.0.18 → 1.1.0

package/types/reactivity/interfaces.d.ts

@@ -1,28 +1,70 @@
-export type TypeHandlerOptions<T extends object = any> = {
+/**
+ * @module reactivity/interfaces
+ *
+ * Type definitions for the low-level reactivity system.
+ */
+/**
+ * Options passed to type handler hooks when reactive operations occur.
+ *
+ * @typeParam T - The type of the reactive target
+ */
+export type TypeHandlerOptions<T extends object = object> = {
+    /** Name for debugging */
     name?: string;
+    /** Whether deep reactivity is enabled */
     deep?: boolean;
-    receiver?: any;
+    /** The Proxy receiver */
+    receiver?: T;
+    /** The raw target object */
     target?: T;
-    key?: keyof T;
-    value?: T[keyof T];
+    /** The property key being accessed/modified */
+    key?: PropertyKey;
+    /** The value being set */
+    value?: unknown;
+    /** Whether the operation changed the object's keys */
     keysChanged?: boolean;
+    /** Whether the operation changed a value */
     valueChanged?: boolean;
 };
-export type HandlerHookType<T extends object = any> = (options: TypeHandlerOptions<T>) => void;
-export type CheckProxyHookType<T extends object = any> = (options: {
+/**
+ * Hook function called on reactive operations.
+ * @typeParam T - The type of the reactive target
+ */
+export type HandlerHookType<T extends object = object> = (options: TypeHandlerOptions<T>) => void;
+/**
+ * Hook function that determines if a value should be wrapped in a Proxy.
+ * @typeParam T - The type of the reactive target
+ */
+export type CheckProxyHookType<T extends object = object> = (options: {
     target: T;
-    key: keyof T;
-    value: T[keyof T];
+    key: PropertyKey;
+    value: unknown;
 }) => boolean;
-export type ReactiveHandlerHooks<T extends object = any> = {
+/**
+ * Collection of hooks for reactive Proxy handlers.
+ * @typeParam T - The type of the reactive target
+ */
+export type ReactiveHandlerHooks<T extends object = object> = {
+    /** Called when a property is read */
     onGet: HandlerHookType<T>;
+    /** Called when a property is set */
     onSet: HandlerHookType<T>;
+    /** Called when a property is deleted */
     onDelete: HandlerHookType<T>;
+    /** Called when `in` operator or `has` trap is triggered */
     onHas: HandlerHookType<T>;
+    /** Determines if a value should be wrapped in a reactive Proxy */
     needsProxy: CheckProxyHookType<T>;
 };
-export type ReactiveOptions<T extends object = any> = {
-    name?: any;
+/**
+ * Configuration options for creating reactive Proxies.
+ *
+ * @typeParam T - The type of the object being made reactive
+ */
+export type ReactiveOptions<T extends object = object> = {
+    /** Name for debugging purposes */
+    name?: string;
+    /** Whether to recursively make nested objects reactive (default: true) */
     deep?: boolean;
 } & Partial<ReactiveHandlerHooks<T>>;
 //# sourceMappingURL=interfaces.d.ts.map

package/types/reactivity/typeHandlers.d.ts

@@ -1,7 +1,8 @@
+import { ReactiveOptions } from './interfaces';
 declare const _default: Readonly<{
     object: (options: any) => {
         get: (target: any, prop: any, receiver: any) => any;
-        set: (target: object, propertyKey: PropertyKey, value: any) => boolean;
+        set: (target: object, propertyKey: PropertyKey, value: unknown) => boolean;
         deleteProperty: (target: object, propertyKey: PropertyKey) => boolean;
         has: (target: any, key: any) => boolean;
         ownKeys: (target: any) => (string | symbol)[];
@@ -9,12 +10,18 @@ declare const _default: Readonly<{
     };
     array: (options: any) => {
         get: (target: any, prop: any, receiver: any) => any;
-        set: (target: object, propertyKey: PropertyKey, value: any) => boolean;
+        set: (target: object, propertyKey: PropertyKey, value: unknown) => boolean;
         deleteProperty: (target: object, propertyKey: PropertyKey) => boolean;
         has: (target: any, key: any) => boolean;
         ownKeys: (target: any) => (string | symbol)[];
         getPrototypeOf: (target: any) => any;
     };
+    set: (options: ReactiveOptions) => {
+        get: (target: Set<unknown>, key: PropertyKey, receiver: object) => any;
+    };
+    map: (options: ReactiveOptions) => {
+        get: (target: Map<unknown, unknown>, key: PropertyKey, receiver: object) => any;
+    };
 }>;
 export default _default;
 //# sourceMappingURL=typeHandlers.d.ts.map

package/types/util.d.ts

@@ -1,5 +1,13 @@
+/**
+ * @module util
+ *
+ * Utility functions for object composition and class mixins.
+ *
+ * These utilities support Madrone's composition-based architecture,
+ * allowing you to build complex objects from simpler pieces.
+ */
 type OptionalPropertyNames<T> = {
-    [K in keyof T]-?: any extends {
+    [K in keyof T]-?: object extends {
         [P in K]: T[K];
     } ? K : never;
 }[keyof T];
@@ -9,24 +17,110 @@ type SpreadProperties<L, R, K extends keyof L & keyof R> = {
 type Id<T> = T extends infer U ? {
     [K in keyof U]: U[K];
 } : never;
+/**
+ * Type utility that merges two object types, with right-hand properties
+ * taking precedence over left-hand properties.
+ *
+ * @typeParam L - The left (base) type
+ * @typeParam R - The right (override) type
+ */
 export type SpreadTwo<L, R> = Id<Pick<L, Exclude<keyof L, keyof R>> & Pick<R, Exclude<keyof R, OptionalPropertyNames<R>>> & Pick<R, Exclude<OptionalPropertyNames<R>, keyof L>> & SpreadProperties<L, R, OptionalPropertyNames<R> & keyof L>>;
-export type Spread<A extends readonly [...any]> = A extends [infer L, ...infer R] ? SpreadTwo<L extends (...any: any[]) => any ? ReturnType<L> : L, Spread<R>> : unknown;
+type ObjectOrFactory = object | ((...args: unknown[]) => object);
 /**
- * Merge multiple object definitions into a single new object definition
- * @param types
- * @returns The new object definition
+ * Type utility that recursively merges an array of object types.
+ *
+ * Handles both plain objects and factory functions (whose return
+ * types are extracted and merged).
+ *
+ * @typeParam A - A tuple of object or factory types
  */
-export declare function merge<A extends (object | ((...any: any[]) => any))[]>(...types: [...A]): Spread<A>;
+export type Spread<A extends readonly unknown[]> = A extends [infer L, ...infer R] ? SpreadTwo<L extends (...args: unknown[]) => infer RT ? RT : L, Spread<R>> : unknown;
 /**
- * Extend the prototype of a base class with the prototypes of other classes. Mutates the base class.
- * @param base Base class that the mixins will be mixed into. Any naming conflicts will prefer this base class.
- * @param constructors List of mixin classes that will be applied to the base class.
+ * Merges multiple objects or factory functions into a single new object.
+ *
+ * Properties from later arguments override those from earlier ones.
+ * Factory functions are called and their return values are merged.
+ * All property descriptors (getters, setters, etc.) are preserved.
+ *
+ * @typeParam A - The types of objects/factories being merged
+ * @param types - Objects or factory functions to merge
+ * @returns A new object with all properties from all inputs
+ *
+ * @example
+ * ```ts
+ * import { merge } from '@madronejs/core';
+ *
+ * const base = { name: 'base', value: 1 };
+ * const override = { value: 2, extra: true };
+ *
+ * const merged = merge(base, override);
+ * // { name: 'base', value: 2, extra: true }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With factory functions
+ * const createTimestamp = () => ({ createdAt: Date.now() });
+ * const data = { name: 'item' };
+ *
+ * const result = merge(createTimestamp, data);
+ * // { createdAt: 1702345678901, name: 'item' }
+ * ```
  */
-export declare function applyClassMixins(base: any, mixins: [...any]): void;
-export declare function getDefaultDescriptors(obj: any, defaults?: any): {
-    [x: string]: TypedPropertyDescriptor<any>;
-} & {
-    [x: string]: PropertyDescriptor;
-};
+export declare function merge<A extends ObjectOrFactory[]>(...types: [...A]): Spread<A>;
+type Constructor = new (...args: unknown[]) => object;
+/**
+ * Applies mixin classes to a base class by merging their prototypes.
+ *
+ * This function mutates the base class, copying all prototype properties
+ * from the mixin classes onto the base class prototype. Properties from
+ * the base class take precedence over mixin properties in case of conflicts.
+ *
+ * @param base - The base class to extend (will be mutated)
+ * @param mixins - Array of mixin classes whose prototypes will be merged in
+ *
+ * @example
+ * ```ts
+ * import { applyClassMixins } from '@madronejs/core';
+ *
+ * class Timestamped {
+ *   createdAt = Date.now();
+ *   getAge() {
+ *     return Date.now() - this.createdAt;
+ *   }
+ * }
+ *
+ * class Serializable {
+ *   toJSON() {
+ *     return JSON.stringify(this);
+ *   }
+ * }
+ *
+ * class Model {
+ *   id: string;
+ * }
+ *
+ * // Add Timestamped and Serializable methods to Model
+ * applyClassMixins(Model, [Timestamped, Serializable]);
+ *
+ * const model = new Model();
+ * model.toJSON(); // Works!
+ * model.getAge(); // Works!
+ * ```
+ */
+export declare function applyClassMixins(base: Constructor, mixins: Constructor[]): void;
+/**
+ * Creates a property descriptor map with default descriptor settings.
+ *
+ * Takes an object and returns its property descriptors with specified
+ * defaults applied. Useful for copying properties with consistent settings.
+ *
+ * @param obj - The source object
+ * @param defaults - Default descriptor values to apply
+ * @returns Property descriptor map with defaults applied
+ *
+ * @internal
+ */
+export declare function getDefaultDescriptors(obj: object, defaults?: Partial<PropertyDescriptor>): PropertyDescriptorMap;
 export {};
 //# sourceMappingURL=util.d.ts.map

package/types/__spec__/decorateComputed.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=decorateComputed.spec.d.ts.map

package/types/__spec__/decorateReactive.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=decorateReactive.spec.d.ts.map

package/types/__spec__/examples.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=examples.spec.d.ts.map

package/types/__spec__/merge.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=merge.spec.d.ts.map

package/types/integrations/__spec__/madroneState.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=madroneState.spec.d.ts.map

package/types/integrations/__spec__/testAccess.d.ts

@@ -1,2 +0,0 @@
-export default function testClass(integrationName: any, integration: any): void;
-//# sourceMappingURL=testAccess.d.ts.map

package/types/integrations/__spec__/testAll.d.ts

@@ -1,4 +0,0 @@
-export default function testAll(name: string, integration: any, options?: {
-    blacklist?: Array<string>;
-}): void;
-//# sourceMappingURL=testAll.d.ts.map

package/types/integrations/__spec__/testAuto.d.ts

@@ -1,2 +0,0 @@
-export default function testAuto(name: any, integration: any): void;
-//# sourceMappingURL=testAuto.d.ts.map

package/types/integrations/__spec__/testClass.d.ts

@@ -1,2 +0,0 @@
-export default function testClass(name: any, integration: any): void;
-//# sourceMappingURL=testClass.d.ts.map

package/types/integrations/__spec__/testVue.d.ts

@@ -1,2 +0,0 @@
-export default function testVue(name: any, integration: any, options: any): void;
-//# sourceMappingURL=testVue.d.ts.map

package/types/integrations/__spec__/vue3.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=vue3.spec.d.ts.map

package/types/reactivity/__spec__/observer.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=observer.spec.d.ts.map

package/types/reactivity/__spec__/observer_array.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=observer_array.spec.d.ts.map

package/types/reactivity/__spec__/observer_object.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=observer_object.spec.d.ts.map

package/types/reactivity/__spec__/observer_set.xspec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=observer_set.xspec.d.ts.map

package/types/reactivity/__spec__/reactive.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=reactive.spec.d.ts.map

package/types/reactivity/__spec__/reactive_array.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=reactive_array.spec.d.ts.map

package/types/reactivity/__spec__/reactive_object.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=reactive_object.spec.d.ts.map

package/types/reactivity/__spec__/reactive_set.xspec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=reactive_set.xspec.d.ts.map

package/types/reactivity/__spec__/watcher.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=watcher.spec.d.ts.map