effectable 0.1.0

package/build/component/Component.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Base class with state and lifecycle for Effectable: GraphRuntime,
+ * connect-HOC (class-based), and standalone use.
+ *
+ * Holds `state`, updates it via {@link Component.setState}, and after each update calls
+ * {@link Component.onUpdate}.
+ *
+ * **Modes:**
+ * - **Standalone** — `Component` as a lightweight stateful object without GraphRuntime: `setState`
+ *   immediately leads to `onUpdate`, with no “only after mount” restriction.
+ * - **Mounted (GraphRuntime)** — LifecycleEngine defines hook order; `onUpdate` runs only after
+ *   a successful {@link Component.onMount}.
+ *
+ * **Who calls hooks:** `onMount`, `onUnmount`, {@link Component.compose} — GraphRuntime in mounted mode.
+ * `connect`-HOC overrides `onMount`/`onUnmount` to manage the store subscription and delegates to
+ * `super.onMount?.()` / `super.onUnmount?.()` on the subclass.
+ *
+ * @module Effectable/component/Component
+ */
+import type { Lifecycle } from './types';
+import type { VirtualServiceNode } from './types';
+/**
+ * Argument to {@link Component.setState}: a partial state (shallow-merged with previous `state`) or
+ * a function `(prevState, props) => Partial<S>`.
+ *
+ * @template S Instance state type.
+ * @template P Instance props type.
+ */
+export type SetStateUpdate<S, P = unknown> = Partial<S> | ((prevState: S, props: P) => Partial<S>);
+/**
+ * Abstract base class with state and lifecycle.
+ * Implements the {@link Lifecycle} contract: `onMount` → `onUpdate*` → `onUnmount`.
+ * GraphRuntime additionally uses {@link Component.compose} for a declarative subtree.
+ *
+ * @template S Type of {@link Component.state}.
+ * @template P Type of {@link Component.props}.
+ * @implements {Lifecycle}
+ *
+ * @example
+ * ```ts
+ * class Tick extends Component<{ count: number }, { step: number }> {
+ *   constructor (props: { step: number }) {
+ *     super(props);
+ *     this.state = { count: 0 };
+ *   }
+ *   bump () {
+ *     this.setState((s, p) => ({ count: s.count + p.step }));
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Component<S = unknown, P = unknown> implements Lifecycle {
+    /**
+     * Opt-in flag for HFT components: if `true`, {@link Component.setState} applies
+     * updates **in-place** on the current `this.state` instead of creating a new object via spread.
+     *
+     * Yields 8.6x–710x speedup depending on state size,
+     * but breaks immutability semantics: `prev` and `next` in `onUpdate` point to the same object.
+     * Enable only for components whose `onUpdate` does not rely on prev/next separation.
+     *
+     * Subclass activates the flag like this:
+     * ```ts
+     * class FastTicker extends Component<State, Props> {
+     *   public static override readonly mutableState = true;
+     * }
+     * ```
+     */
+    static readonly mutableState: boolean;
+    /** Current instance state after the last assignment in {@link Component.setState}. */
+    state: S;
+    /** Instance inputs: filled by GraphRuntime, connect-HOC, or calling code. */
+    props: P;
+    /**
+     * @param {P} props Props available in the {@link Component.setState} callback and in the subclass.
+     * @param {S} [initialState] Initial state; if omitted, an empty object is used as `S`.
+     */
+    constructor(props: P, initialState?: S);
+    /**
+     * Computes the next state as a shallow merge of `prev` with the update object or with the
+     * function result, then calls {@link Component.onUpdate}.
+     *
+     * If the class sets `static mutableState = true`, applies updates in-place
+     * on `this.state` — zero allocations, but `prev === next`.
+     *
+     * @param {SetStateUpdate<S, P>} update Partial state or `(prevState, props) => Partial<S>`.
+     * @returns {void}
+     */
+    setState(update: SetStateUpdate<S, P>): void;
+    /**
+     * Called on every `state` change (from {@link Component.setState} or from connect-HOC
+     * via `setState({})` after merging mapped props).
+     * In standalone — immediately after `setState`. In mounted mode — only after a successful
+     * {@link Component.onMount} (decided by GraphRuntime). Override in subclasses.
+     *
+     * @param {S} _prev State before the update was applied.
+     * @param {S} _next State after the update was applied.
+     * @returns {void}
+     */
+    onUpdate(_prev: S, _next: S): void;
+    /**
+     * Optional: node mount in GraphRuntime. Typically used to start subscriptions,
+     * timers, and background work. Called by LifecycleEngine exactly once before transitioning
+     * to the `ready` stage. Mounted mode only.
+     *
+     * @returns {void | Promise<void>}
+     */
+    onMount?(): void | Promise<void>;
+    /**
+     * Optional: node unmount from GraphRuntime. Typically used to drop subscriptions and stop
+     * side effects. Called by LifecycleEngine exactly once during shutdown. Mounted mode only.
+     *
+     * @returns {void | Promise<void>}
+     */
+    onUnmount?(): void | Promise<void>;
+    /**
+     * Optional: declarative subtree description with no side effects.
+     * Called by GraphRuntime during materialization and reconcile.
+     *
+     * Forbidden inside: network, bus subscriptions, handler registration, mutating global state.
+     *
+     * @returns {VirtualServiceNode | VirtualServiceNode[] | null} One or more virtual nodes,
+     *   or `null` if the subtree is empty.
+     */
+    compose?(): VirtualServiceNode | VirtualServiceNode[] | null;
+}
+//# sourceMappingURL=Component.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Component.d.ts","sourceRoot":"","sources":["../../src/component/Component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,IACrC,OAAO,CAAC,CAAC,CAAC,GACV,CAAC,CAAC,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8BAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,CACxD,YAAW,SAAS;IAClB;;;;;;;;;;;;;;OAcG;IACH,gBAAuB,YAAY,EAAE,OAAO,CAAS;IAErD,sFAAsF;IAC/E,KAAK,EAAE,CAAC,CAAC;IAEhB,6EAA6E;IACtE,KAAK,EAAE,CAAC,CAAC;IAEhB;;;OAGG;gBACU,KAAK,EAAE,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC;IAKvC;;;;;;;;;OASG;IACI,QAAQ,CAAE,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IA0BpD;;;;;;;;;OASG;IACI,QAAQ,CAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAI1C;;;;;;OAMG;IACH,OAAO,CAAC,IAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjC;;;;;OAKG;IACH,SAAS,CAAC,IAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAK,kBAAkB,GAAG,kBAAkB,EAAE,GAAG,IAAI;CAC9D"}

