effectable 0.1.0

package/build/component/lifecycle.js

@@ -0,0 +1,367 @@
+"use strict";
+/**
+ * Node lifecycle engine (`LifecycleEngine`) and transition result type.
+ *
+ * The state machine defines stage order: `registered` → `resolved` → `created` →
+ * `mounted` → `ready` → `unmounting` → `unmounted` → `destroyed`.
+ * Any stage may transition to `failed`; there is no reverse transition from `failed`
+ * (except forced `destroy` via teardown scenarios).
+ *
+ * Public component hooks are called in the expected order:
+ * - startup: `onMount`
+ * - in stage `ready`: `onUpdate` (as decided by GraphRuntime)
+ * - shutdown / cleanup: `onUnmount`
+ *
+ * @module Effectable/component/lifecycle
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleEngine = void 0;
+/**
+ * Numeric lifecycle stage codes for O(1) comparisons.
+ *
+ * Used instead of repeated lookups by string stage-order keys.
+ * Object constant instead of `const enum` — compatibility with `isolatedModules`.
+ *
+ * Keys: Registered … Failed; values — monotonically increasing numbers for stage comparison.
+ */
+const STAGE = {
+    Registered: 0,
+    Resolved: 1,
+    Created: 2,
+    Mounted: 3,
+    Ready: 4,
+    Unmounting: 5,
+    Unmounted: 6,
+    Destroyed: 7,
+    Failed: 8,
+};
+/**
+ * Array index = numeric stage code; value = string `NodeLifecycleStatus`.
+ * Used by {@link LifecycleEngine.getStatus}.
+ */
+const STAGE_TO_STATUS = [
+    'registered', // 0
+    'resolved', // 1
+    'created', // 2
+    'mounted', // 3
+    'ready', // 4
+    'unmounting', // 5
+    'unmounted', // 6
+    'destroyed', // 7
+    'failed', // 8
+];
+/**
+ * Mapping from string target stage (`ForwardStage`) to numeric code for comparison
+ * with `currentStage` in {@link LifecycleEngine.canTransitionTo}.
+ */
+const STAGE_FROM_FORWARD = {
+    resolved: STAGE.Resolved,
+    created: STAGE.Created,
+    mounted: STAGE.Mounted,
+    ready: STAGE.Ready,
+    unmounting: STAGE.Unmounting,
+    unmounted: STAGE.Unmounted,
+    destroyed: STAGE.Destroyed,
+    failed: STAGE.Failed,
+};
+/**
+ * Bits indicating presence of the corresponding hook methods on the component instance.
+ *
+ * Filled in {@link LifecycleEngine.initHookFlags}; when `hookFlags === 0`
+ * startup/shutdown can finish without `typeof` checks on each hook.
+ */
+const HookBit = {
+    Mount: 1 << 0,
+    Update: 1 << 1,
+    Unmount: 1 << 2,
+};
+/**
+ * Checks whether a value is thenable (Promise-like).
+ * Used for the sync fast-path of hooks (3.55x speedup):
+ * if the hook returned a non-Promise — skip await and the related microtask hop.
+ *
+ * @param {unknown} value - hook return value
+ * @returns {boolean} true if the value is Promise-like
+ */
+function isThenable(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.then === 'function');
+}
+/**
+ * Lifecycle state machine for one node in GraphRuntime: one instance
+ * per node (fiber).
+ *
+ * Invariants:
+ * - stages mostly advance monotonically; update passes are allowed in `ready`;
+ * - after `failed`, further transitions are limited (see {@link canTransitionTo});
+ * - {@link Component.onUnmount} is called at most once per instance.
+ *
+ * @example
+ * const engine = new LifecycleEngine();
+ * engine.initHookFlags(component);
+ * await engine.runStartup(component);
+ */
+class LifecycleEngine {
+    /**
+     * Current stage as a number (see {@link STAGE}): comparisons without string lookups.
+     */
+    currentStage = STAGE.Registered;
+    unmountCalled = false;
+    /**
+     * Bit flags for which hooks the component has.
+     * 0 — hooks not initialized or absent (fast-exit in runStartup/runShutdown).
+     * Set via initHookFlags() after instance creation.
+     */
+    hookFlags = 0;
+    /**
+     * Whether hookFlags were initialized via initHookFlags().
+     * Without this, the fast-exit on hookFlags === 0 would apply before initialization.
+     */
+    hookFlagsInitialized = false;
+    /**
+     * Returns the string node status for the external API (GraphRuntime, debugging, UI).
+     *
+     * @returns {NodeLifecycleStatus} current stage as `NodeLifecycleStatus`
+     */
+    getStatus() {
+        return STAGE_TO_STATUS[this.currentStage];
+    }
+    /**
+     * Computes and stores a bit mask of hook methods present on the instance.
+     * Must be called exactly once after instance creation (e.g. from materialize).
+     * Lets {@link runStartup} and {@link runShutdown} skip per-hook checks
+     * when none are declared.
+     *
+     * @param {Component<unknown, unknown>} instance - component instance with optional hooks
+     * @returns {void}
+     */
+    initHookFlags(instance) {
+        this.hookFlags =
+            (typeof instance.onMount === 'function' ? HookBit.Mount : 0) |
+                (typeof instance.onUpdate === 'function' ? HookBit.Update : 0) |
+                (typeof instance.onUnmount === 'function' ? HookBit.Unmount : 0);
+        this.hookFlagsInitialized = true;
+    }
+    /**
+     * Startup phase: if present — call `onMount`, advance stages to `ready`.
+     * On exception: stage already `Mounted` → {@link runFailedCleanup}(`wasMounted=true`)
+     * (attempt `onUnmount` + teardown), result `{ ok: false, error }`.
+     *
+     * Returns a synchronous {@link LifecycleTransitionResult} if `onMount` returned
+     * a non-thenable value (sync fast-path); otherwise a Promise.
+     * `await` works correctly with either union branch.
+     *
+     * @param {Component<unknown, unknown>} instance - component instance
+     * @returns {LifecycleTransitionResult | Promise<LifecycleTransitionResult>}
+     */
+    runStartup(instance) {
+        this.currentStage = STAGE.Resolved;
+        this.currentStage = STAGE.Created;
+        // Fast-exit for pure components without startup hooks (1.15x)
+        if (this.hookFlagsInitialized && this.hookFlags === 0) {
+            this.currentStage = STAGE.Mounted;
+            this.currentStage = STAGE.Ready;
+            return { ok: true };
+        }
+        try {
+            this.currentStage = STAGE.Mounted;
+            if (typeof instance.onMount === 'function') {
+                const r = instance.onMount();
+                if (isThenable(r)) {
+                    return this.continueStartupAsync(instance, r);
+                }
+            }
+            this.currentStage = STAGE.Ready;
+            return { ok: true };
+        }
+        catch (error) {
+            // Stage is already Mounted before onMount — cleanup must attempt onUnmount.
+            const cleanupResult = this.runFailedCleanup(instance, true);
+            if (isThenable(cleanupResult)) {
+                return cleanupResult.then(() => ({ ok: false, error }));
+            }
+            return { ok: false, error };
+        }
+    }
+    /**
+     * Async continuation of {@link runStartup} after `onMount` returned a Promise.
+     *
+     * @param {Component<unknown, unknown>} instance - component instance
+     * @param {PromiseLike<unknown>} pending - Promise from onMount
+     * @returns {Promise<LifecycleTransitionResult>}
+     */
+    async continueStartupAsync(instance, pending) {
+        try {
+            await pending;
+            this.currentStage = STAGE.Ready;
+            return { ok: true };
+        }
+        catch (error) {
+            const cleanupResult = this.runFailedCleanup(instance, true);
+            if (isThenable(cleanupResult)) {
+                await cleanupResult;
+            }
+            return { ok: false, error };
+        }
+    }
+    /**
+     * Shutdown phase: if needed `onUnmount`, stages `unmounting` → `unmounted` → `destroyed`.
+     * If the node is already `destroyed`, noop. An error in `onUnmount` is returned as `{ ok: false, error }`.
+     *
+     * Returns a synchronous {@link LifecycleTransitionResult} if `onUnmount` returned non-thenable
+     * (sync fast-path); otherwise a Promise. `await` works correctly
+     * with either union branch.
+     *
+     * @param {Component<unknown, unknown>} instance - component instance
+     * @returns {LifecycleTransitionResult | Promise<LifecycleTransitionResult>}
+     */
+    runShutdown(instance) {
+        if (this.currentStage === STAGE.Destroyed) {
+            return { ok: true };
+        }
+        // Numeric comparisons instead of 4 STAGE_ORDER string lookups (1.10x)
+        const wasReady = this.currentStage >= STAGE.Mounted &&
+            this.currentStage <= STAGE.Ready;
+        this.currentStage = STAGE.Unmounting;
+        let unmountError = null;
+        if (wasReady && !this.unmountCalled && typeof instance.onUnmount === 'function') {
+            this.unmountCalled = true;
+            try {
+                const r = instance.onUnmount();
+                if (isThenable(r)) {
+                    return this.continueShutdownAsync(r);
+                }
+            }
+            catch (error) {
+                unmountError = error;
+            }
+        }
+        this.currentStage = STAGE.Unmounted;
+        this.currentStage = STAGE.Destroyed;
+        if (unmountError !== null) {
+            return { ok: false, error: unmountError };
+        }
+        return { ok: true };
+    }
+    /**
+     * Async continuation of {@link runShutdown} after `onUnmount` returned a Promise.
+     *
+     * @param {PromiseLike<unknown>} pendingUnmount - Promise from onUnmount
+     * @returns {Promise<LifecycleTransitionResult>}
+     */
+    async continueShutdownAsync(pendingUnmount) {
+        let unmountError = null;
+        try {
+            await pendingUnmount;
+        }
+        catch (error) {
+            unmountError = error;
+        }
+        this.currentStage = STAGE.Unmounted;
+        this.currentStage = STAGE.Destroyed;
+        if (unmountError !== null) {
+            return { ok: false, error: unmountError };
+        }
+        return { ok: true };
+    }
+    /**
+     * Forced cleanup after failure: stage `failed`, if `wasMounted` — attempt
+     * `onUnmount` (errors swallowed), then final teardown.
+     * Used on `onMount` fail (stage already `Mounted`) and by GraphRuntime on errors
+     * outside startup (e.g. during update).
+     *
+     * Returns `void` synchronously if `onUnmount` is absent or returned non-thenable;
+     * otherwise a Promise.
+     *
+     * @param {Component<unknown, unknown>} instance - component instance
+     * @param {boolean} wasMounted - `true` if the node had already mounted before the error
+     * @returns {void | Promise<void>}
+     */
+    runFailedCleanup(instance, wasMounted) {
+        this.currentStage = STAGE.Failed;
+        if (wasMounted && !this.unmountCalled && typeof instance.onUnmount === 'function') {
+            this.unmountCalled = true;
+            try {
+                const r = instance.onUnmount();
+                if (isThenable(r)) {
+                    return this.continueFailedCleanupAsync(r);
+                }
+            }
+            catch {
+                // Continue teardown even if onUnmount fails
+            }
+        }
+        return this.runForcedDestroy();
+    }
+    /**
+     * Async continuation of {@link runFailedCleanup} after async unmount.
+     *
+     * @param {PromiseLike<unknown>} pendingUnmount - Promise from onUnmount
+     * @returns {Promise<void>}
+     */
+    async continueFailedCleanupAsync(pendingUnmount) {
+        try {
+            await pendingUnmount;
+        }
+        catch {
+            // Continue teardown even if onUnmount fails
+        }
+        const destroyResult = this.runForcedDestroy();
+        if (isThenable(destroyResult)) {
+            await destroyResult;
+        }
+    }
+    /**
+     * Idempotent teardown: marks the node as `destroyed`. No `onDestroy` call
+     * (legacy hook removed); side-effect cleanup happens in `onUnmount`.
+     *
+     * @returns {void | Promise<void>} always `void` (signature kept for compatibility)
+     */
+    runForcedDestroy() {
+        this.currentStage = STAGE.Destroyed;
+    }
+    /**
+     * Whether the node can accept an update pass (`onUpdate`): only stage `ready`.
+     *
+     * @returns {boolean} `true` if an update-pass may be called
+     */
+    canUpdate() {
+        return this.currentStage === STAGE.Ready;
+    }
+    /**
+     * Whether the node is in a terminal stage: `destroyed` or `failed` (further work with the node is not expected).
+     *
+     * @returns {boolean} `true` for `destroyed` and `failed`
+     */
+    isTerminated() {
+        return (this.currentStage === STAGE.Destroyed || this.currentStage === STAGE.Failed);
+    }
+    /**
+     * Moves the node to `failed` without calling hooks (external error, marking in GraphRuntime).
+     * If the node is already terminal, state is unchanged.
+     *
+     * @returns {void}
+     */
+    markFailed() {
+        if (!this.isTerminated()) {
+            this.currentStage = STAGE.Failed;
+        }
+    }
+    /**
+     * Whether a “forward” transition to `target` is allowed relative to the current numeric stage.
+     * From `failed` only a transition to `destroyed` is allowed (aligned with forced teardown).
+     *
+     * @param {ForwardStage} target - target stage under test by string name
+     * @returns {boolean} `true` if the target stage is strictly “later” than current (or special case `failed`→`destroyed`)
+     */
+    canTransitionTo(target) {
+        if (this.currentStage === STAGE.Failed) {
+            return target === 'destroyed';
+        }
+        // Numeric comparison instead of two STAGE_ORDER string lookups (1.11x)
+        return STAGE_FROM_FORWARD[target] > this.currentStage;
+    }
+}
+exports.LifecycleEngine = LifecycleEngine;
+//# sourceMappingURL=lifecycle.js.map

