@uploadista/core 0.0.2

package/dist/flow/types/flow-types.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Core flow type definitions and node specifications.
+ *
+ * This module defines the fundamental types for the Flow Engine, including node
+ * definitions, execution results, edges, and configuration. These types form the
+ * foundation of the DAG processing system.
+ *
+ * @module flow/types/flow-types
+ * @see {@link FlowNode} for node specification
+ * @see {@link FlowConfig} for flow configuration
+ */
+/** biome-ignore-all lint/suspicious/noExplicitAny: any is used to allow for dynamic types */
+import type { Effect } from "effect";
+import type { z } from "zod";
+import type { UploadistaError } from "../../errors";
+import type { FlowEvent, FlowEventFlowEnd, FlowEventFlowStart } from "../event";
+import { NodeType } from "../node";
+/**
+ * Type mapping for node input/output schemas.
+ * Used for type-safe node connections in typed flows.
+ */
+export type NodeTypeMap = Record<string, {
+    input: unknown;
+    output: unknown;
+}>;
+/**
+ * Minimal node data without execution logic.
+ * Used for serialization and UI display.
+ *
+ * @property id - Unique node identifier
+ * @property name - Human-readable node name
+ * @property description - Explanation of what the node does
+ * @property type - Node category (input, transform, conditional, output, etc.)
+ */
+export type FlowNodeData = {
+    id: string;
+    name: string;
+    description: string;
+    type: NodeType;
+};
+/**
+ * Result of a node execution - either complete or waiting for more data.
+ *
+ * @template TOutput - Type of the node's output data
+ *
+ * @remarks
+ * Nodes can return "waiting" to pause flow execution when they need additional
+ * data (e.g., chunked uploads, external service responses). The flow can be
+ * resumed later with the missing data.
+ *
+ * @example
+ * ```typescript
+ * // Node completes immediately
+ * return completeNodeExecution({ processedData });
+ *
+ * // Node waits for more chunks
+ * if (needsMoreData) {
+ *   return waitingNodeExecution({ receivedChunks: 3, totalChunks: 10 });
+ * }
+ * ```
+ */
+export type NodeExecutionResult<TOutput> = {
+    type: "complete";
+    data: TOutput;
+} | {
+    type: "waiting";
+    partialData?: unknown;
+};
+/**
+ * Helper function to create a complete node execution result.
+ *
+ * @template TOutput - Type of the output data
+ * @param data - The output data from the node
+ * @returns A complete execution result
+ *
+ * @example
+ * ```typescript
+ * return completeNodeExecution({
+ *   url: uploadedFile.url,
+ *   size: uploadedFile.size
+ * });
+ * ```
+ */
+export declare const completeNodeExecution: <TOutput>(data: TOutput) => {
+    type: "complete";
+    data: TOutput;
+};
+/**
+ * Helper function to create a waiting node execution result.
+ *
+ * @param partialData - Optional partial data available so far
+ * @returns A waiting execution result that pauses the flow
+ *
+ * @example
+ * ```typescript
+ * // Wait for more upload chunks
+ * return waitingNodeExecution({
+ *   receivedBytes: currentSize,
+ *   totalBytes: expectedSize
+ * });
+ * ```
+ */
+export declare const waitingNodeExecution: (partialData?: unknown) => {
+    type: "waiting";
+    partialData: unknown;
+};
+/**
+ * A flow node represents a single processing step in the DAG.
+ *
+ * Nodes are the building blocks of flows. Each node has typed inputs/outputs,
+ * execution logic, and optional features like conditions, retries, and pausing.
+ *
+ * @template TInput - Type of data the node accepts
+ * @template TOutput - Type of data the node produces
+ * @template TError - Type of errors the node can throw
+ *
+ * @property inputSchema - Zod schema for validating input data
+ * @property outputSchema - Zod schema for validating output data
+ * @property run - Effect-based execution function
+ * @property condition - Optional conditional execution rule
+ * @property multiInput - Whether node accepts multiple inputs (default: false)
+ * @property multiOutput - Whether node produces multiple outputs (default: false)
+ * @property pausable - Whether node can pause execution (default: false)
+ * @property retry - Optional retry configuration
+ *
+ * @remarks
+ * - Nodes use Effect for composable error handling and dependency injection
+ * - Input/output schemas ensure type safety at runtime
+ * - Conditions are evaluated before execution
+ * - Retry logic supports exponential backoff
+ * - Pausable nodes can halt flow execution and resume later
+ *
+ * @example
+ * ```typescript
+ * const resizeNode: FlowNode<InputFile, UploadFile> = {
+ *   id: "resize",
+ *   name: "Resize Image",
+ *   description: "Resize image to specified dimensions",
+ *   type: NodeType.transform,
+ *   inputSchema: inputFileSchema,
+ *   outputSchema: uploadFileSchema,
+ *   run: ({ data, storageId }) => Effect.gen(function* () {
+ *     const resized = yield* resizeImage(data, { width: 1920, height: 1080 });
+ *     return completeNodeExecution(resized);
+ *   }),
+ *   retry: {
+ *     maxRetries: 3,
+ *     retryDelay: 1000,
+ *     exponentialBackoff: true
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link NodeExecutionResult} for return type options
+ * @see {@link FlowCondition} for conditional execution
+ */
+export type FlowNode<TInput = unknown, TOutput = unknown, TError = UploadistaError> = FlowNodeData & {
+    inputSchema: z.ZodSchema<TInput>;
+    outputSchema: z.ZodSchema<TOutput>;
+    run: (args: {
+        data: TInput;
+        jobId: string;
+        storageId: string;
+        flowId: string;
+        inputs?: Record<string, unknown>;
+        clientId: string | null;
+    }) => Effect.Effect<NodeExecutionResult<TOutput>, TError>;
+    condition?: {
+        field: string;
+        operator: string;
+        value: unknown;
+    };
+    multiInput?: boolean;
+    multiOutput?: boolean;
+    pausable?: boolean;
+    retry?: {
+        maxRetries?: number;
+        retryDelay?: number;
+        exponentialBackoff?: boolean;
+    };
+};
+/**
+ * Represents a directed edge connecting two nodes in the flow graph.
+ *
+ * Edges define the data flow direction and can specify ports for multi-input/output nodes.
+ *
+ * @property source - ID of the source node
+ * @property target - ID of the target node
+ * @property sourcePort - Optional output port name for multi-output nodes
+ * @property targetPort - Optional input port name for multi-input nodes
+ *
+ * @remarks
+ * - Edges must not create cycles (DAG constraint)
+ * - Source node's output type should be compatible with target node's input type
+ * - Ports allow routing specific outputs to specific inputs
+ *
+ * @example
+ * ```typescript
+ * // Simple edge
+ * const edge: FlowEdge = {
+ *   source: "resize-node",
+ *   target: "optimize-node"
+ * };
+ *
+ * // Edge with ports (for multiplex nodes)
+ * const multiplexEdge: FlowEdge = {
+ *   source: "multiplex-node",
+ *   target: "output-node",
+ *   sourcePort: "image",
+ *   targetPort: "primary"
+ * };
+ * ```
+ */
+export type FlowEdge = {
+    source: string;
+    target: string;
+    sourcePort?: string;
+    targetPort?: string;
+};
+/**
+ * Function type for checking schema compatibility between nodes.
+ *
+ * @param from - Source node's output schema
+ * @param to - Target node's input schema
+ * @returns true if schemas are compatible
+ *
+ * @remarks
+ * Custom type checkers can implement more sophisticated compatibility rules
+ * than the default checker.
+ *
+ * @see {@link FlowTypeValidator} for the default implementation
+ */
+export type TypeCompatibilityChecker = (from: z.ZodSchema<any>, to: z.ZodSchema<any>) => boolean;
+/**
+ * Interface for validating node connections and schema compatibility.
+ *
+ * @remarks
+ * Validators ensure that connected nodes have compatible types,
+ * preventing runtime type errors in flow execution.
+ *
+ * @see {@link FlowTypeValidator} for the implementation
+ */
+export type NodeConnectionValidator = {
+    validateConnection: (sourceNode: FlowNode<any, any>, targetNode: FlowNode<any, any>, edge: FlowEdge) => boolean;
+    getCompatibleTypes: (sourceSchema: z.ZodSchema<any>, targetSchema: z.ZodSchema<any>) => boolean;
+};
+/**
+ * Configuration object for creating a new flow.
+ *
+ * FlowConfig defines all aspects of a flow including its nodes, connections,
+ * schemas, and optional features like event handlers and parallel execution.
+ *
+ * @template TFlowInputSchema - Zod schema for flow inputs
+ * @template TFlowOutputSchema - Zod schema for flow outputs
+ * @template TNodeError - Union of possible errors from node Effects
+ * @template TNodeRequirements - Union of requirements from node Effects
+ *
+ * @property flowId - Unique identifier for the flow
+ * @property name - Human-readable flow name
+ * @property nodes - Array of nodes (can be plain nodes or Effects resolving to nodes)
+ * @property edges - Array of edges connecting the nodes
+ * @property inputSchema - Zod schema for validating flow inputs
+ * @property outputSchema - Zod schema for validating flow outputs
+ * @property typeChecker - Optional custom type compatibility checker
+ * @property onEvent - Optional event handler for monitoring execution
+ * @property parallelExecution - Optional parallel execution configuration
+ *
+ * @remarks
+ * - Nodes can be provided as plain objects or Effect-wrapped for lazy initialization
+ * - Event handlers receive all flow and node events
+ * - Parallel execution is experimental and disabled by default
+ * - Type checker allows custom schema compatibility rules
+ *
+ * @example
+ * ```typescript
+ * const config: FlowConfig<
+ *   z.ZodObject<{ file: z.ZodType<File> }>,
+ *   z.ZodType<UploadFile>,
+ *   never,
+ *   never
+ * > = {
+ *   flowId: "image-upload",
+ *   name: "Image Upload 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,
+ *   onEvent: (event) => Effect.gen(function* () {
+ *     yield* logEvent(event);
+ *     return { eventId: event.jobId };
+ *   })
+ * };
+ * ```
+ *
+ * @see {@link createFlowWithSchema} for creating flows from config
+ * @see {@link FlowNode} for node specifications
+ * @see {@link FlowEdge} for edge specifications
+ */
+export type FlowConfig<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema extends z.ZodSchema<any>, TNodeError = never, TNodeRequirements = never> = {
+    flowId: string;
+    name: string;
+    nodes: Array<FlowNode<any, any, UploadistaError> | Effect.Effect<FlowNode<any, any, UploadistaError>, TNodeError, TNodeRequirements>>;
+    edges: FlowEdge[];
+    inputSchema: TFlowInputSchema;
+    outputSchema: TFlowOutputSchema;
+    typeChecker?: TypeCompatibilityChecker;
+    onEvent?: (event: FlowEvent) => Effect.Effect<{
+        eventId: string | null;
+    }, UploadistaError>;
+    parallelExecution?: {
+        enabled?: boolean;
+        maxConcurrency?: number;
+    };
+};
+export { NodeType };
+export type { FlowEvent, FlowEventFlowEnd, FlowEventFlowStart };
+//# sourceMappingURL=flow-types.d.ts.map

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

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

