@bian-womp/spark-graph 0.2.93 → 0.3.0

package/lib/cjs/src/runtime/components/RunContextManager.d.ts

@@ -0,0 +1,55 @@
+import type { RunContext, RunContextId, RuntimeNode } from "./types";
+/**
+ * RunContextManager component - manages run-context lifecycle
+ */
+export declare class RunContextManager {
+    private runContexts;
+    private runContextCounter;
+    /**
+     * Create a new run-context for runFromHere
+     */
+    createRunContext(startNodeId: string, options?: {
+        skipPropagateValues?: boolean;
+        propagate?: boolean;
+    }): RunContext;
+    /**
+     * Get a run-context by ID
+     */
+    getRunContext(id: RunContextId): RunContext | undefined;
+    /**
+     * Get all run-contexts
+     */
+    getAllRunContexts(): Map<RunContextId, RunContext>;
+    /**
+     * Check if there are any active run-contexts
+     */
+    hasActiveRunContexts(): boolean;
+    /**
+     * Finish and remove a run-context when its pending count reaches zero
+     */
+    finishRunContext(id: RunContextId, nodes: Map<string, RuntimeNode<any>>): void;
+    /**
+     * Cancel a node for all run-contexts (called from UI or update())
+     * @param nodeId - The node to cancel
+     * @param includeDownstream - Whether to also cancel downstream nodes
+     * @param edges - All edges in the graph (for downstream traversal)
+     * @param nodes - All nodes in the graph (for clearing activeRunContexts)
+     */
+    cancelNodeInRunContexts(nodeId: string, includeDownstream: boolean, edges: Array<{
+        source: {
+            nodeId: string;
+        };
+        target: {
+            nodeId: string;
+        };
+    }>, nodes: Map<string, RuntimeNode<any>>): void;
+    /**
+     * Resolve all pending run-context promises (for cleanup)
+     */
+    resolveAll(): void;
+    /**
+     * Clear all run-contexts
+     */
+    clear(): void;
+}
+//# sourceMappingURL=RunContextManager.d.ts.map

package/lib/cjs/src/runtime/components/RunContextManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunContextManager.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/components/RunContextManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAErE;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,iBAAiB,CAAK;IAE9B;;OAEG;IACH,gBAAgB,CACd,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QACR,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GACA,UAAU;IAcb;;OAEG;IACH,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS;IAIvD;;OAEG;IACH,iBAAiB,IAAI,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC;IAIlD;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAI/B;;OAEG;IACH,gBAAgB,CACd,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,GACnC,IAAI;IAcP;;;;;;OAMG;IACH,uBAAuB,CACrB,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,OAAO,EAC1B,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,EACxE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,GACnC,IAAI;IAoCP;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/lib/cjs/src/runtime/components/ValuePropagator.d.ts

@@ -0,0 +1,46 @@
+import type { RunContextId } from "./types";
+import type { GraphStructure } from "./GraphStructure";
+import type { EventEmitter } from "./EventEmitter";
+import type { RunContextManager } from "./RunContextManager";
+import { IExecutionScheduler, IHandleResolver, IRuntimeCoordinator } from "./interfaces";
+/**
+ * ValuePropagator component - handles value propagation through edges
+ */
+export declare class ValuePropagator {
+    private graphStructure;
+    private eventEmitter;
+    private runContextManager;
+    private executionScheduler;
+    private handleResolver;
+    private runtimeCoordinator;
+    private arrayInputBuckets;
+    constructor(graphStructure: GraphStructure, eventEmitter: EventEmitter, runContextManager: RunContextManager, handleResolver: IHandleResolver, runtimeCoordinator: IRuntimeCoordinator);
+    /**
+     * Set the execution scheduler (called after construction to resolve circular dependency)
+     */
+    setExecutionScheduler(executionScheduler: IExecutionScheduler): void;
+    /**
+     * Propagate value through edges
+     * @param runContextIds - Optional set of run-context IDs. If provided, propagation is run-context aware.
+     *                        If undefined or empty, behaves like auto mode (always propagates values and execution).
+     */
+    propagate(srcNodeId: string, srcHandle: string, value: unknown, runContextIds?: Set<RunContextId>): void;
+    /**
+     * Propagate value in run-context aware mode (convenience method)
+     */
+    propagateInRunContexts(srcNodeId: string, srcHandle: string, value: unknown, runContextIds: Set<RunContextId>): void;
+    /**
+     * Re-emit all outputs from a node (used when graph updates)
+     * Only re-emits outputs that are valid according to resolved handles
+     */
+    reemitNodeOutputs(nodeId: string): void;
+    /**
+     * Clear array input buckets for a node (when node is deleted)
+     */
+    clearArrayBuckets(nodeId: string): void;
+    /**
+     * Clear all array buckets
+     */
+    clearAllArrayBuckets(): void;
+}
+//# sourceMappingURL=ValuePropagator.d.ts.map