package/build/component/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/component/lifecycle.ts"],"names":[],"mappings":"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"}

package/build/component/refs.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Ref machinery for declarative component composition in GraphRuntime.
+ *
+ * - {@link UseRef} — property decorator: lazily creates a `RefObject` and registers the field for runtime binding.
+ * - {@link UseImperativeHandle} — method decorator: marks a method as part of the child node's public imperative API.
+ *
+ * **Ref usage rules**
+ *
+ * - Ref is a controlled escape hatch; do not use it as a service locator.
+ * - Only for a narrow imperative API (e.g. reset, focus, flush).
+ * - Does not replace DI, CommandBus, or context.
+ * - After the node unmounts, GraphRuntime clears `ref.current`.
+ *
+ * @module Effectable/component/refs
+ */
+/**
+ * Metadata symbol key: list of class fields marked with {@link UseRef}.
+ *
+ * Filled by the decorator on the constructor; read by {@link getRefFields} and GraphRuntime on mount
+ * to match the field with the node passed via `h(..., ref)`.
+ */
+export declare const REF_FIELDS_META_KEY: unique symbol;
+/**
+ * Metadata symbol key: list of methods marked with {@link UseImperativeHandle}.
+ *
+ * GraphRuntime builds a limited public handle (imperative API) from them without exposing other class methods.
+ */
+export declare const IMPERATIVE_HANDLE_META_KEY: unique symbol;
+/**
+ * Record for a field registered by the {@link UseRef} decorator.
+ *
+ * Used by the runtime to bind a child component instance to the parent's ref.
+ */
+export interface RefFieldMeta {
+    /** Property key on the component instance (`string` or `symbol`). */
+    propertyKey: string | symbol;
+}
+/**
+ * Record for a method registered by the {@link UseImperativeHandle} decorator.
+ *
+ * Participates in building the public imperative API of the child node's ref.
+ */
+export interface ImperativeHandleMeta {
+    /** Method key on the component instance (`string` or `symbol`). */
+    methodKey: string | symbol;
+}
+/**
+ * Component class property decorator: lazily creates a `RefObject` and registers the field in {@link REF_FIELDS_META_KEY}.
+ *
+ * On first getter access, one `RefObject` is created per instance; the same ref is passed to `h(Child, {}, this.childRef)`.
+ * GraphRuntime fills `current` when the child node mounts.
+ *
+ * @returns {PropertyDecorator} property decorator: getter returns a stable `RefObject` for the child node
+ * @example
+ * class Parent extends Component {
+ *   @UseRef()
+ *   private declare childRef: RefObject<Child>;
+ *
+ *   compose() {
+ *     return h(Child, {}, this.childRef);
+ *   }
+ * }
+ */
+export declare function UseRef(): PropertyDecorator;
+/**
+ * Component class method decorator: adds the method to the {@link IMPERATIVE_HANDLE_META_KEY} list.
+ *
+ * GraphRuntime builds the public imperative handle only from such methods; other class methods
+ * are not reachable via ref. The method itself is not overridden — only registered as metadata on the constructor.
+ *
+ * @returns {MethodDecorator} method decorator that leaves `descriptor` unchanged (side effect only — write meta)
+ * @example
+ * class Child extends Component {
+ *   @UseImperativeHandle()
+ *   public async reset(): Promise<void> {
+ *     // ...
+ *   }
+ * }
+ */
+export declare function UseImperativeHandle(): MethodDecorator;
+/**
+ * Returns the array of fields registered by {@link UseRef} on the given component constructor.
+ *
+ * If meta is absent, returns a new empty array. If meta is present, returns the same array stored
+ * on the constructor (external mutations affect the metadata).
+ *
+ * @param {object} componentClass - component constructor: object with optional {@link REF_FIELDS_META_KEY}
+ * @returns {RefFieldMeta[]} ref field records; order matches decorator application order
+ */
+export declare function getRefFields(componentClass: {
+    [REF_FIELDS_META_KEY]?: RefFieldMeta[];
+}): RefFieldMeta[];
+/**
+ * Returns the array of methods registered by {@link UseImperativeHandle} on the given constructor.
+ *
+ * If meta is absent, returns a new empty array. If meta is present, returns the same array stored
+ * on the constructor (external mutations affect the metadata).
+ *
+ * @param {object} componentClass - component constructor: object with optional {@link IMPERATIVE_HANDLE_META_KEY}
+ * @returns {ImperativeHandleMeta[]} imperative API method records; order matches decorator application order
+ */
+export declare function getImperativeHandleMethods(componentClass: {
+    [IMPERATIVE_HANDLE_META_KEY]?: ImperativeHandleMeta[];
+}): ImperativeHandleMeta[];
+//# sourceMappingURL=refs.d.ts.map