package/dist/flow/types/flow-types.js

@@ -0,0 +1,52 @@
+/**
+ * Core flow type definitions and node specifications.
+ *
+ * This module defines the fundamental types for the Flow Engine, including node
+ * definitions, execution results, edges, and configuration. These types form the
+ * foundation of the DAG processing system.
+ *
+ * @module flow/types/flow-types
+ * @see {@link FlowNode} for node specification
+ * @see {@link FlowConfig} for flow configuration
+ */
+import { NodeType } from "../node";
+/**
+ * Helper function to create a complete node execution result.
+ *
+ * @template TOutput - Type of the output data
+ * @param data - The output data from the node
+ * @returns A complete execution result
+ *
+ * @example
+ * ```typescript
+ * return completeNodeExecution({
+ *   url: uploadedFile.url,
+ *   size: uploadedFile.size
+ * });
+ * ```
+ */
+export const completeNodeExecution = (data) => ({
+    type: "complete",
+    data,
+});
+/**
+ * Helper function to create a waiting node execution result.
+ *
+ * @param partialData - Optional partial data available so far
+ * @returns A waiting execution result that pauses the flow
+ *
+ * @example
+ * ```typescript
+ * // Wait for more upload chunks
+ * return waitingNodeExecution({
+ *   receivedBytes: currentSize,
+ *   totalBytes: expectedSize
+ * });
+ * ```
+ */
+export const waitingNodeExecution = (partialData) => ({
+    type: "waiting",
+    partialData,
+});
+// Re-export existing types for compatibility
+export { NodeType };

