effectable 0.1.0

package/build/component/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Lifecycle and Disposable types for Effectable/component.
+ * Lifecycle contract and Explicit Resource Management (TS 5.2+, Symbol.dispose).
+ * Also includes VirtualServiceNode, Fiber, and NodeLifecycleStatus types for declarative component trees.
+ *
+ * @module Effectable/component/types
+ */
+import type { Component } from './Component';
+/**
+ * Lifecycle interface for a GraphRuntime / connect-HOC component instance.
+ * Methods are called in order: onMount -> onUpdate* -> onUnmount.
+ */
+export interface Lifecycle {
+    /** Mount: start subscriptions, timers, and background work. */
+    onMount?(): void | Promise<void>;
+    /** On every state/props update (prev/next). */
+    onUpdate?(prev: unknown, next: unknown): void | Promise<void>;
+    /** Unmount: drop subscriptions and stop side effects. */
+    onUnmount?(): void | Promise<void>;
+}
+/**
+ * Internal runtime hook for components that need custom application of incoming `props`
+ * during reconcile instead of a direct `instance.props = nextProps`.
+ *
+ * Used by `connect`-HOC to update props and rebuild merged props
+ * (`props + dispatch props + state props`) without losing previously computed values.
+ */
+export declare const RUNTIME_PROPS_RECEIVER: unique symbol;
+/**
+ * Hidden scheduler hook: GraphRuntime writes this symbol onto a mounted instance after
+ * successful startup. `Component.setState()` invokes it after `onUpdate` so GraphRuntime
+ * can schedule an automatic subtree reconcile without an explicit external call.
+ *
+ * Cleared by GraphRuntime before `runShutdown` on unmount.
+ * Absence of the symbol on the instance (standalone or before mount / after unmount) means “no runtime”.
+ */
+export declare const SCHEDULE_UPDATE_HOOK: unique symbol;
+/**
+ * Internal contract for a component that intercepts `props` updates from GraphRuntime.
+ *
+ * Not part of the public API for user components; intended for infrastructure HOCs.
+ */
+export interface RuntimePropsReceiver<P = unknown> {
+    [RUNTIME_PROPS_RECEIVER]?(props: P): void;
+}
+/**
+ * Explicit Resource Management (ECMAScript) contract.
+ * Implementation allows using the instance in `using` for a guaranteed dispose call on block exit.
+ */
+export interface Disposable {
+    [Symbol.dispose](): void;
+}
+/**
+ * Typed ref object for accessing a component instance from a parent.
+ * Filled by GraphRuntime when the node mounts.
+ */
+export interface RefObject<T> {
+    /** Current component instance (null before mount or after unmount). */
+    current: T | null;
+}
+/**
+ * Typed component constructor.
+ */
+export type ComponentConstructor<P = unknown> = new (props: P) => Component<unknown, P>;
+/**
+ * Virtual service-tree node — a declarative component description for GraphRuntime.
+ * Created by h() and never contains side effects.
+ *
+ * To store heterogeneous nodes in arrays (compose() result, children)
+ * use AnyVirtualServiceNode (without a generic).
+ */
+export interface VirtualServiceNode<P = unknown> {
+    /**
+     * Component class that GraphRuntime will instantiate.
+     * Stored as an unknown constructor for covariant compatibility when held
+     * in arrays and runtime structures. GraphRuntime uses vnode.props to create the instance.
+     */
+    type: ComponentConstructor<unknown>;
+    /** Props passed to the component constructor. */
+    props: P;
+    /**
+     * Stable identity key for diffing.
+     * Required in dynamic lists — without a key the reconciler cannot correctly reuse nodes.
+     */
+    key?: string;
+    /** Ref for accessing the instance from the parent component. */
+    ref?: RefObject<unknown>;
+    /** Child nodes in declaration order. */
+    children: VirtualServiceNode[];
+}
+/**
+ * Node lifecycle status within GraphRuntime.
+ * Transitions are strictly unidirectional (except the ready -> update pass -> ready loop).
+ *
+ * registered -> resolved -> created -> mounted -> ready
+ * ready -(props/state/context change)-> update pass -> ready
+ * ready -> unmounting -> unmounted -> destroyed
+ * any stage -> failed (no return)
+ */
+export type NodeLifecycleStatus = 'registered' | 'resolved' | 'created' | 'mounted' | 'ready' | 'unmounting' | 'unmounted' | 'destroyed' | 'failed';
+/**
+ * Named fiber effect tags for the reconciler commit phase.
+ * null (no tag) is not part of the object — see {@link FiberEffectTag}.
+ */
+export declare const FIBER_EFFECT_TAG: {
+    /** New node (PLACE). */
+    readonly PLACE: "PLACE";
+    /** Props update (UPDATE). */
+    readonly UPDATE: "UPDATE";
+    /** Node removal (DELETE). */
+    readonly DELETE: "DELETE";
+};
+/**
+ * Fiber effect tag: a value from {@link FIBER_EFFECT_TAG} or `null`.
+ *
+ * NOTE: `null` means no uncommitted effect on the fiber. Currently set only after
+ * a successful PLACE/materialize: when `runStartup` completes ok (sync materialize path,
+ * `continueMaterializeAsync`, `finalizeMaterializeAsync`), GraphRuntime resets
+ * `effectTag` from {@link FIBER_EFFECT_TAG.PLACE} to `null` before `injectUpdateHook`.
+ *
+ * Do not confuse with “node was never updated”: after {@link FIBER_EFFECT_TAG.UPDATE}
+ * (`applyFiberUpdate`) the tag remains `UPDATE` and is not reset back to `null`.
+ * For DELETE there is no separate assignment on the fiber in the current GraphRuntime —
+ * removal goes through `destroyFiber` without writing `effectTag = DELETE`.
+ */
+export type FiberEffectTag = (typeof FIBER_EFFECT_TAG)[keyof typeof FIBER_EFFECT_TAG] | null;
+/**
+ * Readonly snapshot of a fiber node for test/debug introspection ({@link GraphRuntime.inspectRootFiber}).
+ * Does not contain mutable references to RuntimeFiber / instance / engine.
+ */
+export type FiberInspectNode = {
+    /** Current effectTag after the last materialize/reconcile phase. */
+    effectTag: FiberEffectTag;
+    /** true if the fiber has a materialized instance. */
+    hasInstance: boolean;
+    /** Virtual node key (null if unset). */
+    key: string | null;
+    /** Number of direct child fibers. */
+    childCount: number;
+    /** Recursive readonly child snapshots (compose order). */
+    children: readonly FiberInspectNode[];
+};
+/**
+ * Fiber — the reconciler work unit.
+ * Each virtual tree node has a corresponding fiber in the current tree.
+ * During reconcile a work-in-progress (WIP) tree is built via the alternate field.
+ */
+export interface Fiber<P = unknown> {
+    /** Virtual node this fiber was created from. */
+    vnode: VirtualServiceNode<P>;
+    /** Real component instance (null before the created phase). */
+    instance: Component<unknown, P> | null;
+    /** Current node lifecycle status. */
+    lifecycleStatus: NodeLifecycleStatus;
+    /** Child fibers in declaration order. */
+    children: Fiber[];
+    /** Parent fiber (null for the root). */
+    parentFiber: Fiber | null;
+    /**
+     * Alternate fiber — WIP pair of the current node during reconcile.
+     * current.alternate == wip, wip.alternate == current.
+     */
+    alternate: Fiber | null;
+    /** Pending props for a node update (null — no pending update). */
+    pendingProps: P | null;
+    /** Effect tag for the commit phase. */
+    effectTag: FiberEffectTag;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/build/component/types.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Lifecycle and Disposable types for Effectable/component.
+ * Lifecycle contract and Explicit Resource Management (TS 5.2+, Symbol.dispose).
+ * Also includes VirtualServiceNode, Fiber, and NodeLifecycleStatus types for declarative component trees.
+ *
+ * @module Effectable/component/types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIBER_EFFECT_TAG = exports.SCHEDULE_UPDATE_HOOK = exports.RUNTIME_PROPS_RECEIVER = void 0;
+/**
+ * Internal runtime hook for components that need custom application of incoming `props`
+ * during reconcile instead of a direct `instance.props = nextProps`.
+ *
+ * Used by `connect`-HOC to update props and rebuild merged props
+ * (`props + dispatch props + state props`) without losing previously computed values.
+ */
+exports.RUNTIME_PROPS_RECEIVER = Symbol('effectable:runtime_props_receiver');
+/**
+ * Hidden scheduler hook: GraphRuntime writes this symbol onto a mounted instance after
+ * successful startup. `Component.setState()` invokes it after `onUpdate` so GraphRuntime
+ * can schedule an automatic subtree reconcile without an explicit external call.
+ *
+ * Cleared by GraphRuntime before `runShutdown` on unmount.
+ * Absence of the symbol on the instance (standalone or before mount / after unmount) means “no runtime”.
+ */
+exports.SCHEDULE_UPDATE_HOOK = Symbol('effectable:schedule_update_hook');
+/**
+ * Named fiber effect tags for the reconciler commit phase.
+ * null (no tag) is not part of the object — see {@link FiberEffectTag}.
+ */
+exports.FIBER_EFFECT_TAG = {
+    /** New node (PLACE). */
+    PLACE: 'PLACE',
+    /** Props update (UPDATE). */
+    UPDATE: 'UPDATE',
+    /** Node removal (DELETE). */
+    DELETE: 'DELETE',
+};
+//# sourceMappingURL=types.js.map

package/build/component/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/component/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAiBH;;;;;;GAMG;AACU,QAAA,sBAAsB,GAAG,MAAM,CAAC,mCAAmC,CAAC,CAAC;AAElF;;;;;;;GAOG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,iCAAiC,CAAC,CAAC;AAoF9E;;;GAGG;AACU,QAAA,gBAAgB,GAAG;IAC9B,wBAAwB;IACxB,KAAK,EAAE,OAAO;IACd,6BAA6B;IAC7B,MAAM,EAAE,QAAQ;IAChB,6BAA6B;IAC7B,MAAM,EAAE,QAAQ;CACR,CAAC"}

package/build/connect/connect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HOC connect: connects a component class to the store via mapStateToProps and/or mapDispatchToProps,
+ * implemented as a class-based wrapper over the original class.
+ *
+ * Call: `connect(store, mapState?, mapDispatch?)(Ctor)`.
+ * Third argument: full function `(dispatch, props) => …`, short `(dispatch) => …`,
+ * or an object of action creators `{ key: (...args) => action }` (see `resolveMapDispatchProps`).
+ *
+ * @module Effectable/connect/connect
+ */
+import type { Action } from '../store/types';
+import type { Store } from '../store/types';
+import type { MapStateToProps, MapDispatchToProps, ConnectOptions, ConnectableHocTarget } from './types';
+/**
+ * Connects a component class to the store (class-based HOC): merge into `props` from state and/or dispatch.
+ * Supports two forms:
+ * - `connect(store, mapState?, mapDispatch?)` for a root connected component;
+ * - `connect(mapState?, mapDispatch?)` for a child connected component that receives the store from context.
+ *
+ * @template S store state type
+ * @template P props type of the connected component
+ * @template R result type of `mapStateToProps`
+ * @template A action type
+ * @param {Store<S, A> | MapStateToProps<S, P, R> | null | undefined} [storeOrMapStateToProps] - explicit store or `mapStateToProps`
+ * @param {MapStateToProps<S, P, R> | MapDispatchToProps<S, P, A> | null | undefined} [mapStateToPropsOrMapDispatchToProps] - `mapStateToProps` or `mapDispatchToProps`
+ * @param {MapDispatchToProps<S, P, A> | ConnectOptions | null | undefined} [mapDispatchToPropsOrOptions] - `mapDispatchToProps` or {@link ConnectOptions}
+ * @param {ConnectOptions} [maybeOptions] - {@link ConnectOptions} (e.g. `ownPropsModeMerge`) for the form with an explicit store
+ * @returns {<C extends ConnectableHocTarget>(Constructor: C) => C} HOC: `(Ctor) => subclass of C` with the same constructor name
+ */
+export declare function connect<S, P = unknown, R = unknown, A extends Action = Action>(storeOrMapStateToProps?: Store<S, A> | MapStateToProps<S, P, R> | null, mapStateToPropsOrMapDispatchToProps?: MapStateToProps<S, P, R> | MapDispatchToProps<S, P, A> | null, mapDispatchToPropsOrOptions?: MapDispatchToProps<S, P, A> | ConnectOptions | null, maybeOptions?: ConnectOptions): <C extends ConnectableHocTarget>(Constructor: C) => C;
+//# sourceMappingURL=connect.d.ts.map

package/build/connect/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/connect/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAU5C,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAIlB,cAAc,EACd,oBAAoB,EAErB,MAAM,SAAS,CAAC;AAqjBjB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAC5E,sBAAsB,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EACtE,mCAAmC,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,EACnG,2BAA2B,CAAC,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,GAAG,IAAI,EACjF,YAAY,CAAC,EAAE,cAAc,GAC5B,CAAC,CAAC,SAAS,oBAAoB,EAAE,WAAW,EAAE,CAAC,KAAK,CAAC,CA2BvD"}