package/build/component/Component.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Base class with state and lifecycle for Effectable: GraphRuntime,
+ * connect-HOC (class-based), and standalone use.
+ *
+ * Holds `state`, updates it via {@link Component.setState}, and after each update calls
+ * {@link Component.onUpdate}.
+ *
+ * **Modes:**
+ * - **Standalone** — `Component` as a lightweight stateful object without GraphRuntime: `setState`
+ *   immediately leads to `onUpdate`, with no “only after mount” restriction.
+ * - **Mounted (GraphRuntime)** — LifecycleEngine defines hook order; `onUpdate` runs only after
+ *   a successful {@link Component.onMount}.
+ *
+ * **Who calls hooks:** `onMount`, `onUnmount`, {@link Component.compose} — GraphRuntime in mounted mode.
+ * `connect`-HOC overrides `onMount`/`onUnmount` to manage the store subscription and delegates to
+ * `super.onMount?.()` / `super.onUnmount?.()` on the subclass.
+ *
+ * @module Effectable/component/Component
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Component = void 0;
+const types_1 = require("./types");
+/**
+ * Abstract base class with state and lifecycle.
+ * Implements the {@link Lifecycle} contract: `onMount` → `onUpdate*` → `onUnmount`.
+ * GraphRuntime additionally uses {@link Component.compose} for a declarative subtree.
+ *
+ * @template S Type of {@link Component.state}.
+ * @template P Type of {@link Component.props}.
+ * @implements {Lifecycle}
+ *
+ * @example
+ * ```ts
+ * class Tick extends Component<{ count: number }, { step: number }> {
+ *   constructor (props: { step: number }) {
+ *     super(props);
+ *     this.state = { count: 0 };
+ *   }
+ *   bump () {
+ *     this.setState((s, p) => ({ count: s.count + p.step }));
+ *   }
+ * }
+ * ```
+ */
+class Component {
+    /**
+     * Opt-in flag for HFT components: if `true`, {@link Component.setState} applies
+     * updates **in-place** on the current `this.state` instead of creating a new object via spread.
+     *
+     * Yields 8.6x–710x speedup depending on state size,
+     * but breaks immutability semantics: `prev` and `next` in `onUpdate` point to the same object.
+     * Enable only for components whose `onUpdate` does not rely on prev/next separation.
+     *
+     * Subclass activates the flag like this:
+     * ```ts
+     * class FastTicker extends Component<State, Props> {
+     *   public static override readonly mutableState = true;
+     * }
+     * ```
+     */
+    static mutableState = false;
+    /** Current instance state after the last assignment in {@link Component.setState}. */
+    state;
+    /** Instance inputs: filled by GraphRuntime, connect-HOC, or calling code. */
+    props;
+    /**
+     * @param {P} props Props available in the {@link Component.setState} callback and in the subclass.
+     * @param {S} [initialState] Initial state; if omitted, an empty object is used as `S`.
+     */
+    constructor(props, initialState) {
+        this.props = props;
+        this.state = (initialState ?? {});
+    }
+    /**
+     * Computes the next state as a shallow merge of `prev` with the update object or with the
+     * function result, then calls {@link Component.onUpdate}.
+     *
+     * If the class sets `static mutableState = true`, applies updates in-place
+     * on `this.state` — zero allocations, but `prev === next`.
+     *
+     * @param {SetStateUpdate<S, P>} update Partial state or `(prevState, props) => Partial<S>`.
+     * @returns {void}
+     */
+    setState(update) {
+        const prev = this.state;
+        const delta = typeof update === 'function'
+            ? update(prev, this.props)
+            : update;
+        // HFT fast-path: in-place state mutation without allocating a new object
+        // (8.6x–710x speedup). Enabled via static mutableState = true.
+        if (this.constructor.mutableState === true) {
+            const target = prev;
+            const src = delta;
+            for (const k in src) {
+                target[k] = src[k];
+            }
+            this.onUpdate(prev, prev);
+            this[types_1.SCHEDULE_UPDATE_HOOK]?.();
+            return;
+        }
+        // Shallow-copy previous state and delta to avoid mutating the original state
+        const next = { ...prev, ...delta };
+        this.state = next;
+        this.onUpdate(prev, next);
+        this[types_1.SCHEDULE_UPDATE_HOOK]?.();
+    }
+    /**
+     * Called on every `state` change (from {@link Component.setState} or from connect-HOC
+     * via `setState({})` after merging mapped props).
+     * In standalone — immediately after `setState`. In mounted mode — only after a successful
+     * {@link Component.onMount} (decided by GraphRuntime). Override in subclasses.
+     *
+     * @param {S} _prev State before the update was applied.
+     * @param {S} _next State after the update was applied.
+     * @returns {void}
+     */
+    onUpdate(_prev, _next) {
+        // Empty by default; subclass overrides as needed.
+    }
+}
+exports.Component = Component;
+//# sourceMappingURL=Component.js.map