package/build/component/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/component/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,eAAkC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,eAAyC,CAAC;AAEjF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,IAAK,iBAAiB,CA+B3C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,IAAK,eAAe,CAoBtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,cAAc,EAAE;IAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,GACzD,YAAY,EAAE,CAEhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE;IAAE,CAAC,0BAA0B,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAA;CAAE,GACxE,oBAAoB,EAAE,CAExB"}

package/build/component/refs.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Ref machinery for declarative component composition in GraphRuntime.
+ *
+ * - {@link UseRef} — property decorator: lazily creates a `RefObject` and registers the field for runtime binding.
+ * - {@link UseImperativeHandle} — method decorator: marks a method as part of the child node's public imperative API.
+ *
+ * **Ref usage rules**
+ *
+ * - Ref is a controlled escape hatch; do not use it as a service locator.
+ * - Only for a narrow imperative API (e.g. reset, focus, flush).
+ * - Does not replace DI, CommandBus, or context.
+ * - After the node unmounts, GraphRuntime clears `ref.current`.
+ *
+ * @module Effectable/component/refs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPERATIVE_HANDLE_META_KEY = exports.REF_FIELDS_META_KEY = void 0;
+exports.UseRef = UseRef;
+exports.UseImperativeHandle = UseImperativeHandle;
+exports.getRefFields = getRefFields;
+exports.getImperativeHandleMethods = getImperativeHandleMethods;
+/**
+ * Metadata symbol key: list of class fields marked with {@link UseRef}.
+ *
+ * Filled by the decorator on the constructor; read by {@link getRefFields} and GraphRuntime on mount
+ * to match the field with the node passed via `h(..., ref)`.
+ */
+exports.REF_FIELDS_META_KEY = Symbol('effectable:ref_fields');
+/**
+ * Metadata symbol key: list of methods marked with {@link UseImperativeHandle}.
+ *
+ * GraphRuntime builds a limited public handle (imperative API) from them without exposing other class methods.
+ */
+exports.IMPERATIVE_HANDLE_META_KEY = Symbol('effectable:imperative_handle');
+/**
+ * Component class property decorator: lazily creates a `RefObject` and registers the field in {@link REF_FIELDS_META_KEY}.
+ *
+ * On first getter access, one `RefObject` is created per instance; the same ref is passed to `h(Child, {}, this.childRef)`.
+ * GraphRuntime fills `current` when the child node mounts.
+ *
+ * @returns {PropertyDecorator} property decorator: getter returns a stable `RefObject` for the child node
+ * @example
+ * class Parent extends Component {
+ *   @UseRef()
+ *   private declare childRef: RefObject<Child>;
+ *
+ *   compose() {
+ *     return h(Child, {}, this.childRef);
+ *   }
+ * }
+ */
+function UseRef() {
+    return function (target, propertyKey) {
+        const constructor = target.constructor;
+        if (!Array.isArray(constructor[exports.REF_FIELDS_META_KEY])) {
+            constructor[exports.REF_FIELDS_META_KEY] = [];
+        }
+        const existing = constructor[exports.REF_FIELDS_META_KEY];
+        if (existing !== undefined) {
+            existing.push({ propertyKey });
+        }
+        // Pre-compute storage key once in closure (30.9x speedup vs string concat per getter call)
+        const refKey = `__ref_${String(propertyKey)}`;
+        Object.defineProperty(target, propertyKey, {
+            get() {
+                if (this[refKey] === undefined) {
+                    this[refKey] = { current: null };
+                }
+                return this[refKey];
+            },
+            enumerable: true,
+            configurable: true,
+        });
+    };
+}
+/**
+ * Component class method decorator: adds the method to the {@link IMPERATIVE_HANDLE_META_KEY} list.
+ *
+ * GraphRuntime builds the public imperative handle only from such methods; other class methods
+ * are not reachable via ref. The method itself is not overridden — only registered as metadata on the constructor.
+ *
+ * @returns {MethodDecorator} method decorator that leaves `descriptor` unchanged (side effect only — write meta)
+ * @example
+ * class Child extends Component {
+ *   @UseImperativeHandle()
+ *   public async reset(): Promise<void> {
+ *     // ...
+ *   }
+ * }
+ */
+function UseImperativeHandle() {
+    return function (target, methodKey, _descriptor) {
+        const constructor = target.constructor;
+        if (!Array.isArray(constructor[exports.IMPERATIVE_HANDLE_META_KEY])) {
+            constructor[exports.IMPERATIVE_HANDLE_META_KEY] = [];
+        }
+        const existing = constructor[exports.IMPERATIVE_HANDLE_META_KEY];
+        if (existing !== undefined) {
+            existing.push({ methodKey });
+        }
+    };
+}
+/**
+ * Returns the array of fields registered by {@link UseRef} on the given component constructor.
+ *
+ * If meta is absent, returns a new empty array. If meta is present, returns the same array stored
+ * on the constructor (external mutations affect the metadata).
+ *
+ * @param {object} componentClass - component constructor: object with optional {@link REF_FIELDS_META_KEY}
+ * @returns {RefFieldMeta[]} ref field records; order matches decorator application order
+ */
+function getRefFields(componentClass) {
+    return componentClass[exports.REF_FIELDS_META_KEY] ?? [];
+}
+/**
+ * Returns the array of methods registered by {@link UseImperativeHandle} on the given constructor.
+ *
+ * If meta is absent, returns a new empty array. If meta is present, returns the same array stored
+ * on the constructor (external mutations affect the metadata).
+ *
+ * @param {object} componentClass - component constructor: object with optional {@link IMPERATIVE_HANDLE_META_KEY}
+ * @returns {ImperativeHandleMeta[]} imperative API method records; order matches decorator application order
+ */
+function getImperativeHandleMethods(componentClass) {
+    return componentClass[exports.IMPERATIVE_HANDLE_META_KEY] ?? [];
+}
+//# sourceMappingURL=refs.js.map