package/dist/flow/types/index.d.ts

@@ -0,0 +1,4 @@
+export type { FlowCondition } from "./flow-file";
+export * from "./flow-types";
+export * from "./type-validator";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/flow/types/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,cAAc,cAAc,CAAC;AAE7B,cAAc,kBAAkB,CAAC"}

package/dist/flow/types/index.js

@@ -0,0 +1,3 @@
+// Export all flow types
+export * from "./flow-types";
+export * from "./type-validator";

package/dist/flow/types/run-args.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Flow execution argument schemas and types.
+ *
+ * Defines and validates the arguments passed when running a flow,
+ * ensuring inputs are properly structured before execution begins.
+ *
+ * @module flow/types/run-args
+ */
+import { z } from "zod";
+/**
+ * Zod schema for validating flow run arguments.
+ *
+ * @property inputs - Record mapping input node IDs to their input data
+ *
+ * @example
+ * ```typescript
+ * const args = {
+ *   inputs: {
+ *     "input-node-1": { file: myFile, metadata: { ... } },
+ *     "input-node-2": { file: anotherFile }
+ *   }
+ * };
+ *
+ * // Validate before running
+ * const validated = runArgsSchema.parse(args);
+ * ```
+ */
+export declare const runArgsSchema: z.ZodObject<{
+    inputs: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, z.core.$strip>;
+/**
+ * Type representing validated flow run arguments.
+ *
+ * This type is inferred from the runArgsSchema and ensures type safety
+ * when passing inputs to flow execution.
+ */
+export type RunArgs = z.infer<typeof runArgsSchema>;
+//# sourceMappingURL=run-args.d.ts.map

package/dist/flow/types/run-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-args.d.ts","sourceRoot":"","sources":["../../../src/flow/types/run-args.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,aAAa;;iBAExB,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/flow/types/run-args.js

@@ -0,0 +1,30 @@
+/**
+ * Flow execution argument schemas and types.
+ *
+ * Defines and validates the arguments passed when running a flow,
+ * ensuring inputs are properly structured before execution begins.
+ *
+ * @module flow/types/run-args
+ */
+import { z } from "zod";
+/**
+ * Zod schema for validating flow run arguments.
+ *
+ * @property inputs - Record mapping input node IDs to their input data
+ *
+ * @example
+ * ```typescript
+ * const args = {
+ *   inputs: {
+ *     "input-node-1": { file: myFile, metadata: { ... } },
+ *     "input-node-2": { file: anotherFile }
+ *   }
+ * };
+ *
+ * // Validate before running
+ * const validated = runArgsSchema.parse(args);
+ * ```
+ */
+export const runArgsSchema = z.object({
+    inputs: z.record(z.string(), z.any()),
+});

package/dist/flow/types/type-validator.d.ts

@@ -0,0 +1,26 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: any is used to allow for dynamic types */
+import type { z } from "zod";
+import type { FlowEdge, FlowNode, NodeConnectionValidator, TypeCompatibilityChecker } from "./flow-types";
+export declare const defaultTypeChecker: TypeCompatibilityChecker;
+export declare class FlowTypeValidator implements NodeConnectionValidator {
+    private typeChecker;
+    constructor(typeChecker?: TypeCompatibilityChecker);
+    validateConnection(sourceNode: FlowNode<any, any>, targetNode: FlowNode<any, any>, _edge: FlowEdge): boolean;
+    getCompatibleTypes(sourceSchema: z.ZodSchema<any>, targetSchema: z.ZodSchema<any>): boolean;
+    validateFlow(nodes: FlowNode<any, any>[], edges: FlowEdge[]): {
+        isValid: boolean;
+        errors: string[];
+    };
+    getExpectedInputSchemas(nodeId: string, nodes: FlowNode<any, any>[], edges: FlowEdge[]): Record<string, unknown>;
+    getActualOutputSchemas(nodeId: string, nodes: FlowNode<any, any>[], edges: FlowEdge[]): Record<string, unknown>;
+    validateData(data: unknown, schema: unknown): {
+        isValid: boolean;
+        errors: string[];
+    };
+}
+export declare const typeUtils: {
+    isAssignable(fromSchema: z.ZodSchema<any>, toSchema: z.ZodSchema<any>): boolean;
+    getCommonSchema(schema1: z.ZodSchema<any>, schema2: z.ZodSchema<any>): z.ZodSchema<any>;
+    matchesSchema(value: unknown, schema: z.ZodSchema<any>): boolean;
+};
+//# sourceMappingURL=type-validator.d.ts.map

package/dist/flow/types/type-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-validator.d.ts","sourceRoot":"","sources":["../../../src/flow/types/type-validator.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EACV,QAAQ,EACR,QAAQ,EACR,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,cAAc,CAAC;AAGtB,eAAO,MAAM,kBAAkB,EAAE,wBAyBhC,CAAC;AAGF,qBAAa,iBAAkB,YAAW,uBAAuB;IAC/D,OAAO,CAAC,WAAW,CAA2B;gBAElC,WAAW,GAAE,wBAA6C;IAItE,kBAAkB,CAChB,UAAU,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAC9B,UAAU,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAC9B,KAAK,EAAE,QAAQ,GACd,OAAO;IAQV,kBAAkB,CAChB,YAAY,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAC9B,YAAY,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAC7B,OAAO;IAKV,YAAY,CACV,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAC3B,KAAK,EAAE,QAAQ,EAAE,GAChB;QACD,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB;IAgCD,uBAAuB,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAC3B,KAAK,EAAE,QAAQ,EAAE,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAkB1B,sBAAsB,CACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAC3B,KAAK,EAAE,QAAQ,EAAE,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAkB1B,YAAY,CACV,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,OAAO,GACd;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;CAmB1C;AAGD,eAAO,MAAM,SAAS;6BAGN,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,YAClB,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GACzB,OAAO;6BAMC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,WAChB,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GACxB,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC;yBASE,OAAO,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,OAAO;CAQjE,CAAC"}

package/dist/flow/types/type-validator.js

@@ -0,0 +1,134 @@
+// Default type compatibility checker using Zod schemas
+export const defaultTypeChecker = (fromSchema, toSchema) => {
+    // Basic schema compatibility rules
+    if (fromSchema === toSchema)
+        return true;
+    // Check if schemas are compatible by comparing their types
+    try {
+        // For now, assume schemas are compatible if they're both Zod schemas
+        // In a more sophisticated system, you'd check actual schema compatibility
+        if (fromSchema &&
+            toSchema &&
+            typeof fromSchema === "object" &&
+            typeof toSchema === "object") {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        // If schema comparison fails, assume compatible
+        return true;
+    }
+};
+// Enhanced type validator with Zod schema support
+export class FlowTypeValidator {
+    typeChecker;
+    constructor(typeChecker = defaultTypeChecker) {
+        this.typeChecker = typeChecker;
+    }
+    validateConnection(sourceNode, targetNode, _edge) {
+        // Check if source node output schema is compatible with target node input schema
+        return this.getCompatibleTypes(sourceNode.outputSchema, targetNode.inputSchema);
+    }
+    getCompatibleTypes(sourceSchema, targetSchema) {
+        return this.typeChecker(sourceSchema, targetSchema);
+    }
+    // Validate entire flow for type compatibility
+    validateFlow(nodes, edges) {
+        const errors = [];
+        const nodeMap = new Map(nodes.map((node) => [node.id, node]));
+        for (const edge of edges) {
+            const sourceNode = nodeMap.get(edge.source);
+            const targetNode = nodeMap.get(edge.target);
+            if (!sourceNode) {
+                errors.push(`Source node ${edge.source} not found`);
+                continue;
+            }
+            if (!targetNode) {
+                errors.push(`Target node ${edge.target} not found`);
+                continue;
+            }
+            if (!this.validateConnection(sourceNode, targetNode, edge)) {
+                errors.push(`Schema mismatch: ${sourceNode.id} output schema incompatible with ${targetNode.id} input schema`);
+            }
+        }
+        return {
+            isValid: errors.length === 0,
+            errors,
+        };
+    }
+    // Get expected input schemas for a node based on its incoming edges
+    getExpectedInputSchemas(nodeId, nodes, edges) {
+        const nodeMap = new Map(nodes.map((node) => [node.id, node]));
+        const expectedSchemas = {};
+        for (const edge of edges) {
+            if (edge.target === nodeId) {
+                const sourceNode = nodeMap.get(edge.source);
+                if (sourceNode) {
+                    const portKey = edge.sourcePort || edge.source;
+                    expectedSchemas[portKey] = sourceNode.outputSchema;
+                }
+            }
+        }
+        return expectedSchemas;
+    }
+    // Get actual output schemas for a node based on its outgoing edges
+    getActualOutputSchemas(nodeId, nodes, edges) {
+        const nodeMap = new Map(nodes.map((node) => [node.id, node]));
+        const actualSchemas = {};
+        for (const edge of edges) {
+            if (edge.source === nodeId) {
+                const targetNode = nodeMap.get(edge.target);
+                if (targetNode) {
+                    const portKey = edge.targetPort || edge.target;
+                    actualSchemas[portKey] = targetNode.inputSchema;
+                }
+            }
+        }
+        return actualSchemas;
+    }
+    // Validate data against a schema
+    validateData(data, schema) {
+        try {
+            schema.parse(data);
+            return { isValid: true, errors: [] };
+        }
+        catch (error) {
+            if (error instanceof Error && "errors" in error) {
+                return {
+                    isValid: false,
+                    errors: error.errors.map((err) => `${err.path.join(".")}: ${err.message}`),
+                };
+            }
+            return {
+                isValid: false,
+                errors: [error instanceof Error ? error.message : "Validation failed"],
+            };
+        }
+    }
+}
+// Utility functions for common type checks
+export const typeUtils = {
+    // Check if a schema is assignable to another
+    isAssignable(fromSchema, toSchema) {
+        return defaultTypeChecker(fromSchema, toSchema);
+    },
+    // Get the most specific common schema
+    getCommonSchema(schema1, schema2) {
+        if (schema1 === schema2)
+            return schema1;
+        // For now, return the more specific schema or schema1
+        // In a more sophisticated system, you'd compute the intersection
+        return schema1;
+    },
+    // Check if a value matches a schema
+    matchesSchema(value, schema) {
+        try {
+            schema.parse(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};

package/dist/flow/utils/resolve-upload-metadata.d.ts

@@ -0,0 +1,11 @@
+import type { UploadFile } from "../../types";
+type FileMetadata = UploadFile["metadata"];
+export type ResolvedUploadMetadata = {
+    type: string;
+    fileName: string;
+    metadata: FileMetadata;
+    metadataJson: string | undefined;
+};
+export declare function resolveUploadMetadata(metadata: FileMetadata): ResolvedUploadMetadata;
+export {};
+//# sourceMappingURL=resolve-upload-metadata.d.ts.map

package/dist/flow/utils/resolve-upload-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-upload-metadata.d.ts","sourceRoot":"","sources":["../../../src/flow/utils/resolve-upload-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,KAAK,YAAY,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;AAE3C,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,GACrB,sBAAsB,CAkCxB"}

package/dist/flow/utils/resolve-upload-metadata.js

@@ -0,0 +1,28 @@
+export function resolveUploadMetadata(metadata) {
+    if (!metadata) {
+        return {
+            type: "",
+            fileName: "",
+            metadata: undefined,
+            metadataJson: undefined,
+        };
+    }
+    const normalized = { ...metadata };
+    const type = String(normalized.type || normalized.mimeType || normalized["content-type"] || "");
+    if (type) {
+        normalized.type ||= type;
+        normalized.mimeType ||= type;
+    }
+    const fileName = String(normalized.fileName || normalized.originalName || normalized.name || "");
+    if (fileName) {
+        normalized.fileName ||= fileName;
+        normalized.originalName ||= fileName;
+        normalized.name ||= fileName;
+    }
+    return {
+        type,
+        fileName,
+        metadata: normalized,
+        metadataJson: JSON.stringify(normalized),
+    };
+}