package/build/component/Component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Component.js","sourceRoot":"","sources":["../../src/component/Component.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAIH,mCAA+C;AAa/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAsB,SAAS;IAE7B;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAU,YAAY,GAAY,KAAK,CAAC;IAErD,sFAAsF;IAC/E,KAAK,CAAI;IAEhB,6EAA6E;IACtE,KAAK,CAAI;IAEhB;;;OAGG;IACH,YAAa,KAAQ,EAAE,YAAgB;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,CAAC,YAAY,IAAI,EAAE,CAAM,CAAC;IACzC,CAAC;IAED;;;;;;;;;OASG;IACI,QAAQ,CAAE,MAA4B;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,MAAM,KAAK,GAAG,OAAO,MAAM,KAAK,UAAU;YACxC,CAAC,CAAE,MAA4C,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;YACjE,CAAC,CAAC,MAAM,CAAC;QAEX,yEAAyE;QACzE,+DAA+D;QAC/D,IAAK,IAAI,CAAC,WAA0C,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAC3E,MAAM,MAAM,GAAG,IAA0C,CAAC;YAC1D,MAAM,GAAG,GAAG,KAA2C,CAAC;YACxD,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;gBACpB,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACrB,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACzB,IAA2D,CAAC,4BAAoB,CAAC,EAAE,EAAE,CAAC;YACvF,OAAO;QACT,CAAC;QAED,6EAA6E;QAC7E,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,IAAS,CAAC;QACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACzB,IAA2D,CAAC,4BAAoB,CAAC,EAAE,EAAE,CAAC;IACzF,CAAC;IAED;;;;;;;;;OASG;IACI,QAAQ,CAAE,KAAQ,EAAE,KAAQ;QACjC,kDAAkD;IACpD,CAAC;;AAlFH,8BA+GC"}