package/build/component/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/component/refs.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAwDH,wBA+BC;AAiBD,kDAoBC;AAWD,oCAIC;AAWD,gEAIC;AAtJD;;;;;GAKG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAEnE;;;;GAIG;AACU,QAAA,0BAA0B,GAAG,MAAM,CAAC,8BAA8B,CAAC,CAAC;AAsBjF;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,MAAM;IACpB,OAAO,UAAU,MAAc,EAAE,WAA4B;QAC3D,MAAM,WAAW,GAAG,MAAM,CAAC,WAE1B,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,2BAAmB,CAAC,CAAC,EAAE,CAAC;YACrD,WAAW,CAAC,2BAAmB,CAAC,GAAG,EAAE,CAAC;QACxC,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,CAAC,2BAAmB,CAAC,CAAC;QAElD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QACjC,CAAC;QAED,2FAA2F;QAC3F,MAAM,MAAM,GAAG,SAAS,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAE9C,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE;YACzC,GAAG;gBACD,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;oBAC/B,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAwB,CAAC;gBACzD,CAAC;gBAED,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;YACD,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,mBAAmB;IACjC,OAAO,UACL,MAAc,EACd,SAA0B,EAC1B,WAA+B;QAE/B,MAAM,WAAW,GAAG,MAAM,CAAC,WAE1B,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,kCAA0B,CAAC,CAAC,EAAE,CAAC;YAC5D,WAAW,CAAC,kCAA0B,CAAC,GAAG,EAAE,CAAC;QAC/C,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,CAAC,kCAA0B,CAAC,CAAC;QAEzD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,YAAY,CAC1B,cAA0D;IAE1D,OAAO,cAAc,CAAC,2BAAmB,CAAC,IAAI,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,0BAA0B,CACxC,cAAyE;IAEzE,OAAO,cAAc,CAAC,kCAA0B,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC"}