@uploadista/core 0.0.2

package/dist/flow/flow.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Core Flow Engine implementation using Effect-based DAG execution.
+ *
+ * This module implements the Flow Engine, which executes directed acyclic graphs (DAGs)
+ * of processing nodes. It supports sequential execution with topological sorting,
+ * conditional node execution, retry logic, and pausable flows.
+ *
+ * @module flow
+ * @see {@link createFlowWithSchema} for creating new flows
+ * @see {@link Flow} for the flow type definition
+ */
+/** biome-ignore-all lint/suspicious/noExplicitAny: any is used to allow for dynamic types */
+import { Effect } from "effect";
+import { z } from "zod";
+import { UploadistaError } from "../errors";
+import type { FlowEdge } from "./edge";
+import type { FlowConfig, FlowNode, FlowNodeData } from "./types/flow-types";
+/**
+ * Serialized flow data for storage and transport.
+ * Contains the minimal information needed to reconstruct a flow.
+ *
+ * @property id - Unique flow identifier
+ * @property name - Human-readable flow name
+ * @property nodes - Array of node data (without execution logic)
+ * @property edges - Connections between nodes defining data flow
+ */
+export type FlowData = {
+    id: string;
+    name: string;
+    nodes: FlowNodeData[];
+    edges: FlowEdge[];
+};
+/**
+ * Extracts serializable flow data from a Flow instance.
+ * Useful for storing flow definitions or sending them over the network.
+ *
+ * @template TRequirements - Effect requirements for the flow
+ * @param flow - Flow instance to extract data from
+ * @returns Serializable flow data without execution logic
+ *
+ * @example
+ * ```typescript
+ * const flowData = getFlowData(myFlow);
+ * // Store in database or send to client
+ * await db.flows.save(flowData);
+ * ```
+ */
+export declare const getFlowData: <TRequirements>(flow: Flow<any, any, TRequirements>) => FlowData;
+/**
+ * Result of a flow execution - either completed or paused.
+ *
+ * @template TOutput - Type of the flow's output data
+ *
+ * @remarks
+ * Flows can pause when a node needs additional data (e.g., waiting for user input
+ * or external service). The execution state allows resuming from where it paused.
+ *
+ * @example
+ * ```typescript
+ * const result = await Effect.runPromise(flow.run({ inputs, storageId, jobId }));
+ *
+ * if (result.type === "completed") {
+ *   console.log("Flow completed:", result.result);
+ * } else {
+ *   console.log("Flow paused at node:", result.nodeId);
+ *   // Can resume later with: flow.resume({ jobId, executionState: result.executionState, ... })
+ * }
+ * ```
+ */
+export type FlowExecutionResult<TOutput> = {
+    type: "completed";
+    result: TOutput;
+} | {
+    type: "paused";
+    nodeId: string;
+    executionState: {
+        executionOrder: string[];
+        currentIndex: number;
+        inputs: Record<string, unknown>;
+    };
+};
+/**
+ * A Flow represents a directed acyclic graph (DAG) of processing nodes.
+ *
+ * Flows execute nodes in topological order, passing data between nodes through edges.
+ * They support conditional execution, retry logic, pausable nodes, and event emission.
+ *
+ * @template TFlowInputSchema - Zod schema defining the shape of input data
+ * @template TFlowOutputSchema - Zod schema defining the shape of output data
+ * @template TRequirements - Effect requirements (services/contexts) needed by nodes
+ *
+ * @property id - Unique flow identifier
+ * @property name - Human-readable flow name
+ * @property nodes - Array of nodes in the flow
+ * @property edges - Connections between nodes
+ * @property inputSchema - Zod schema for validating flow inputs
+ * @property outputSchema - Zod schema for validating flow outputs
+ * @property onEvent - Optional callback for flow execution events
+ * @property run - Executes the flow from the beginning
+ * @property resume - Resumes a paused flow execution
+ * @property validateTypes - Validates node type compatibility
+ * @property validateInputs - Validates input data against schema
+ * @property validateOutputs - Validates output data against schema
+ *
+ * @remarks
+ * Flows are created using {@link createFlowWithSchema}. The Effect-based design
+ * allows for composable error handling, resource management, and dependency injection.
+ *
+ * @example
+ * ```typescript
+ * const flow = yield* createFlowWithSchema({
+ *   flowId: "image-pipeline",
+ *   name: "Image Processing Pipeline",
+ *   nodes: [inputNode, resizeNode, optimizeNode, storageNode],
+ *   edges: [
+ *     { source: "input", target: "resize" },
+ *     { source: "resize", target: "optimize" },
+ *     { source: "optimize", target: "storage" }
+ *   ],
+ *   inputSchema: z.object({ file: z.instanceof(File) }),
+ *   outputSchema: uploadFileSchema
+ * });
+ *
+ * const result = yield* flow.run({
+ *   inputs: { input: { file: myFile } },
+ *   storageId: "storage-1",
+ *   jobId: "job-123"
+ * });
+ * ```
+ */
+export type Flow<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema extends z.ZodSchema<any>, TRequirements> = {
+    id: string;
+    name: string;
+    nodes: FlowNode<any, any, UploadistaError>[];
+    edges: FlowEdge[];
+    inputSchema: TFlowInputSchema;
+    outputSchema: TFlowOutputSchema;
+    onEvent?: FlowConfig<TFlowInputSchema, TFlowOutputSchema, TRequirements>["onEvent"];
+    run: (args: {
+        inputs?: Record<string, z.infer<TFlowInputSchema>>;
+        storageId: string;
+        jobId: string;
+        clientId: string | null;
+    }) => Effect.Effect<FlowExecutionResult<Record<string, z.infer<TFlowOutputSchema>>>, UploadistaError, TRequirements>;
+    resume: (args: {
+        jobId: string;
+        storageId: string;
+        nodeResults: Record<string, unknown>;
+        executionState: {
+            executionOrder: string[];
+            currentIndex: number;
+            inputs: Record<string, z.infer<TFlowInputSchema>>;
+        };
+        clientId: string | null;
+    }) => Effect.Effect<FlowExecutionResult<Record<string, z.infer<TFlowOutputSchema>>>, UploadistaError, TRequirements>;
+    validateTypes: () => {
+        isValid: boolean;
+        errors: string[];
+    };
+    validateInputs: (inputs: unknown) => {
+        isValid: boolean;
+        errors: string[];
+    };
+    validateOutputs: (outputs: unknown) => {
+        isValid: boolean;
+        errors: string[];
+    };
+};
+/**
+ * Creates a new Flow with Zod schema-based type validation.
+ *
+ * This is the primary way to create flows in Uploadista. It constructs a Flow
+ * instance that validates inputs/outputs, executes nodes in topological order,
+ * handles errors with retries, and emits events during execution.
+ *
+ * @template TFlowInputSchema - Zod schema for flow input validation
+ * @template TFlowOutputSchema - Zod schema for flow output validation
+ * @template TRequirements - Effect requirements/services needed by the flow
+ * @template TNodeError - Union of possible errors from nodes
+ * @template TNodeRequirements - Union of requirements from nodes
+ *
+ * @param config - Flow configuration object
+ * @param config.flowId - Unique identifier for the flow
+ * @param config.name - Human-readable flow name
+ * @param config.nodes - Array of nodes (can be plain nodes or Effects resolving to nodes)
+ * @param config.edges - Array of edges connecting nodes
+ * @param config.inputSchema - Zod schema for validating inputs
+ * @param config.outputSchema - Zod schema for validating outputs
+ * @param config.typeChecker - Optional custom type compatibility checker
+ * @param config.onEvent - Optional event callback for monitoring execution
+ *
+ * @returns Effect that resolves to a Flow instance
+ *
+ * @throws {UploadistaError} FLOW_CYCLE_ERROR if the graph contains cycles
+ * @throws {UploadistaError} FLOW_NODE_NOT_FOUND if a node is referenced but missing
+ * @throws {UploadistaError} FLOW_NODE_ERROR if node execution fails
+ * @throws {UploadistaError} FLOW_OUTPUT_VALIDATION_ERROR if outputs don't match schema
+ *
+ * @remarks
+ * - Nodes can be provided as plain objects or as Effects that resolve to nodes
+ * - The flow performs topological sorting to determine execution order
+ * - Conditional nodes are evaluated before execution
+ * - Nodes can specify retry configuration with exponential backoff
+ * - Pausable nodes can halt execution and resume later
+ *
+ * @example
+ * ```typescript
+ * const flow = yield* createFlowWithSchema({
+ *   flowId: "image-upload",
+ *   name: "Image Upload with Processing",
+ *   nodes: [
+ *     inputNode,
+ *     yield* createResizeNode({ width: 1920, height: 1080 }),
+ *     optimizeNode,
+ *     storageNode
+ *   ],
+ *   edges: [
+ *     { source: "input", target: "resize" },
+ *     { source: "resize", target: "optimize" },
+ *     { source: "optimize", target: "storage" }
+ *   ],
+ *   inputSchema: z.object({
+ *     file: z.instanceof(File),
+ *     metadata: z.record(z.string(), z.any()).optional()
+ *   }),
+ *   outputSchema: uploadFileSchema,
+ *   onEvent: (event) => Effect.gen(function* () {
+ *     console.log("Flow event:", event);
+ *     return { eventId: event.jobId };
+ *   })
+ * });
+ * ```
+ *
+ * @see {@link Flow} for the returned flow type
+ * @see {@link FlowConfig} for configuration options
+ */
+export declare function createFlowWithSchema<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema extends z.ZodSchema<any>, TRequirements = never, TNodeError = never, TNodeRequirements = never>(config: FlowConfig<TFlowInputSchema, TFlowOutputSchema, TNodeError, TNodeRequirements>): Effect.Effect<Flow<TFlowInputSchema, TFlowOutputSchema, TRequirements>, TNodeError, TNodeRequirements>;
+//# sourceMappingURL=flow.d.ts.map

package/dist/flow/flow.d.ts.map

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