package/lib/cjs/src/runtime/components/ValuePropagator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValuePropagator.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/components/ValuePropagator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACpB,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,kBAAkB,CAAsB;IAChD,OAAO,CAAC,iBAAiB,CAGrB;gBAGF,cAAc,EAAE,cAAc,EAC9B,YAAY,EAAE,YAAY,EAC1B,iBAAiB,EAAE,iBAAiB,EACpC,cAAc,EAAE,eAAe,EAC/B,kBAAkB,EAAE,mBAAmB;IASzC;;OAEG;IACH,qBAAqB,CAAC,kBAAkB,EAAE,mBAAmB,GAAG,IAAI;IAIpE;;;;OAIG;IACH,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAChC,IAAI;IA8NP;;OAEG;IACH,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,GAAG,CAAC,YAAY,CAAC,GAC/B,IAAI;IAIP;;;OAGG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAqBvC;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIvC;;OAEG;IACH,oBAAoB,IAAI,IAAI;CAG7B"}

package/lib/cjs/src/runtime/components/interfaces.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedHandles } from "@bian-womp/spark-protocol";
+import type { Registry } from "../../builder/Registry";
+import type { RunContextId } from "./types";
+/**
+ * Interface for value propagation operations
+ */
+export interface IValuePropagator {
+    propagate(srcNodeId: string, srcHandle: string, value: unknown, runContextIds?: Set<RunContextId>): void;
+    propagateInRunContexts(srcNodeId: string, srcHandle: string, value: unknown, runContextIds: Set<RunContextId>): void;
+}
+/**
+ * Interface for execution scheduling operations
+ */
+export interface IExecutionScheduler {
+    scheduleInputsChanged(nodeId: string): void;
+    scheduleInputsChangedWithRunContexts(nodeId: string, runContextIds: Set<RunContextId>): void;
+    allInboundHaveValue(nodeId: string): boolean;
+}
+/**
+ * Interface for handle resolution operations
+ */
+export interface IHandleResolver {
+    scheduleRecomputeHandles(nodeId: string): void;
+}
+/**
+ * Interface for runtime coordination operations
+ * Implemented by GraphRuntime to coordinate cross-component operations
+ */
+export interface IRuntimeCoordinator {
+    updateNodeHandles(nodeId: string, handles: ResolvedHandles, registry: Registry): void;
+    invalidateDownstream(nodeId: string): void;
+    isPaused(): boolean;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/lib/cjs/src/runtime/components/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/components/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAChC,IAAI,CAAC;IACR,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,GAAG,CAAC,YAAY,CAAC,GAC/B,IAAI,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,oCAAoC,CAClC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,GAAG,CAAC,YAAY,CAAC,GAC/B,IAAI,CAAC;IACR,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,iBAAiB,CACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,QAAQ,GACjB,IAAI,CAAC;IACR,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,IAAI,OAAO,CAAC;CACrB"}

package/lib/cjs/src/runtime/components/types.d.ts

@@ -0,0 +1,43 @@
+import type { GraphNodeDefinition, GraphEdgeDefinition, ExecutionPolicy, LogLevel } from "@bian-womp/spark-protocol";
+import type { NodeTypeDescriptor, RuntimeEdgeStats, RuntimeNodeStats } from "../../core/types";
+import type { CategoryRuntime } from "../../core/categories";
+export interface RuntimeNode<State = any> extends GraphNodeDefinition {
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    state: State;
+    runtime: CategoryRuntime<State>;
+    lifecycle: NodeTypeDescriptor<Record<string, string>, Record<string, string>, State, any>["lifecycle"];
+    policy?: Partial<ExecutionPolicy>;
+    logLevel?: LogLevel;
+    latestRunId?: string;
+    runSeq: number;
+    activeControllers: Set<AbortController>;
+    controllerRunIds: Map<AbortController, string>;
+    snapshotCancelledRunIds?: Set<string>;
+    queue: Array<{
+        runId: string;
+        inputs: Record<string, unknown>;
+    }>;
+    lastScheduledAt?: number;
+    stats: RuntimeNodeStats;
+    activeRunContexts: Set<string>;
+}
+export interface RuntimeEdge extends GraphEdgeDefinition {
+    convert?: (value: unknown) => unknown;
+    convertAsync?: (value: unknown, signal: AbortSignal) => Promise<unknown>;
+    stats: RuntimeEdgeStats;
+    srcUnionTypes?: string[];
+    dstDeclared?: string;
+    effectiveTypeId: string;
+}
+export type RunContextId = string;
+export interface RunContext {
+    id: RunContextId;
+    startNodes: Set<string>;
+    cancelledNodes: Set<string>;
+    pending: number;
+    skipPropagateValues: boolean;
+    propagate: boolean;
+    resolve?: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/cjs/src/runtime/components/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/components/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,QAAQ,EACT,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,GAAG,CAAE,SAAQ,mBAAmB;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAChC,SAAS,EAAE,kBAAkB,CAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtB,KAAK,EACL,GAAG,CACJ,CAAC,WAAW,CAAC,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;IAGxC,gBAAgB,EAAE,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAK/C,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,gBAAgB,CAAC;IAExB,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,WAAY,SAAQ,mBAAmB;IACtD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,KAAK,EAAE,gBAAgB,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,YAAY,CAAC;IACjB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB"}

package/lib/cjs/src/runtime/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared utility functions for runtime components
+ */
+/**
+ * Type guard to check if a value is a Promise
+ */
+export declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
+/**
+ * Unwrap a value that might be a Promise
+ */
+export declare function unwrapMaybePromise<T>(value: T | Promise<T>): Promise<T>;
+/**
+ * Shallow/deep-ish equality check to avoid unnecessary runs on identical values
+ */
+export declare function valuesEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/lib/cjs/src/runtime/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/runtime/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAE1E;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE7E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAW3D"}