@uploadista/core 0.0.2 → 0.0.3

package/dist/index-0xq1cArb.d.cts

@@ -0,0 +1,4132 @@
+import { n as UploadistaError } from "./uploadista-error-CAtkQiAv.cjs";
+import { l as GenerateId, p as GenerateIdShape } from "./index-GLPiXqj4.cjs";
+import * as effect_Types0 from "effect/Types";
+import * as effect_Cause0 from "effect/Cause";
+import { Context, Effect, Layer, Stream } from "effect";
+import z$1, { z } from "zod";
+
+//#region src/flow/node.d.ts
+/**
+ * Defines the type of node in a flow, determining its role in the processing pipeline.
+ */
+declare enum NodeType {
+  /** Entry point for data into the flow */
+  input = "input",
+  /** Transforms data during flow execution */
+  process = "process",
+  /** Saves data to storage backends */
+  output = "output",
+  /** Routes data based on conditions */
+  conditional = "conditional",
+  /** Splits data to multiple outputs */
+  multiplex = "multiplex",
+  /** Combines multiple inputs into one output */
+  merge = "merge",
+}
+/**
+ * Fields that can be evaluated in conditional node conditions.
+ * These fields are typically found in file metadata.
+ */
+type ConditionField = "mimeType" | "size" | "width" | "height" | "extension";
+/**
+ * Operators available for comparing values in conditional node conditions.
+ */
+type ConditionOperator = "equals" | "notEquals" | "greaterThan" | "lessThan" | "contains" | "startsWith";
+/**
+ * Value used in conditional node comparisons.
+ * Can be either a string or number depending on the field being evaluated.
+ */
+type ConditionValue = string | number;
+/**
+ * Creates a flow node with automatic input/output validation and retry logic.
+ *
+ * Flow nodes are the building blocks of processing pipelines. Each node:
+ * - Validates its input against a Zod schema
+ * - Executes its processing logic
+ * - Validates its output against a Zod schema
+ * - Can optionally retry on failure with exponential backoff
+ *
+ * @template Input - The expected input type for this node
+ * @template Output - The output type produced by this node
+ *
+ * @param config - Node configuration
+ * @param config.id - Unique identifier for this node in the flow
+ * @param config.name - Human-readable name for the node
+ * @param config.description - Description of what this node does
+ * @param config.type - The type of node (input, process, output, conditional, multiplex, merge)
+ * @param config.inputSchema - Zod schema for validating input data
+ * @param config.outputSchema - Zod schema for validating output data
+ * @param config.run - The processing function to execute for this node
+ * @param config.condition - Optional condition for conditional nodes to determine if they should execute
+ * @param config.multiInput - If true, node receives all inputs as a record instead of a single input
+ * @param config.multiOutput - If true, node can output to multiple targets
+ * @param config.pausable - If true, node can pause execution and wait for additional data
+ * @param config.retry - Optional retry configuration for handling transient failures
+ * @param config.retry.maxRetries - Maximum number of retry attempts (default: 0)
+ * @param config.retry.retryDelay - Base delay in milliseconds between retries (default: 1000)
+ * @param config.retry.exponentialBackoff - Whether to use exponential backoff for retries (default: true)
+ *
+ * @returns An Effect that succeeds with the created FlowNode
+ *
+ * @example
+ * ```typescript
+ * const resizeNode = createFlowNode({
+ *   id: "resize-1",
+ *   name: "Resize Image",
+ *   description: "Resizes images to 800x600",
+ *   type: NodeType.process,
+ *   inputSchema: z.object({
+ *     stream: z.instanceof(Uint8Array),
+ *     metadata: z.object({ width: z.number(), height: z.number() })
+ *   }),
+ *   outputSchema: z.object({
+ *     stream: z.instanceof(Uint8Array),
+ *     metadata: z.object({ width: z.literal(800), height: z.literal(600) })
+ *   }),
+ *   run: ({ data }) => Effect.gen(function* () {
+ *     const resized = yield* resizeImage(data.stream, 800, 600);
+ *     return {
+ *       type: "complete",
+ *       data: { stream: resized, metadata: { width: 800, height: 600 } }
+ *     };
+ *   }),
+ *   retry: {
+ *     maxRetries: 3,
+ *     retryDelay: 1000,
+ *     exponentialBackoff: true
+ *   }
+ * });
+ * ```
+ */
+declare function createFlowNode<Input, Output>({
+  id,
+  name,
+  description,
+  type,
+  inputSchema,
+  outputSchema,
+  run,
+  condition,
+  multiInput,
+  multiOutput,
+  pausable,
+  retry
+}: {
+  id: string;
+  name: string;
+  description: string;
+  type: NodeType;
+  inputSchema: z.ZodSchema<Input>;
+  outputSchema: z.ZodSchema<Output>;
+  run: (args: {
+    data: Input;
+    jobId: string;
+    storageId: string;
+    flowId: string;
+    clientId: string | null;
+  }) => Effect.Effect<NodeExecutionResult<Output>, UploadistaError>;
+  condition?: {
+    field: ConditionField;
+    operator: ConditionOperator;
+    value: ConditionValue;
+  };
+  multiInput?: boolean;
+  multiOutput?: boolean;
+  pausable?: boolean;
+  retry?: {
+    maxRetries?: number;
+    retryDelay?: number;
+    exponentialBackoff?: boolean;
+  };
+}): Effect.Effect<FlowNode<Input, Output, UploadistaError>>;
+/**
+ * Extracts serializable node metadata from a FlowNode instance.
+ *
+ * This function is useful for serializing flow configurations or
+ * transmitting node information over the network without including
+ * the executable run function or schemas.
+ *
+ * @param node - The flow node to extract data from
+ * @returns A plain object containing the node's metadata (id, name, description, type)
+ */
+declare const getNodeData: (node: FlowNode<any, any, UploadistaError>) => FlowNodeData;
+//#endregion
+//#region src/flow/event.d.ts
+/**
+ * Enumeration of all possible flow and node execution event types.
+ *
+ * Events follow a lifecycle pattern:
+ * - Job level: JobStart → ... → JobEnd
+ * - Flow level: FlowStart → ... → (FlowEnd | FlowError)
+ * - Node level: NodeStart → ... → (NodeEnd | NodePause | NodeError)
+ *
+ * @example
+ * ```typescript
+ * // Listen for flow completion
+ * if (event.eventType === EventType.FlowEnd) {
+ *   console.log("Flow completed:", event.result);
+ * }
+ * ```
+ */
+declare enum EventType {
+  /** Emitted when a job starts execution */
+  JobStart = "job-start",
+  /** Emitted when a job completes (success or failure) */
+  JobEnd = "job-end",
+  /** Emitted when a flow begins execution */
+  FlowStart = "flow-start",
+  /** Emitted when a flow completes successfully */
+  FlowEnd = "flow-end",
+  /** Emitted when a flow encounters an error */
+  FlowError = "flow-error",
+  /** Emitted when a node starts processing */
+  NodeStart = "node-start",
+  /** Emitted when a node completes successfully */
+  NodeEnd = "node-end",
+  /** Emitted when a node pauses (waiting for additional data) */
+  NodePause = "node-pause",
+  /** Emitted when a paused node resumes execution */
+  NodeResume = "node-resume",
+  /** Emitted when a node encounters an error */
+  NodeError = "node-error",
+  /** Emitted for streaming node data (e.g., progress updates) */
+  NodeStream = "node-stream",
+  /** Emitted for node response data */
+  NodeResponse = "node-response",
+}
+/**
+ * Event emitted when a job starts execution.
+ */
+type FlowEventJobStart = {
+  jobId: string;
+  eventType: EventType.JobStart;
+};
+/**
+ * Event emitted when a job completes (either successfully or with failure).
+ */
+type FlowEventJobEnd = {
+  jobId: string;
+  eventType: EventType.JobEnd;
+};
+/**
+ * Event emitted when a flow begins execution.
+ * This is the first event after JobStart in the execution lifecycle.
+ */
+type FlowEventFlowStart = {
+  jobId: string;
+  flowId: string;
+  eventType: EventType.FlowStart;
+};
+/**
+ * Event emitted when a flow completes successfully.
+ *
+ * @property result - The final output from all output nodes in the flow
+ */
+type FlowEventFlowEnd = {
+  jobId: string;
+  flowId: string;
+  eventType: EventType.FlowEnd;
+  result?: unknown;
+};
+/**
+ * Event emitted when a flow encounters an unrecoverable error.
+ *
+ * @property error - Error message describing what went wrong
+ */
+type FlowEventFlowError = {
+  jobId: string;
+  flowId: string;
+  eventType: EventType.FlowError;
+  error: string;
+};
+/**
+ * Event emitted when a node begins processing.
+ *
+ * @property nodeName - Human-readable node name
+ * @property nodeType - Type of node (input, transform, conditional, output, etc.)
+ */
+type FlowEventNodeStart = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodeStart;
+  nodeName: string;
+  nodeType: NodeType;
+};
+/**
+ * Event emitted when a node fails after all retry attempts.
+ *
+ * @property error - Error message from the failed execution
+ * @property retryCount - Number of retry attempts made before giving up
+ */
+type FlowEventNodeError = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  nodeName: string;
+  eventType: EventType.NodeError;
+  error: string;
+  retryCount?: number;
+};
+/**
+ * Event emitted when a node completes successfully.
+ *
+ * @property result - The output data produced by the node
+ */
+type FlowEventNodeEnd = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodeEnd;
+  nodeName: string;
+  result?: unknown;
+};
+/**
+ * Event emitted when a node pauses execution, waiting for additional data.
+ *
+ * This typically occurs with input nodes that need more chunks or nodes
+ * waiting for external services.
+ *
+ * @property partialData - Any partial result available before pausing
+ */
+type FlowEventNodePause = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodePause;
+  nodeName: string;
+  partialData?: unknown;
+};
+/**
+ * Event emitted when a paused node resumes execution.
+ *
+ * This occurs after providing the additional data needed by a paused node.
+ */
+type FlowEventNodeResume = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodeResume;
+  nodeName: string;
+  nodeType: NodeType;
+};
+/**
+ * Event emitted for node-specific response data.
+ *
+ * Used for streaming intermediate results or progress updates.
+ */
+type FlowEventNodeResponse = {
+  jobId: string;
+  flowId: string;
+  nodeId: string;
+  eventType: EventType.NodeResponse;
+  nodeName: string;
+  data: unknown;
+};
+/**
+ * Union of all possible flow execution events.
+ *
+ * This discriminated union allows type-safe event handling based on eventType.
+ *
+ * @example
+ * ```typescript
+ * function handleFlowEvent(event: FlowEvent) {
+ *   switch (event.eventType) {
+ *     case EventType.FlowStart:
+ *       console.log("Flow started:", event.flowId);
+ *       break;
+ *     case EventType.NodeEnd:
+ *       console.log("Node completed:", event.nodeName, event.result);
+ *       break;
+ *     case EventType.FlowError:
+ *       console.error("Flow failed:", event.error);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+type FlowEvent = FlowEventJobStart | FlowEventJobEnd | FlowEventFlowStart | FlowEventFlowEnd | FlowEventFlowError | FlowEventNodeStart | FlowEventNodeEnd | FlowEventNodePause | FlowEventNodeResume | FlowEventNodeError;
+//#endregion
+//#region src/flow/types/flow-types.d.ts
+/**
+ * Type mapping for node input/output schemas.
+ * Used for type-safe node connections in typed flows.
+ */
+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.)
+ */
+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 });
+ * }
+ * ```
+ */
+type NodeExecutionResult<TOutput$1> = {
+  type: "complete";
+  data: TOutput$1;
+} | {
+  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
+ * });
+ * ```
+ */
+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
+ * });
+ * ```
+ */
+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
+ */
+type FlowNode<TInput = unknown, TOutput$1 = unknown, TError$1 = UploadistaError> = FlowNodeData & {
+  inputSchema: z.ZodSchema<TInput>;
+  outputSchema: z.ZodSchema<TOutput$1>;
+  run: (args: {
+    data: TInput;
+    jobId: string;
+    storageId: string;
+    flowId: string;
+    inputs?: Record<string, unknown>;
+    clientId: string | null;
+  }) => Effect.Effect<NodeExecutionResult<TOutput$1>, TError$1>;
+  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"
+ * };
+ * ```
+ */
+type FlowEdge$1 = {
+  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
+ */
+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
+ */
+type NodeConnectionValidator = {
+  validateConnection: (sourceNode: FlowNode<any, any>, targetNode: FlowNode<any, any>, edge: FlowEdge$1) => 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
+ */
+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$1[];
+  inputSchema: TFlowInputSchema;
+  outputSchema: TFlowOutputSchema;
+  typeChecker?: TypeCompatibilityChecker;
+  onEvent?: (event: FlowEvent) => Effect.Effect<{
+    eventId: string | null;
+  }, UploadistaError>;
+  parallelExecution?: {
+    enabled?: boolean;
+    maxConcurrency?: number;
+  };
+};
+//#endregion
+//#region src/flow/edge.d.ts
+/**
+ * Represents a connection between two nodes in a flow, defining the data flow direction.
+ *
+ * Edges connect the output of a source node to the input of a target node,
+ * enabling data to flow through the processing pipeline in a directed acyclic graph (DAG).
+ */
+type FlowEdge = FlowEdge$1;
+/**
+ * Creates a flow edge connecting two nodes in a processing pipeline.
+ *
+ * Edges define how data flows between nodes. The data output from the source node
+ * becomes the input for the target node. For nodes with multiple inputs/outputs,
+ * ports can be specified to route data to specific connections.
+ *
+ * @param config - Edge configuration
+ * @param config.source - ID of the source node (data originates here)
+ * @param config.target - ID of the target node (data flows to here)
+ * @param config.sourcePort - Optional port name on the source node for multi-output nodes
+ * @param config.targetPort - Optional port name on the target node for multi-input nodes
+ *
+ * @returns A FlowEdge object representing the connection
+ *
+ * @example
+ * ```typescript
+ * // Simple edge connecting two nodes
+ * const edge = createFlowEdge({
+ *   source: "input-1",
+ *   target: "process-1"
+ * });
+ *
+ * // Edge with ports for multi-input/output nodes
+ * const portEdge = createFlowEdge({
+ *   source: "multiplex-1",
+ *   target: "merge-1",
+ *   sourcePort: "out-a",
+ *   targetPort: "in-1"
+ * });
+ * ```
+ */
+declare function createFlowEdge({
+  source,
+  target,
+  sourcePort,
+  targetPort
+}: {
+  source: string;
+  target: string;
+  sourcePort?: string;
+  targetPort?: string;
+}): FlowEdge;
+//#endregion
+//#region src/flow/flow.d.ts
+/**
+ * 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
+ */
+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);
+ * ```
+ */
+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, ... })
+ * }
+ * ```
+ */
+type FlowExecutionResult<TOutput$1> = {
+  type: "completed";
+  result: TOutput$1;
+} | {
+  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"
+ * });
+ * ```
+ */
+type Flow<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema extends z.ZodSchema<any>, TRequirements$1> = {
+  id: string;
+  name: string;
+  nodes: FlowNode<any, any, UploadistaError>[];
+  edges: FlowEdge[];
+  inputSchema: TFlowInputSchema;
+  outputSchema: TFlowOutputSchema;
+  onEvent?: FlowConfig<TFlowInputSchema, TFlowOutputSchema, TRequirements$1>["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$1>;
+  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$1>;
+  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
+ */
+declare function createFlowWithSchema<TFlowInputSchema extends z.ZodSchema<any>, TFlowOutputSchema extends z.ZodSchema<any>, TRequirements$1 = never, TNodeError = never, TNodeRequirements = never>(config: FlowConfig<TFlowInputSchema, TFlowOutputSchema, TNodeError, TNodeRequirements>): Effect.Effect<Flow<TFlowInputSchema, TFlowOutputSchema, TRequirements$1>, TNodeError, TNodeRequirements>;
+//#endregion
+//#region src/types/upload-file.d.ts
+/**
+ * Zod schema for validating UploadFile objects.
+ *
+ * This schema defines the structure and validation rules for upload file metadata.
+ * Use this schema to parse and validate UploadFile data from external sources.
+ *
+ * @see {@link UploadFile} for the TypeScript type
+ */
+declare const uploadFileSchema: z.ZodObject<{
+  id: z.ZodString;
+  size: z.ZodOptional<z.ZodNumber>;
+  offset: z.ZodNumber;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+  creationDate: z.ZodOptional<z.ZodString>;
+  url: z.ZodOptional<z.ZodString>;
+  sizeIsDeferred: z.ZodOptional<z.ZodBoolean>;
+  checksum: z.ZodOptional<z.ZodString>;
+  checksumAlgorithm: z.ZodOptional<z.ZodString>;
+  storage: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    uploadId: z.ZodOptional<z.ZodString>;
+    bucket: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Represents an uploaded file with its metadata and storage information.
+ *
+ * This is the core data structure that tracks file uploads throughout their lifecycle.
+ * It contains all metadata needed to resume uploads, track progress, and locate files
+ * in storage backends.
+ *
+ * @property id - Unique identifier for this upload
+ * @property offset - Current byte offset (how many bytes have been uploaded)
+ * @property storage - Storage backend information
+ * @property storage.id - Storage backend identifier (e.g., "s3-production")
+ * @property storage.type - Storage backend type (e.g., "s3", "azure", "gcs")
+ * @property storage.path - Optional path prefix within the storage backend
+ * @property storage.uploadId - Optional backend-specific upload ID (e.g., S3 multipart upload ID)
+ * @property storage.bucket - Optional bucket or container name
+ * @property flow - Optional flow processing information (when file is part of a flow)
+ * @property flow.flowId - ID of the flow processing this file
+ * @property flow.nodeId - ID of the flow node that created this file
+ * @property flow.jobId - ID of the flow job execution
+ * @property size - Total file size in bytes (undefined if deferred)
+ * @property metadata - Custom key-value metadata attached to the file
+ * @property creationDate - ISO 8601 timestamp when upload was created
+ * @property url - Optional public URL to access the file
+ * @property sizeIsDeferred - True if file size is not known at upload start
+ * @property checksum - Optional file checksum/hash value
+ * @property checksumAlgorithm - Algorithm used for checksum (e.g., "md5", "sha256")
+ *
+ * @example
+ * ```typescript
+ * // Create an UploadFile for a new upload
+ * const uploadFile: UploadFile = {
+ *   id: "upload_abc123",
+ *   offset: 0,
+ *   size: 1024000,
+ *   storage: {
+ *     id: "s3-production",
+ *     type: "s3",
+ *     bucket: "my-uploads",
+ *     path: "files/"
+ *   },
+ *   metadata: {
+ *     fileName: "image.jpg",
+ *     contentType: "image/jpeg",
+ *     userId: "user_123"
+ *   },
+ *   creationDate: new Date().toISOString(),
+ *   checksum: "5d41402abc4b2a76b9719d911017c592",
+ *   checksumAlgorithm: "md5"
+ * };
+ *
+ * // UploadFile with flow processing
+ * const flowFile: UploadFile = {
+ *   id: "upload_xyz789",
+ *   offset: 0,
+ *   size: 2048000,
+ *   storage: {
+ *     id: "s3-temp",
+ *     type: "s3",
+ *     bucket: "temp-processing"
+ *   },
+ *   flow: {
+ *     flowId: "flow_resize_optimize",
+ *     nodeId: "input_1",
+ *     jobId: "job_456"
+ *   }
+ * };
+ *
+ * // Resume an interrupted upload
+ * const resumingFile: UploadFile = {
+ *   id: "upload_resume",
+ *   offset: 524288, // Already uploaded 512KB
+ *   size: 1024000,
+ *   storage: {
+ *     id: "s3-production",
+ *     type: "s3",
+ *     uploadId: "multipart_xyz" // S3 multipart upload ID
+ *   }
+ * };
+ * ```
+ */
+type UploadFile = {
+  id: string;
+  offset: number;
+  storage: {
+    id: string;
+    type: string;
+    path?: string | undefined;
+    uploadId?: string | undefined;
+    bucket?: string | undefined;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  };
+  size?: number | undefined;
+  metadata?: Record<string, string | number | boolean> | undefined;
+  creationDate?: string | undefined;
+  url?: string | undefined;
+  sizeIsDeferred?: boolean | undefined;
+  checksum?: string | undefined;
+  checksumAlgorithm?: string | undefined;
+};
+//#endregion
+//#region src/types/kv-store.d.ts
+/**
+ * Base key-value store interface for raw string storage.
+ *
+ * This is the low-level interface that storage adapters implement.
+ * It stores raw string values without type safety or serialization.
+ *
+ * @property get - Retrieves a value by key, returns null if not found
+ * @property set - Stores a value with the given key
+ * @property delete - Removes a value by key
+ * @property list - Optional operation to list all keys with a given prefix
+ *
+ * @example
+ * ```typescript
+ * // Implement a BaseKvStore with Redis
+ * const redisKvStore: BaseKvStore = {
+ *   get: (key) => Effect.tryPromise({
+ *     try: () => redis.get(key),
+ *     catch: (error) => UploadistaError.fromCode("UNKNOWN_ERROR", { cause: error })
+ *   }),
+ *
+ *   set: (key, value) => Effect.tryPromise({
+ *     try: () => redis.set(key, value),
+ *     catch: (error) => UploadistaError.fromCode("UNKNOWN_ERROR", { cause: error })
+ *   }),
+ *
+ *   delete: (key) => Effect.tryPromise({
+ *     try: () => redis.del(key),
+ *     catch: (error) => UploadistaError.fromCode("UNKNOWN_ERROR", { cause: error })
+ *   }),
+ *
+ *   list: (prefix) => Effect.tryPromise({
+ *     try: () => redis.keys(`${prefix}*`),
+ *     catch: (error) => UploadistaError.fromCode("UNKNOWN_ERROR", { cause: error })
+ *   })
+ * };
+ * ```
+ */
+interface BaseKvStore {
+  readonly get: (key: string) => Effect.Effect<string | null, UploadistaError>;
+  readonly set: (key: string, value: string) => Effect.Effect<void, UploadistaError>;
+  readonly delete: (key: string) => Effect.Effect<void, UploadistaError>;
+  readonly list?: (keyPrefix: string) => Effect.Effect<Array<string>, UploadistaError>;
+}
+/**
+ * Type-safe key-value store interface with automatic serialization.
+ *
+ * This wraps a BaseKvStore and handles JSON serialization/deserialization
+ * for a specific data type, providing type safety and eliminating the need
+ * for manual JSON.stringify/parse calls.
+ *
+ * @template TData - The type of data stored in this KV store
+ *
+ * @property get - Retrieves and deserializes a value, fails if not found
+ * @property set - Serializes and stores a value
+ * @property delete - Removes a value by key
+ * @property list - Optional operation to list all keys (without prefix)
+ *
+ * @example
+ * ```typescript
+ * // Use a typed KV store
+ * const uploadStore: KvStore<UploadFile> = new TypedKvStore(
+ *   baseStore,
+ *   "uploads:",
+ *   jsonSerializer.serialize,
+ *   jsonSerializer.deserialize
+ * );
+ *
+ * // Store and retrieve typed data
+ * const program = Effect.gen(function* () {
+ *   const file: UploadFile = {
+ *     id: "file123",
+ *     offset: 0,
+ *     storage: { id: "s3", type: "s3" }
+ *   };
+ *
+ *   // Automatic serialization
+ *   yield* uploadStore.set("file123", file);
+ *
+ *   // Automatic deserialization with type safety
+ *   const retrieved = yield* uploadStore.get("file123");
+ *   console.log(retrieved.offset); // TypeScript knows this is a number
+ * });
+ * ```
+ */
+type KvStore<TData> = {
+  readonly get: (key: string) => Effect.Effect<TData, UploadistaError>;
+  readonly set: (key: string, value: TData) => Effect.Effect<void, UploadistaError>;
+  readonly delete: (key: string) => Effect.Effect<void, UploadistaError>;
+  readonly list?: () => Effect.Effect<Array<string>, UploadistaError>;
+};
+/**
+ * Typed wrapper class that adds serialization to a BaseKvStore.
+ *
+ * This class implements the KvStore interface by wrapping a BaseKvStore
+ * and handling serialization/deserialization for a specific type. It also
+ * adds a key prefix to isolate different data types in the same store.
+ *
+ * @template TData - The type of data to store
+ *
+ * @example
+ * ```typescript
+ * // Create a typed store for UploadFile
+ * const uploadFileStore = new TypedKvStore<UploadFile>(
+ *   baseKvStore,
+ *   "uploadista:upload-file:", // All keys will be prefixed
+ *   (data) => JSON.stringify(data),
+ *   (str) => JSON.parse(str) as UploadFile
+ * );
+ *
+ * // Use the store
+ * const effect = Effect.gen(function* () {
+ *   const file: UploadFile = { ... };
+ *   yield* uploadFileStore.set("abc123", file);
+ *   // Internally stores at key "uploadista:upload-file:abc123"
+ *
+ *   const retrieved = yield* uploadFileStore.get("abc123");
+ *   return retrieved;
+ * });
+ *
+ * // Custom serialization for binary data
+ * const binaryStore = new TypedKvStore<Uint8Array>(
+ *   baseKvStore,
+ *   "binary:",
+ *   (data) => btoa(String.fromCharCode(...data)), // Base64 encode
+ *   (str) => Uint8Array.from(atob(str), c => c.charCodeAt(0)) // Base64 decode
+ * );
+ * ```
+ */
+declare class TypedKvStore<TData> implements KvStore<TData> {
+  private baseStore;
+  private keyPrefix;
+  private serialize;
+  private deserialize;
+  constructor(baseStore: BaseKvStore, keyPrefix: string, serialize: (data: TData) => string, deserialize: (str: string) => TData);
+  get: (key: string) => Effect.Effect<TData, UploadistaError>;
+  set: (key: string, value: TData) => Effect.Effect<void, UploadistaError>;
+  delete: (key: string) => Effect.Effect<void, UploadistaError>;
+  list: () => Effect.Effect<Array<string>, UploadistaError>;
+}
+/**
+ * Default JSON serialization helpers.
+ *
+ * These functions provide standard JSON serialization for use with TypedKvStore.
+ * They work with any JSON-serializable type.
+ *
+ * @example
+ * ```typescript
+ * const store = new TypedKvStore<MyType>(
+ *   baseStore,
+ *   "mydata:",
+ *   jsonSerializer.serialize,
+ *   jsonSerializer.deserialize
+ * );
+ * ```
+ */
+declare const jsonSerializer: {
+  serialize: <T>(data: T) => string;
+  deserialize: <T>(str: string) => T;
+};
+declare const BaseKvStoreService_base: Context.TagClass<BaseKvStoreService, "BaseKvStore", BaseKvStore>;
+/**
+ * Effect-TS context tag for the base untyped KV store.
+ *
+ * This is the low-level store that storage adapter implementations provide.
+ * Most application code should use typed stores like UploadFileKVStore instead.
+ *
+ * @example
+ * ```typescript
+ * // Provide a base store implementation
+ * const baseStoreLayer = Layer.succeed(BaseKvStoreService, redisKvStore);
+ *
+ * // Use in an Effect
+ * const effect = Effect.gen(function* () {
+ *   const baseStore = yield* BaseKvStoreService;
+ *   yield* baseStore.set("raw-key", "raw-value");
+ * });
+ * ```
+ */
+declare class BaseKvStoreService extends BaseKvStoreService_base {}
+declare const UploadFileKVStore_base: Context.TagClass<UploadFileKVStore, "UploadFileKVStore", KvStore<UploadFile>>;
+/**
+ * Effect-TS context tag for the UploadFile typed KV store.
+ *
+ * This provides type-safe storage for UploadFile metadata. It's the primary
+ * way to store and retrieve upload metadata in the system.
+ *
+ * @example
+ * ```typescript
+ * const uploadEffect = Effect.gen(function* () {
+ *   const kvStore = yield* UploadFileKVStore;
+ *
+ *   // Store upload metadata
+ *   const file: UploadFile = {
+ *     id: "upload123",
+ *     offset: 0,
+ *     storage: { id: "s3", type: "s3" }
+ *   };
+ *   yield* kvStore.set("upload123", file);
+ *
+ *   // Retrieve with type safety
+ *   const retrieved = yield* kvStore.get("upload123");
+ *   return retrieved;
+ * });
+ * ```
+ */
+declare class UploadFileKVStore extends UploadFileKVStore_base {}
+/**
+ * Effect Layer that creates the UploadFileKVStore from a BaseKvStore.
+ *
+ * This layer automatically wires up JSON serialization for UploadFile objects
+ * with the "uploadista:upload-file:" key prefix.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const kvStore = yield* UploadFileKVStore;
+ *   // Use the store...
+ * }).pipe(
+ *   Effect.provide(uploadFileKvStore),
+ *   Effect.provide(baseStoreLayer)
+ * );
+ * ```
+ */
+declare const uploadFileKvStore: Layer.Layer<UploadFileKVStore, never, BaseKvStoreService>;
+declare const FlowJobKVStore_base: Context.TagClass<FlowJobKVStore, "FlowJobKVStore", KvStore<FlowJob>>;
+/**
+ * Effect-TS context tag for the FlowJob typed KV store.
+ *
+ * This provides type-safe storage for FlowJob metadata, tracking the
+ * execution state of flow processing jobs.
+ *
+ * @example
+ * ```typescript
+ * const flowEffect = Effect.gen(function* () {
+ *   const jobStore = yield* FlowJobKVStore;
+ *
+ *   // Store job state
+ *   const job: FlowJob = {
+ *     id: "job123",
+ *     flowId: "flow_resize",
+ *     status: "running",
+ *     tasks: [],
+ *     createdAt: new Date(),
+ *     updatedAt: new Date()
+ *   };
+ *   yield* jobStore.set("job123", job);
+ *
+ *   // Retrieve and check status
+ *   const retrieved = yield* jobStore.get("job123");
+ *   return retrieved.status;
+ * });
+ * ```
+ */
+declare class FlowJobKVStore extends FlowJobKVStore_base {}
+/**
+ * Effect Layer that creates the FlowJobKVStore from a BaseKvStore.
+ *
+ * This layer automatically wires up JSON serialization for FlowJob objects
+ * with the "uploadista:flow-job:" key prefix.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const jobStore = yield* FlowJobKVStore;
+ *   // Use the store...
+ * }).pipe(
+ *   Effect.provide(flowJobKvStore),
+ *   Effect.provide(baseStoreLayer)
+ * );
+ * ```
+ */
+declare const flowJobKvStore: Layer.Layer<FlowJobKVStore, never, BaseKvStoreService>;
+//#endregion
+//#region src/types/data-store.d.ts
+/**
+ * Options for writing data to a DataStore.
+ *
+ * @property file_id - Unique identifier for the file being written
+ * @property stream - Stream of byte chunks to write to storage
+ * @property offset - Byte offset where writing should begin (for resumable uploads)
+ */
+type DataStoreWriteOptions = {
+  file_id: string;
+  stream: Stream.Stream<Uint8Array, UploadistaError>;
+  offset: number;
+};
+/**
+ * Upload strategy type indicating how chunks are uploaded.
+ *
+ * - `single`: Upload file in a single request (traditional upload)
+ * - `parallel`: Upload file chunks in parallel (for large files)
+ */
+type UploadStrategy = "single" | "parallel";
+/**
+ * Capabilities and constraints of a DataStore implementation.
+ *
+ * This type describes what features a storage backend supports and what
+ * limitations it has. Use this to determine the optimal upload strategy
+ * and validate client requests.
+ *
+ * @property supportsParallelUploads - Can upload chunks in parallel (e.g., S3 multipart)
+ * @property supportsConcatenation - Can concatenate multiple uploads into one file
+ * @property supportsDeferredLength - Can start upload without knowing final size
+ * @property supportsResumableUploads - Can resume interrupted uploads from last offset
+ * @property supportsTransactionalUploads - Guarantees atomic upload success/failure
+ * @property maxConcurrentUploads - Maximum parallel upload parts (if parallel supported)
+ * @property minChunkSize - Minimum size in bytes for each chunk (except last)
+ * @property maxChunkSize - Maximum size in bytes for each chunk
+ * @property maxParts - Maximum number of parts in a multipart upload
+ * @property optimalChunkSize - Recommended chunk size for best performance
+ * @property requiresOrderedChunks - Must receive chunks in sequential order
+ * @property requiresMimeTypeValidation - Validates file MIME type matches declaration
+ * @property maxValidationSize - Maximum file size for MIME type validation
+ *
+ * @example
+ * ```typescript
+ * const capabilities = dataStore.getCapabilities();
+ *
+ * if (capabilities.supportsParallelUploads && fileSize > 10_000_000) {
+ *   // Use parallel upload for large files
+ *   const chunkSize = capabilities.optimalChunkSize || 5_242_880; // 5MB default
+ *   uploadInParallel(file, chunkSize);
+ * } else {
+ *   // Use single upload
+ *   uploadAsSingleChunk(file);
+ * }
+ * ```
+ */
+type DataStoreCapabilities = {
+  supportsParallelUploads: boolean;
+  supportsConcatenation: boolean;
+  supportsDeferredLength: boolean;
+  supportsResumableUploads: boolean;
+  supportsTransactionalUploads: boolean;
+  maxConcurrentUploads?: number;
+  minChunkSize?: number;
+  maxChunkSize?: number;
+  maxParts?: number;
+  optimalChunkSize?: number;
+  requiresOrderedChunks: boolean;
+  requiresMimeTypeValidation?: boolean;
+  maxValidationSize?: number;
+};
+/**
+ * Core interface for all storage backend implementations.
+ *
+ * DataStore abstracts file storage operations across different backends
+ * (S3, Azure Blob, GCS, local filesystem, etc.). All storage adapters
+ * must implement this interface.
+ *
+ * @template TData - The data type stored (typically UploadFile)
+ *
+ * @property bucket - Optional storage bucket or container name
+ * @property path - Optional base path prefix for all stored files
+ * @property create - Creates a new file record in storage
+ * @property remove - Deletes a file from storage
+ * @property read - Reads complete file contents as bytes
+ * @property write - Writes data stream to storage at specified offset
+ * @property deleteExpired - Optional cleanup of expired files
+ * @property getCapabilities - Returns storage backend capabilities
+ * @property validateUploadStrategy - Validates if strategy is supported
+ *
+ * @example
+ * ```typescript
+ * // Implement a custom DataStore
+ * const myDataStore: DataStore<UploadFile> = {
+ *   bucket: "my-uploads",
+ *   path: "files/",
+ *
+ *   create: (file) => Effect.gen(function* () {
+ *     // Store file metadata
+ *     yield* saveMetadata(file);
+ *     return file;
+ *   }),
+ *
+ *   write: ({ file_id, stream, offset }, { onProgress }) => Effect.gen(function* () {
+ *     // Write chunks to storage
+ *     let bytesWritten = offset;
+ *     yield* Stream.runForEach(stream, (chunk) => Effect.sync(() => {
+ *       writeChunk(file_id, chunk, bytesWritten);
+ *       bytesWritten += chunk.byteLength;
+ *       onProgress?.(chunk.byteLength);
+ *     }));
+ *     return bytesWritten;
+ *   }),
+ *
+ *   read: (file_id) => Effect.gen(function* () {
+ *     // Read complete file
+ *     const data = yield* readFromStorage(file_id);
+ *     return data;
+ *   }),
+ *
+ *   remove: (file_id) => Effect.gen(function* () {
+ *     yield* deleteFromStorage(file_id);
+ *   }),
+ *
+ *   getCapabilities: () => ({
+ *     supportsParallelUploads: true,
+ *     supportsConcatenation: false,
+ *     supportsDeferredLength: true,
+ *     supportsResumableUploads: true,
+ *     supportsTransactionalUploads: false,
+ *     maxConcurrentUploads: 10,
+ *     optimalChunkSize: 5_242_880, // 5MB
+ *     requiresOrderedChunks: false,
+ *   }),
+ *
+ *   validateUploadStrategy: (strategy) =>
+ *     Effect.succeed(strategy === "parallel" || strategy === "single"),
+ * };
+ * ```
+ */
+type DataStore<TData = unknown> = {
+  readonly bucket?: string;
+  readonly path?: string;
+  readonly create: (file: TData) => Effect.Effect<TData, UploadistaError>;
+  readonly remove: (file_id: string) => Effect.Effect<void, UploadistaError>;
+  readonly read: (file_id: string) => Effect.Effect<Uint8Array, UploadistaError>;
+  readonly write: (options: DataStoreWriteOptions, dependencies: {
+    onProgress?: (chunkSize: number) => void;
+  }) => Effect.Effect<number, UploadistaError>;
+  readonly deleteExpired?: Effect.Effect<number, UploadistaError>;
+  readonly getCapabilities: () => DataStoreCapabilities;
+  readonly validateUploadStrategy: (strategy: UploadStrategy) => Effect.Effect<boolean, never>;
+};
+declare const UploadFileDataStore_base: Context.TagClass<UploadFileDataStore, "UploadFileDataStore", DataStore<UploadFile>>;
+/**
+ * Effect-TS context tag for UploadFile DataStore.
+ *
+ * Use this tag to access the primary DataStore in an Effect context.
+ * This is the standard storage backend for uploaded files.
+ *
+ * @example
+ * ```typescript
+ * const uploadEffect = Effect.gen(function* () {
+ *   const dataStore = yield* UploadFileDataStore;
+ *   const file = yield* dataStore.create(uploadFile);
+ *   return file;
+ * });
+ * ```
+ */
+declare class UploadFileDataStore extends UploadFileDataStore_base {}
+declare const BufferedUploadFileDataStore_base: Context.TagClass<BufferedUploadFileDataStore, "BufferedUploadFileDataStore", DataStore<UploadFile>>;
+/**
+ * Effect-TS context tag for buffered/temporary DataStore.
+ *
+ * This is an optional storage backend used for temporary or intermediate files
+ * during flow processing. Not all implementations provide a buffered store.
+ *
+ * @example
+ * ```typescript
+ * const processEffect = Effect.gen(function* () {
+ *   const bufferedStore = yield* BufferedUploadFileDataStore;
+ *   // Store intermediate processing results
+ *   const tempFile = yield* bufferedStore.create(intermediateFile);
+ *   return tempFile;
+ * });
+ * ```
+ */
+declare class BufferedUploadFileDataStore extends BufferedUploadFileDataStore_base {}
+/**
+ * Service interface for managing multiple DataStore instances.
+ *
+ * This allows routing files to different storage backends based on
+ * storageId (e.g., different S3 buckets, Azure containers, or storage tiers).
+ *
+ * @property getDataStore - Retrieves the appropriate DataStore for a given storage ID
+ * @property bufferedDataStore - Optional temporary storage for intermediate files
+ */
+type UploadFileDataStoresShape = {
+  getDataStore: (storageId: string, clientId: string | null) => Effect.Effect<DataStore<UploadFile>, UploadistaError>;
+  bufferedDataStore: Effect.Effect<DataStore<UploadFile> | undefined, UploadistaError>;
+};
+declare const UploadFileDataStores_base: Context.TagClass<UploadFileDataStores, "UploadFileDataStores", UploadFileDataStoresShape>;
+/**
+ * Effect-TS context tag for the DataStore routing service.
+ *
+ * Provides access to multiple DataStore instances with routing logic.
+ *
+ * @example
+ * ```typescript
+ * const uploadEffect = Effect.gen(function* () {
+ *   const dataStores = yield* UploadFileDataStores;
+ *   // Route to specific storage based on storageId
+ *   const dataStore = yield* dataStores.getDataStore("s3-production", clientId);
+ *   const file = yield* dataStore.create(uploadFile);
+ *   return file;
+ * });
+ * ```
+ */
+declare class UploadFileDataStores extends UploadFileDataStores_base {}
+/**
+ * Simplified DataStore configuration for easy setup.
+ *
+ * This type allows flexible configuration:
+ * - Single DataStore instance
+ * - Multiple named stores with routing
+ * - Effect that resolves to a DataStore
+ * - Pre-built Effect Layer
+ *
+ * @example
+ * ```typescript
+ * // Single store
+ * const config: DataStoreConfig = s3DataStore;
+ *
+ * // Multiple stores with routing
+ * const config: DataStoreConfig = {
+ *   stores: {
+ *     "s3-prod": s3ProdStore,
+ *     "s3-dev": s3DevStore,
+ *     "local": localFileStore,
+ *   },
+ *   default: "s3-prod"
+ * };
+ *
+ * // Effect that creates a store
+ * const config: DataStoreConfig = Effect.gen(function* () {
+ *   const kvStore = yield* UploadFileKVStore;
+ *   return createS3Store(kvStore);
+ * });
+ *
+ * // Pre-built Layer
+ * const config: DataStoreConfig = Layer.succeed(UploadFileDataStores, {...});
+ * ```
+ */
+type DataStoreConfig = DataStore<UploadFile> | Effect.Effect<DataStore<UploadFile>, never, UploadFileKVStore> | {
+  stores: Record<string, DataStore<UploadFile> | Effect.Effect<DataStore<UploadFile>, never, UploadFileKVStore>>;
+  default?: string;
+} | Layer.Layer<UploadFileDataStores, never, UploadFileKVStore>;
+/**
+ * Type guard to check if a value is a DataStore instance.
+ *
+ * @param config - The value to check
+ * @returns True if the value is a DataStore
+ *
+ * @example
+ * ```typescript
+ * if (isDataStore(config)) {
+ *   const capabilities = config.getCapabilities();
+ * }
+ * ```
+ */
+declare const isDataStore: (config: DataStoreConfig) => config is DataStore<UploadFile>;
+/**
+ * Creates an Effect Layer from simplified DataStoreConfig.
+ *
+ * This function converts any DataStoreConfig format into a proper Effect Layer
+ * that can be provided to the UploadFileDataStores context tag.
+ *
+ * It handles:
+ * - Single DataStore: Wraps in a Layer that always returns that store
+ * - Multiple stores: Creates routing logic with optional default
+ * - Effect<DataStore>: Executes the Effect and wraps the result
+ * - Layer: Returns as-is
+ *
+ * @param config - The DataStore configuration
+ * @returns A Layer that provides UploadFileDataStores service
+ *
+ * @example
+ * ```typescript
+ * // Create from single store
+ * const layer = await createDataStoreLayer(s3DataStore);
+ *
+ * // Create from multiple stores
+ * const layer = await createDataStoreLayer({
+ *   stores: {
+ *     "production": s3Store,
+ *     "development": localStore,
+ *   },
+ *   default: "development"
+ * });
+ *
+ * // Use the layer
+ * const program = Effect.gen(function* () {
+ *   const stores = yield* UploadFileDataStores;
+ *   const store = yield* stores.getDataStore("production", null);
+ *   return store;
+ * }).pipe(Effect.provide(layer));
+ * ```
+ */
+declare const createDataStoreLayer: (config: DataStoreConfig) => Promise<Layer.Layer<UploadFileDataStores, never, UploadFileKVStore>>;
+//#endregion
+//#region src/types/event-broadcaster.d.ts
+/**
+ * Event broadcaster interface for pub/sub messaging across distributed instances.
+ * Used by WebSocketManager to broadcast upload events to all connected instances.
+ */
+interface EventBroadcaster {
+  /**
+   * Publish a message to a channel
+   */
+  readonly publish: (channel: string, message: string) => Effect.Effect<void, UploadistaError>;
+  /**
+   * Subscribe to messages on a channel
+   */
+  readonly subscribe: (channel: string, handler: (message: string) => void) => Effect.Effect<void, UploadistaError>;
+  /**
+   * Unsubscribe from a channel (optional - not all implementations may support)
+   */
+  readonly unsubscribe?: (channel: string) => Effect.Effect<void, UploadistaError>;
+}
+declare const EventBroadcasterService_base: Context.TagClass<EventBroadcasterService, "EventBroadcaster", EventBroadcaster>;
+/**
+ * Context tag for EventBroadcaster service
+ */
+declare class EventBroadcasterService extends EventBroadcasterService_base {}
+//#endregion
+//#region src/types/upload-event.d.ts
+declare enum UploadEventType {
+  UPLOAD_STARTED = "upload-started",
+  UPLOAD_PROGRESS = "upload-progress",
+  UPLOAD_COMPLETE = "upload-complete",
+  UPLOAD_FAILED = "upload-failed",
+  UPLOAD_VALIDATION_SUCCESS = "upload-validation-success",
+  UPLOAD_VALIDATION_FAILED = "upload-validation-failed",
+  UPLOAD_VALIDATION_WARNING = "upload-validation-warning",
+}
+declare const uploadEventSchema: z.ZodUnion<readonly [z.ZodObject<{
+  type: z.ZodUnion<readonly [z.ZodLiteral<UploadEventType.UPLOAD_STARTED>, z.ZodLiteral<UploadEventType.UPLOAD_COMPLETE>]>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    size: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    creationDate: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    sizeIsDeferred: z.ZodOptional<z.ZodBoolean>;
+    checksum: z.ZodOptional<z.ZodString>;
+    checksumAlgorithm: z.ZodOptional<z.ZodString>;
+    storage: z.ZodObject<{
+      id: z.ZodString;
+      type: z.ZodString;
+      path: z.ZodOptional<z.ZodString>;
+      uploadId: z.ZodOptional<z.ZodString>;
+      bucket: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    flow: z.ZodOptional<z.ZodObject<{
+      flowId: z.ZodString;
+      nodeId: z.ZodString;
+      jobId: z.ZodString;
+    }, z.core.$strip>>;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_PROGRESS>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    progress: z.ZodNumber;
+    total: z.ZodNumber;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_FAILED>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    error: z.ZodString;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_SUCCESS>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    validationType: z.ZodEnum<{
+      checksum: "checksum";
+      mimetype: "mimetype";
+    }>;
+    algorithm: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_FAILED>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    reason: z.ZodString;
+    expected: z.ZodString;
+    actual: z.ZodString;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_WARNING>;
+  data: z.ZodObject<{
+    id: z.ZodString;
+    message: z.ZodString;
+  }, z.core.$strip>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>]>;
+type UploadEvent = z.infer<typeof uploadEventSchema>;
+//#endregion
+//#region src/types/websocket.d.ts
+/**
+ * Platform-agnostic WebSocket connection interface
+ */
+interface WebSocketConnection {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  readonly readyState: number;
+  readonly id: string;
+}
+/**
+ * WebSocket message that can be sent/received
+ */
+declare const webSocketMessageSchema: z$1.ZodUnion<readonly [z$1.ZodObject<{
+  type: z$1.ZodLiteral<"upload_event">;
+  payload: z$1.ZodUnion<readonly [z$1.ZodObject<{
+    type: z$1.ZodUnion<readonly [z$1.ZodLiteral<UploadEventType.UPLOAD_STARTED>, z$1.ZodLiteral<UploadEventType.UPLOAD_COMPLETE>]>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      size: z$1.ZodOptional<z$1.ZodNumber>;
+      offset: z$1.ZodNumber;
+      metadata: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodUnion<readonly [z$1.ZodString, z$1.ZodNumber, z$1.ZodBoolean]>>>;
+      creationDate: z$1.ZodOptional<z$1.ZodString>;
+      url: z$1.ZodOptional<z$1.ZodString>;
+      sizeIsDeferred: z$1.ZodOptional<z$1.ZodBoolean>;
+      checksum: z$1.ZodOptional<z$1.ZodString>;
+      checksumAlgorithm: z$1.ZodOptional<z$1.ZodString>;
+      storage: z$1.ZodObject<{
+        id: z$1.ZodString;
+        type: z$1.ZodString;
+        path: z$1.ZodOptional<z$1.ZodString>;
+        uploadId: z$1.ZodOptional<z$1.ZodString>;
+        bucket: z$1.ZodOptional<z$1.ZodString>;
+      }, z$1.core.$strip>;
+      flow: z$1.ZodOptional<z$1.ZodObject<{
+        flowId: z$1.ZodString;
+        nodeId: z$1.ZodString;
+        jobId: z$1.ZodString;
+      }, z$1.core.$strip>>;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_PROGRESS>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      progress: z$1.ZodNumber;
+      total: z$1.ZodNumber;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_FAILED>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      error: z$1.ZodString;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_SUCCESS>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      validationType: z$1.ZodEnum<{
+        checksum: "checksum";
+        mimetype: "mimetype";
+      }>;
+      algorithm: z$1.ZodOptional<z$1.ZodString>;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_FAILED>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      reason: z$1.ZodString;
+      expected: z$1.ZodString;
+      actual: z$1.ZodString;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>, z$1.ZodObject<{
+    type: z$1.ZodLiteral<UploadEventType.UPLOAD_VALIDATION_WARNING>;
+    data: z$1.ZodObject<{
+      id: z$1.ZodString;
+      message: z$1.ZodString;
+    }, z$1.core.$strip>;
+    flow: z$1.ZodOptional<z$1.ZodObject<{
+      flowId: z$1.ZodString;
+      nodeId: z$1.ZodString;
+      jobId: z$1.ZodString;
+    }, z$1.core.$strip>>;
+  }, z$1.core.$strip>]>;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"flow_event">;
+  payload: z$1.ZodAny;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"subscribed">;
+  payload: z$1.ZodObject<{
+    eventKey: z$1.ZodString;
+  }, z$1.core.$strip>;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"error">;
+  message: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"pong">;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"ping">;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>, z$1.ZodObject<{
+  type: z$1.ZodLiteral<"connection">;
+  message: z$1.ZodOptional<z$1.ZodString>;
+  uploadId: z$1.ZodOptional<z$1.ZodString>;
+  timestamp: z$1.ZodOptional<z$1.ZodString>;
+}, z$1.core.$strip>]>;
+type WebSocketMessage<TEvent = unknown> = z$1.infer<typeof webSocketMessageSchema> | {
+  type: "upload_event";
+  payload: TEvent;
+  timestamp?: string;
+} | {
+  type: "flow_event";
+  payload: TEvent;
+  timestamp?: string;
+};
+//#endregion
+//#region src/types/event-emitter.d.ts
+/**
+ * Base event emitter interface for raw string message broadcasting.
+ *
+ * This is the low-level interface that event broadcasting implementations
+ * (WebSocket, Server-Sent Events, etc.) implement. It emits raw string messages
+ * without type safety or serialization.
+ *
+ * @property subscribe - Registers a WebSocket connection to receive events for a key
+ * @property unsubscribe - Removes subscription for a key
+ * @property emit - Broadcasts a string message to all subscribers of a key
+ *
+ * @example
+ * ```typescript
+ * // Implement BaseEventEmitter with WebSocket broadcast
+ * const websocketEmitter: BaseEventEmitter = {
+ *   subscribe: (key, connection) => Effect.sync(() => {
+ *     connections.set(key, [...(connections.get(key) || []), connection]);
+ *   }),
+ *
+ *   unsubscribe: (key) => Effect.sync(() => {
+ *     connections.delete(key);
+ *   }),
+ *
+ *   emit: (key, event) => Effect.sync(() => {
+ *     const subs = connections.get(key) || [];
+ *     subs.forEach(conn => conn.send(event));
+ *   })
+ * };
+ * ```
+ */
+interface BaseEventEmitter {
+  readonly subscribe: (key: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+  readonly unsubscribe: (key: string) => Effect.Effect<void, UploadistaError>;
+  readonly emit: (key: string, event: string) => Effect.Effect<void, UploadistaError>;
+}
+/**
+ * Type-safe event emitter interface with automatic serialization.
+ *
+ * This wraps a BaseEventEmitter and handles event serialization to JSON messages,
+ * providing type safety for events and ensuring consistent message format.
+ *
+ * @template TEvent - The type of events emitted by this emitter
+ *
+ * @property subscribe - Registers a WebSocket connection to receive typed events
+ * @property unsubscribe - Removes subscription
+ * @property emit - Serializes and broadcasts a typed event
+ *
+ * @example
+ * ```typescript
+ * // Use a typed event emitter
+ * const uploadEmitter: EventEmitter<UploadEvent> = new TypedEventEmitter(
+ *   baseEmitter,
+ *   (event) => JSON.stringify({ type: 'upload', payload: event })
+ * );
+ *
+ * // Emit type-safe events
+ * const program = Effect.gen(function* () {
+ *   const event: UploadEvent = {
+ *     uploadId: "upload123",
+ *     type: "progress",
+ *     offset: 1024,
+ *     size: 2048
+ *   };
+ *
+ *   // Automatic serialization
+ *   yield* uploadEmitter.emit("upload123", event);
+ * });
+ * ```
+ */
+type EventEmitter<TEvent> = {
+  readonly subscribe: (key: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+  readonly unsubscribe: (key: string) => Effect.Effect<void, UploadistaError>;
+  readonly emit: (key: string, event: TEvent) => Effect.Effect<void, UploadistaError>;
+};
+/**
+ * Typed wrapper class that adds event serialization to a BaseEventEmitter.
+ *
+ * This class implements the EventEmitter interface by wrapping a BaseEventEmitter
+ * and handling serialization for a specific event type. It converts typed events
+ * to JSON message strings before broadcasting.
+ *
+ * @template TEvent - The type of events to emit
+ *
+ * @example
+ * ```typescript
+ * // Create a typed emitter for UploadEvent
+ * const uploadEmitter = new TypedEventEmitter<UploadEvent>(
+ *   baseEmitter,
+ *   (event) => JSON.stringify({
+ *     type: "upload_event",
+ *     payload: event,
+ *     timestamp: new Date().toISOString()
+ *   })
+ * );
+ *
+ * // Use the emitter
+ * const effect = Effect.gen(function* () {
+ *   // Subscribe a WebSocket connection
+ *   yield* uploadEmitter.subscribe("upload123", websocket);
+ *
+ *   // Emit an event (automatically serialized)
+ *   yield* uploadEmitter.emit("upload123", {
+ *     uploadId: "upload123",
+ *     type: "completed",
+ *     offset: 2048,
+ *     size: 2048
+ *   });
+ *
+ *   // Unsubscribe when done
+ *   yield* uploadEmitter.unsubscribe("upload123");
+ * });
+ *
+ * // Custom message format
+ * const customEmitter = new TypedEventEmitter<MyEvent>(
+ *   baseEmitter,
+ *   (event) => `EVENT:${event.type}:${JSON.stringify(event.data)}`
+ * );
+ * ```
+ */
+declare class TypedEventEmitter<TEvent> implements EventEmitter<TEvent> {
+  private baseEmitter;
+  private eventToMessage;
+  constructor(baseEmitter: BaseEventEmitter, eventToMessage: (event: TEvent) => string);
+  subscribe: (key: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+  unsubscribe: (key: string) => Effect.Effect<void, UploadistaError>;
+  emit: (key: string, event: TEvent) => Effect.Effect<void, UploadistaError>;
+}
+/**
+ * Default event-to-message serialization helper.
+ *
+ * Creates a standardized JSON message format with type, payload, and timestamp.
+ * This is the recommended way to serialize events for WebSocket transmission.
+ *
+ * @param messageType - The message type identifier ("upload_event" or "flow_event")
+ * @returns An object with an eventToMessage function
+ *
+ * @example
+ * ```typescript
+ * // Create emitter with standard serialization
+ * const emitter = new TypedEventEmitter<UploadEvent>(
+ *   baseEmitter,
+ *   eventToMessageSerializer("upload_event").eventToMessage
+ * );
+ *
+ * // Messages will be formatted as:
+ * // {
+ * //   "type": "upload_event",
+ * //   "payload": { ...event data... },
+ * //   "timestamp": "2024-01-15T10:30:00.000Z"
+ * // }
+ * ```
+ */
+declare const eventToMessageSerializer: (messageType: "upload_event" | "flow_event") => {
+  eventToMessage: <T>(event: T) => string;
+};
+declare const BaseEventEmitterService_base: Context.TagClass<BaseEventEmitterService, "BaseEventEmitter", BaseEventEmitter>;
+/**
+ * Effect-TS context tag for the base untyped event emitter.
+ *
+ * This is the low-level emitter that broadcasting implementations provide.
+ * Most application code should use typed emitters like UploadEventEmitter instead.
+ *
+ * @example
+ * ```typescript
+ * // Provide a base emitter implementation
+ * const baseEmitterLayer = Layer.succeed(BaseEventEmitterService, websocketEmitter);
+ *
+ * // Use in an Effect
+ * const effect = Effect.gen(function* () {
+ *   const baseEmitter = yield* BaseEventEmitterService;
+ *   yield* baseEmitter.emit("channel1", "raw message");
+ * });
+ * ```
+ */
+declare class BaseEventEmitterService extends BaseEventEmitterService_base {}
+declare const UploadEventEmitter_base: Context.TagClass<UploadEventEmitter, "UploadEventEmitter", EventEmitter<{
+  type: UploadEventType.UPLOAD_STARTED | UploadEventType.UPLOAD_COMPLETE;
+  data: {
+    id: string;
+    offset: number;
+    storage: {
+      id: string;
+      type: string;
+      path?: string | undefined;
+      uploadId?: string | undefined;
+      bucket?: string | undefined;
+    };
+    size?: number | undefined;
+    metadata?: Record<string, string | number | boolean> | undefined;
+    creationDate?: string | undefined;
+    url?: string | undefined;
+    sizeIsDeferred?: boolean | undefined;
+    checksum?: string | undefined;
+    checksumAlgorithm?: string | undefined;
+    flow?: {
+      flowId: string;
+      nodeId: string;
+      jobId: string;
+    } | undefined;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_PROGRESS;
+  data: {
+    id: string;
+    progress: number;
+    total: number;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_FAILED;
+  data: {
+    id: string;
+    error: string;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_VALIDATION_SUCCESS;
+  data: {
+    id: string;
+    validationType: "checksum" | "mimetype";
+    algorithm?: string | undefined;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_VALIDATION_FAILED;
+  data: {
+    id: string;
+    reason: string;
+    expected: string;
+    actual: string;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+} | {
+  type: UploadEventType.UPLOAD_VALIDATION_WARNING;
+  data: {
+    id: string;
+    message: string;
+  };
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+}>>;
+/**
+ * Effect-TS context tag for the UploadEvent typed emitter.
+ *
+ * This provides type-safe event emission for upload progress and lifecycle events.
+ * It's the primary way to broadcast upload events to connected clients.
+ *
+ * @example
+ * ```typescript
+ * const uploadEffect = Effect.gen(function* () {
+ *   const emitter = yield* UploadEventEmitter;
+ *
+ *   // Subscribe a client to upload events
+ *   yield* emitter.subscribe("upload123", websocketConnection);
+ *
+ *   // Emit progress event
+ *   yield* emitter.emit("upload123", {
+ *     uploadId: "upload123",
+ *     type: "progress",
+ *     offset: 512000,
+ *     size: 1024000
+ *   });
+ *
+ *   // Emit completion event
+ *   yield* emitter.emit("upload123", {
+ *     uploadId: "upload123",
+ *     type: "completed",
+ *     offset: 1024000,
+ *     size: 1024000
+ *   });
+ * });
+ * ```
+ */
+declare class UploadEventEmitter extends UploadEventEmitter_base {}
+/**
+ * Effect Layer that creates the UploadEventEmitter from a BaseEventEmitter.
+ *
+ * This layer automatically wires up JSON serialization for UploadEvent objects
+ * with the standard "upload_event" message format.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const emitter = yield* UploadEventEmitter;
+ *   // Use the emitter...
+ * }).pipe(
+ *   Effect.provide(uploadEventEmitter),
+ *   Effect.provide(baseEmitterLayer)
+ * );
+ * ```
+ */
+declare const uploadEventEmitter: Layer.Layer<UploadEventEmitter, never, BaseEventEmitterService>;
+declare const FlowEventEmitter_base: Context.TagClass<FlowEventEmitter, "FlowEventEmitter", EventEmitter<FlowEvent>>;
+/**
+ * Effect-TS context tag for the FlowEvent typed emitter.
+ *
+ * This provides type-safe event emission for flow processing lifecycle events.
+ * It's used to broadcast flow execution progress, node completion, and errors.
+ *
+ * @example
+ * ```typescript
+ * const flowEffect = Effect.gen(function* () {
+ *   const emitter = yield* FlowEventEmitter;
+ *
+ *   // Subscribe a client to flow job events
+ *   yield* emitter.subscribe("job123", websocketConnection);
+ *
+ *   // Emit node start event
+ *   yield* emitter.emit("job123", {
+ *     jobId: "job123",
+ *     eventType: "NodeStart",
+ *     flowId: "flow_resize",
+ *     nodeId: "resize_1"
+ *   });
+ *
+ *   // Emit node completion event
+ *   yield* emitter.emit("job123", {
+ *     jobId: "job123",
+ *     eventType: "NodeEnd",
+ *     flowId: "flow_resize",
+ *     nodeId: "resize_1",
+ *     result: { width: 800, height: 600 }
+ *   });
+ * });
+ * ```
+ */
+declare class FlowEventEmitter extends FlowEventEmitter_base {}
+/**
+ * Effect Layer that creates the FlowEventEmitter from a BaseEventEmitter.
+ *
+ * This layer automatically wires up JSON serialization for FlowEvent objects
+ * with the standard "flow_event" message format.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const emitter = yield* FlowEventEmitter;
+ *   // Use the emitter...
+ * }).pipe(
+ *   Effect.provide(flowEventEmitter),
+ *   Effect.provide(baseEmitterLayer)
+ * );
+ * ```
+ */
+declare const flowEventEmitter: Layer.Layer<FlowEventEmitter, never, BaseEventEmitterService>;
+//#endregion
+//#region src/types/input-file.d.ts
+/**
+ * Zod schema for validating InputFile objects.
+ *
+ * This schema defines the structure and validation rules for file upload requests.
+ * Use this schema to parse and validate input data when creating new uploads.
+ *
+ * @see {@link InputFile} for the TypeScript type
+ */
+declare const inputFileSchema: z.ZodObject<{
+  uploadLengthDeferred: z.ZodOptional<z.ZodBoolean>;
+  storageId: z.ZodString;
+  size: z.ZodNumber;
+  type: z.ZodString;
+  fileName: z.ZodOptional<z.ZodString>;
+  lastModified: z.ZodOptional<z.ZodNumber>;
+  metadata: z.ZodOptional<z.ZodString>;
+  checksum: z.ZodOptional<z.ZodString>;
+  checksumAlgorithm: z.ZodOptional<z.ZodString>;
+  flow: z.ZodOptional<z.ZodObject<{
+    flowId: z.ZodString;
+    nodeId: z.ZodString;
+    jobId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Represents the input data for creating a new file upload.
+ *
+ * This type defines the information required to initiate an upload.
+ * It's used by clients to provide upload metadata before sending file data.
+ *
+ * @property storageId - Target storage backend identifier (e.g., "s3-production", "azure-blob")
+ * @property size - File size in bytes
+ * @property type - MIME type of the file (e.g., "image/jpeg", "application/pdf")
+ * @property uploadLengthDeferred - If true, file size is not known upfront (streaming upload)
+ * @property fileName - Original filename from the client
+ * @property lastModified - File's last modified timestamp in milliseconds since epoch
+ * @property metadata - Base64-encoded metadata string (as per tus protocol)
+ * @property checksum - Expected file checksum for validation
+ * @property checksumAlgorithm - Algorithm used for checksum (e.g., "md5", "sha256")
+ * @property flow - Optional flow processing configuration
+ * @property flow.flowId - ID of the flow to execute on this file
+ * @property flow.nodeId - Starting node ID in the flow
+ * @property flow.jobId - Flow job execution ID
+ *
+ * @example
+ * ```typescript
+ * // Basic file upload
+ * const inputFile: InputFile = {
+ *   storageId: "s3-production",
+ *   size: 1024000,
+ *   type: "image/jpeg",
+ *   fileName: "photo.jpg",
+ *   lastModified: Date.now()
+ * };
+ *
+ * // Upload with metadata (base64 encoded as per tus protocol)
+ * const metadata = btoa(JSON.stringify({
+ *   userId: "user_123",
+ *   albumId: "album_456"
+ * }));
+ * const inputWithMetadata: InputFile = {
+ *   storageId: "s3-production",
+ *   size: 2048000,
+ *   type: "image/png",
+ *   fileName: "screenshot.png",
+ *   metadata
+ * };
+ *
+ * // Upload with checksum validation
+ * const inputWithChecksum: InputFile = {
+ *   storageId: "s3-production",
+ *   size: 512000,
+ *   type: "application/pdf",
+ *   fileName: "document.pdf",
+ *   checksum: "5d41402abc4b2a76b9719d911017c592",
+ *   checksumAlgorithm: "md5"
+ * };
+ *
+ * // Upload that triggers a flow
+ * const inputWithFlow: InputFile = {
+ *   storageId: "s3-temp",
+ *   size: 4096000,
+ *   type: "image/jpeg",
+ *   fileName: "large-image.jpg",
+ *   flow: {
+ *     flowId: "resize-and-optimize",
+ *     nodeId: "input_1",
+ *     jobId: "job_789"
+ *   }
+ * };
+ *
+ * // Streaming upload (size unknown)
+ * const streamingInput: InputFile = {
+ *   storageId: "s3-production",
+ *   size: 0, // Will be updated as data arrives
+ *   type: "video/mp4",
+ *   uploadLengthDeferred: true,
+ *   fileName: "live-stream.mp4"
+ * };
+ * ```
+ */
+type InputFile = z.infer<typeof inputFileSchema>;
+//#endregion
+//#region src/types/middleware.d.ts
+type MiddlewareContext = {
+  request: Request;
+  uploadId?: string;
+  metadata?: Record<string, string>;
+};
+type MiddlewareNext = () => Promise<Response>;
+type Middleware = (context: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
+declare const MiddlewareService_base: Context.TagClass<MiddlewareService, "MiddlewareService", {
+  readonly execute: (middlewares: Middleware[], context: MiddlewareContext, handler: MiddlewareNext) => Effect.Effect<Response, UploadistaError>;
+}>;
+declare class MiddlewareService extends MiddlewareService_base {}
+declare const MiddlewareServiceLive: Layer.Layer<MiddlewareService, never, never>;
+//#endregion
+//#region src/upload/mime.d.ts
+/**
+ * Detect MIME type from buffer using magic bytes (file signatures).
+ * Supports a wide range of common file types including images, videos, audio, documents, and archives.
+ *
+ * @param buffer - File content as Uint8Array
+ * @param filename - Optional filename for extension-based fallback
+ * @returns Detected MIME type or "application/octet-stream" if unknown
+ */
+declare const detectMimeType: (buffer: Uint8Array, filename?: string) => string;
+/**
+ * Compare two MIME types with lenient matching.
+ * Matches on major type (e.g., "image/*") to allow for minor variations.
+ *
+ * @param declared - MIME type provided by client
+ * @param detected - MIME type detected from file content
+ * @returns true if MIME types are compatible
+ *
+ * @example
+ * compareMimeTypes("image/png", "image/apng") // true
+ * compareMimeTypes("image/jpeg", "image/png") // true (both images)
+ * compareMimeTypes("image/png", "application/pdf") // false
+ */
+declare function compareMimeTypes(declared: string, detected: string): boolean;
+//#endregion
+//#region src/upload/upload-server.d.ts
+/**
+ * Legacy configuration options for UploadServer.
+ *
+ * @deprecated Use Effect Layers instead of this configuration object.
+ * This type is kept for backward compatibility.
+ *
+ * @property dataStore - DataStore instance or factory function
+ * @property kvStore - KV store for upload metadata
+ * @property eventEmitter - Event emitter for upload progress
+ * @property generateId - Optional ID generator (defaults to UUID)
+ * @property middlewares - Optional request middlewares
+ * @property withTracing - Enable Effect tracing for debugging
+ */
+type UploadServerOptions = {
+  dataStore: ((storageId: string) => Promise<DataStore<UploadFile>>) | DataStore<UploadFile>;
+  kvStore: KvStore<UploadFile>;
+  eventEmitter: EventEmitter<UploadEvent>;
+  generateId?: GenerateIdShape;
+  middlewares?: Middleware[];
+  withTracing?: boolean;
+};
+/**
+ * UploadServer service interface.
+ *
+ * This is the core upload handling service that provides all file upload operations.
+ * It manages upload lifecycle, resumable uploads, progress tracking, and storage integration.
+ *
+ * All operations return Effect types for composable, type-safe error handling.
+ *
+ * @property createUpload - Initiates a new upload and returns metadata
+ * @property uploadChunk - Uploads a chunk of data for an existing upload
+ * @property getCapabilities - Returns storage backend capabilities
+ * @property upload - Complete upload in one operation (create + upload data)
+ * @property uploadFromUrl - Uploads a file from a remote URL
+ * @property getUpload - Retrieves upload metadata by ID
+ * @property read - Reads the complete uploaded file data
+ * @property delete - Deletes an upload and its data
+ * @property subscribeToUploadEvents - Subscribes WebSocket to upload progress events
+ * @property unsubscribeFromUploadEvents - Unsubscribes from upload events
+ *
+ * @example
+ * ```typescript
+ * // Basic upload flow
+ * const program = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *
+ *   // 1. Create upload
+ *   const inputFile: InputFile = {
+ *     storageId: "s3-production",
+ *     size: 1024000,
+ *     type: "image/jpeg",
+ *     fileName: "photo.jpg"
+ *   };
+ *   const upload = yield* server.createUpload(inputFile, "client123");
+ *
+ *   // 2. Upload chunks
+ *   const chunk = new ReadableStream(...);
+ *   const updated = yield* server.uploadChunk(upload.id, "client123", chunk);
+ *
+ *   // 3. Read the uploaded file
+ *   const data = yield* server.read(upload.id, "client123");
+ *
+ *   return upload;
+ * });
+ *
+ * // Upload with WebSocket progress tracking
+ * const uploadWithProgress = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *
+ *   // Subscribe to progress events
+ *   yield* server.subscribeToUploadEvents(uploadId, websocket);
+ *
+ *   // Upload (events will be emitted automatically)
+ *   const result = yield* server.upload(inputFile, clientId, stream);
+ *
+ *   // Unsubscribe when done
+ *   yield* server.unsubscribeFromUploadEvents(uploadId);
+ *
+ *   return result;
+ * });
+ *
+ * // Upload from URL
+ * const urlUpload = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *
+ *   const inputFile: InputFile = {
+ *     storageId: "s3-production",
+ *     size: 0, // Unknown initially
+ *     type: "image/png",
+ *     fileName: "remote-image.png"
+ *   };
+ *
+ *   const upload = yield* server.uploadFromUrl(
+ *     inputFile,
+ *     "client123",
+ *     "https://example.com/image.png"
+ *   );
+ *
+ *   return upload;
+ * });
+ * ```
+ */
+type UploadServerShape = {
+  createUpload: (inputFile: InputFile, clientId: string | null) => Effect.Effect<UploadFile, UploadistaError>;
+  uploadChunk: (uploadId: string, clientId: string | null, chunk: ReadableStream) => Effect.Effect<UploadFile, UploadistaError>;
+  getCapabilities: (storageId: string, clientId: string | null) => Effect.Effect<DataStoreCapabilities, UploadistaError>;
+  upload: (file: InputFile, clientId: string | null, stream: ReadableStream) => Effect.Effect<UploadFile, UploadistaError>;
+  uploadFromUrl: (inputFile: InputFile, clientId: string | null, url: string) => Effect.Effect<UploadFile, UploadistaError>;
+  getUpload: (uploadId: string) => Effect.Effect<UploadFile, UploadistaError>;
+  read: (uploadId: string, clientId: string | null) => Effect.Effect<Uint8Array, UploadistaError>;
+  delete: (uploadId: string, clientId: string | null) => Effect.Effect<void, UploadistaError>;
+  subscribeToUploadEvents: (uploadId: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+  unsubscribeFromUploadEvents: (uploadId: string) => Effect.Effect<void, UploadistaError>;
+};
+declare const UploadServer_base: Context.TagClass<UploadServer, "UploadServer", UploadServerShape>;
+/**
+ * Effect-TS context tag for the UploadServer service.
+ *
+ * Use this tag to access the UploadServer in an Effect context.
+ * The server must be provided via a Layer or dependency injection.
+ *
+ * @example
+ * ```typescript
+ * // Access UploadServer in an Effect
+ * const uploadEffect = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   const upload = yield* server.createUpload(inputFile, clientId);
+ *   return upload;
+ * });
+ *
+ * // Provide UploadServer layer
+ * const program = uploadEffect.pipe(
+ *   Effect.provide(uploadServer),
+ *   Effect.provide(uploadFileKvStore),
+ *   Effect.provide(dataStoreLayer),
+ *   Effect.provide(eventEmitterLayer)
+ * );
+ * ```
+ */
+declare class UploadServer extends UploadServer_base {}
+/**
+ * Creates the UploadServer implementation.
+ *
+ * This function constructs the UploadServer service by composing all required
+ * dependencies (KV store, data stores, event emitter, ID generator). It implements
+ * all upload operations defined in UploadServerShape.
+ *
+ * The server automatically handles:
+ * - Upload lifecycle management (create, resume, complete)
+ * - Progress tracking and event emission
+ * - Storage backend routing based on storageId
+ * - Error handling with proper UploadistaError types
+ *
+ * @returns An Effect that yields the UploadServerShape implementation
+ *
+ * @example
+ * ```typescript
+ * // Create a custom UploadServer layer
+ * const myUploadServer = Layer.effect(
+ *   UploadServer,
+ *   createUploadServer()
+ * );
+ *
+ * // Use in a program
+ * const program = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   // Use server operations...
+ * }).pipe(Effect.provide(myUploadServer));
+ * ```
+ */
+declare function createUploadServer(): Effect.Effect<{
+  upload: (inputFile: InputFile, clientId: string | null, stream: ReadableStream) => Effect.Effect<UploadFile, UploadistaError, never>;
+  uploadFromUrl: (inputFile: InputFile, clientId: string | null, url: string) => Effect.Effect<UploadFile, UploadistaError, never>;
+  createUpload: (inputFile: InputFile, clientId: string | null) => Effect.Effect<UploadFile, UploadistaError, never>;
+  uploadChunk: (uploadId: string, clientId: string | null, chunk: ReadableStream) => Effect.Effect<UploadFile, UploadistaError, never>;
+  getUpload: (uploadId: string) => Effect.Effect<UploadFile, UploadistaError, never>;
+  read: (uploadId: string, clientId: string | null) => Effect.Effect<Uint8Array<ArrayBufferLike>, UploadistaError, never>;
+  delete: (uploadId: string, clientId: string | null) => Effect.Effect<void, UploadistaError, never>;
+  getCapabilities: (storageId: string, clientId: string | null) => Effect.Effect<DataStoreCapabilities, UploadistaError, never>;
+  subscribeToUploadEvents: (uploadId: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError, never>;
+  unsubscribeFromUploadEvents: (uploadId: string) => Effect.Effect<void, UploadistaError, never>;
+}, never, UploadFileDataStores | UploadFileKVStore | UploadEventEmitter | GenerateId>;
+/**
+ * Pre-built UploadServer Effect Layer.
+ *
+ * This layer provides a ready-to-use UploadServer implementation that can be
+ * composed with other layers to build a complete upload system.
+ *
+ * Required dependencies:
+ * - UploadFileKVStore: For storing upload metadata
+ * - UploadFileDataStores: For routing to storage backends
+ * - UploadEventEmitter: For progress events
+ * - GenerateId: For creating upload IDs
+ *
+ * @example
+ * ```typescript
+ * // Compose a complete upload system
+ * const fullUploadSystem = Layer.mergeAll(
+ *   uploadServer,
+ *   uploadFileKvStore,
+ *   dataStoreLayer,
+ *   uploadEventEmitter,
+ *   generateIdLayer
+ * );
+ *
+ * // Use in application
+ * const app = Effect.gen(function* () {
+ *   const server = yield* UploadServer;
+ *   // Perform uploads...
+ * }).pipe(Effect.provide(fullUploadSystem));
+ * ```
+ */
+declare const uploadServer: Layer.Layer<UploadServer, never, UploadFileDataStores | UploadFileKVStore | UploadEventEmitter | GenerateId>;
+//#endregion
+//#region src/upload/upload-strategy-negotiator.d.ts
+/**
+ * Configuration options for upload strategy negotiation.
+ *
+ * @property fileSize - Size of the file to be uploaded in bytes
+ * @property preferredStrategy - Preferred upload strategy (single, parallel, resumable)
+ * @property preferredChunkSize - Preferred chunk size in bytes
+ * @property parallelUploads - Number of parallel upload connections
+ * @property minChunkSizeForParallel - Minimum file size to consider parallel uploads
+ */
+type UploadStrategyOptions = {
+  fileSize: number;
+  preferredStrategy?: UploadStrategy;
+  preferredChunkSize?: number;
+  parallelUploads?: number;
+  minChunkSizeForParallel?: number;
+};
+/**
+ * Result of upload strategy negotiation.
+ *
+ * @property strategy - The negotiated upload strategy
+ * @property chunkSize - The negotiated chunk size in bytes
+ * @property parallelUploads - The negotiated number of parallel uploads
+ * @property reasoning - Array of reasoning strings explaining the decisions
+ * @property warnings - Array of warning messages about adjustments made
+ */
+type NegotiatedStrategy = {
+  strategy: UploadStrategy;
+  chunkSize: number;
+  parallelUploads: number;
+  reasoning: string[];
+  warnings: string[];
+};
+/**
+ * Negotiates the optimal upload strategy based on data store capabilities and file characteristics.
+ *
+ * This class analyzes data store capabilities, file size, and user preferences to determine
+ * the best upload strategy (single, parallel, resumable) and optimal parameters like chunk size
+ * and parallel connection count.
+ *
+ * The negotiator considers:
+ * - Data store capabilities (parallel uploads, resumable uploads, concatenation)
+ * - File size and chunk size constraints
+ * - User preferences and requirements
+ * - Performance optimization opportunities
+ *
+ * @example
+ * ```typescript
+ * // Create negotiator for S3 data store
+ * const negotiator = new UploadStrategyNegotiator(
+ *   s3Capabilities,
+ *   (strategy) => s3Capabilities.supportsStrategy(strategy)
+ * );
+ *
+ * // Negotiate strategy for large file
+ * const result = negotiator.negotiateStrategy({
+ *   fileSize: 100_000_000, // 100MB
+ *   preferredStrategy: "parallel",
+ *   preferredChunkSize: 5_000_000, // 5MB chunks
+ *   parallelUploads: 4
+ * });
+ *
+ * console.log(result.strategy); // "parallel"
+ * console.log(result.chunkSize); // 5_000_000
+ * console.log(result.reasoning); // ["Using preferred strategy: parallel", ...]
+ * ```
+ */
+declare class UploadStrategyNegotiator {
+  private capabilities;
+  private validateUploadStrategy;
+  /**
+   * Creates a new upload strategy negotiator.
+   *
+   * @param capabilities - Data store capabilities and constraints
+   * @param validateUploadStrategy - Function to validate if a strategy is supported
+   */
+  constructor(capabilities: DataStoreCapabilities, validateUploadStrategy: (strategy: UploadStrategy) => boolean);
+  /**
+   * Negotiates the optimal upload strategy based on options and data store capabilities.
+   *
+   * This method analyzes the provided options and data store capabilities to determine
+   * the best upload strategy, chunk size, and parallel upload settings. It considers
+   * user preferences, file size, and data store constraints to make optimal decisions.
+   *
+   * The negotiation process:
+   * 1. Validates preferred strategy against data store capabilities
+   * 2. Automatically selects strategy based on file size and capabilities
+   * 3. Adjusts chunk size to fit within data store constraints
+   * 4. Validates parallel upload settings
+   * 5. Ensures final strategy is supported by the data store
+   *
+   * @param options - Upload strategy options including file size and preferences
+   * @returns Negotiated strategy with reasoning and warnings
+   *
+   * @example
+   * ```typescript
+   * const result = negotiator.negotiateStrategy({
+   *   fileSize: 50_000_000, // 50MB
+   *   preferredStrategy: "parallel",
+   *   preferredChunkSize: 5_000_000, // 5MB
+   *   parallelUploads: 3
+   * });
+   *
+   * console.log(result.strategy); // "parallel"
+   * console.log(result.chunkSize); // 5_000_000
+   * console.log(result.parallelUploads); // 3
+   * console.log(result.reasoning); // ["Using preferred strategy: parallel", ...]
+   * console.log(result.warnings); // [] (no warnings)
+   * ```
+   */
+  negotiateStrategy(options: UploadStrategyOptions): NegotiatedStrategy;
+  /**
+   * Gets the data store capabilities used by this negotiator.
+   *
+   * @returns The data store capabilities and constraints
+   */
+  getDataStoreCapabilities(): DataStoreCapabilities;
+  /**
+   * Validates upload strategy configuration against data store capabilities.
+   *
+   * This method checks if the provided configuration is valid for the current
+   * data store capabilities without performing the actual negotiation. It's
+   * useful for pre-validation before attempting to negotiate a strategy.
+   *
+   * @param options - Upload strategy options to validate
+   * @returns Validation result with validity flag and error messages
+   *
+   * @example
+   * ```typescript
+   * const validation = negotiator.validateConfiguration({
+   *   fileSize: 10_000_000,
+   *   preferredStrategy: "parallel",
+   *   preferredChunkSize: 1_000_000,
+   *   parallelUploads: 5
+   * });
+   *
+   * if (!validation.valid) {
+   *   console.log("Configuration errors:", validation.errors);
+   *   // Handle validation errors
+   * }
+   * ```
+   */
+  validateConfiguration(options: UploadStrategyOptions): {
+    valid: boolean;
+    errors: string[];
+  };
+}
+//#endregion
+//#region src/flow/types/flow-job.d.ts
+/**
+ * Flow job tracking and state management types.
+ *
+ * A FlowJob represents a single execution instance of a flow, tracking its progress,
+ * node results, and execution state. Jobs can be paused and resumed, making them
+ * suitable for long-running or interactive flows.
+ *
+ * @module flow/types/flow-job
+ * @see {@link FlowServer} for job management operations
+ */
+/**
+ * Status of an individual node within a flow job.
+ *
+ * Node tasks follow this lifecycle:
+ * started → pending → running → (completed | paused | failed)
+ */
+type FlowJobTaskStatus = "started" | "pending" | "running" | "completed" | "paused" | "failed";
+/**
+ * Represents a single node's execution within a flow job.
+ *
+ * Tasks track individual node execution, storing results, errors, and retry information.
+ * They allow monitoring of which nodes have completed and accessing intermediate results.
+ *
+ * @property nodeId - Unique identifier of the node this task represents
+ * @property status - Current execution status of the node
+ * @property result - Output data from the node (if completed successfully)
+ * @property error - Error message if the node failed
+ * @property retryCount - Number of retry attempts made before success or final failure
+ * @property createdAt - When the task was created
+ * @property updatedAt - When the task was last updated
+ */
+type FlowJobTask = {
+  nodeId: string;
+  status: FlowJobTaskStatus;
+  result?: unknown;
+  error?: string;
+  retryCount?: number;
+  createdAt: Date;
+  updatedAt: Date;
+};
+/**
+ * Represents a flow execution job with full state tracking.
+ *
+ * Jobs are created when a flow is executed and track the entire execution lifecycle.
+ * They store node results, handle paused states, and manage cleanup of intermediate files.
+ *
+ * @property id - Unique job identifier (UUID)
+ * @property flowId - The flow being executed
+ * @property storageId - Storage location for file outputs
+ * @property clientId - Client that initiated the job (for authorization)
+ * @property status - Overall job status
+ * @property createdAt - When the job was created
+ * @property updatedAt - When the job was last updated
+ * @property tasks - Array of node execution tasks
+ * @property error - Error message if the job failed
+ * @property endedAt - When the job completed or failed
+ * @property result - Final output from the flow (only set when completed)
+ * @property pausedAt - Node ID where execution is paused (if applicable)
+ * @property executionState - State needed to resume a paused flow
+ * @property intermediateFiles - File IDs to cleanup after completion
+ *
+ * @remarks
+ * - Jobs can be paused at nodes that return `{ type: "waiting" }`
+ * - Paused jobs store execution state and can be resumed with new data
+ * - Intermediate files from non-output nodes are automatically cleaned up
+ * - Tasks are updated as nodes progress through their lifecycle
+ *
+ * @example
+ * ```typescript
+ * // Create and monitor a job
+ * const job = yield* flowServer.runFlow({
+ *   flowId: "image-pipeline",
+ *   storageId: "storage-1",
+ *   inputs: { input: myFile }
+ * });
+ *
+ * // Poll for status
+ * const status = yield* flowServer.getJobStatus(job.id);
+ * if (status.status === "completed") {
+ *   console.log("Final result:", status.result);
+ * } else if (status.status === "paused") {
+ *   // Resume with additional data
+ *   yield* flowServer.continueFlow({
+ *     jobId: job.id,
+ *     nodeId: status.pausedAt,
+ *     newData: additionalChunk
+ *   });
+ * }
+ * ```
+ */
+type FlowJob = {
+  id: string;
+  flowId: string;
+  storageId: string;
+  clientId: string | null;
+  status: FlowJobStatus;
+  createdAt: Date;
+  updatedAt: Date;
+  tasks: FlowJobTask[];
+  error?: string;
+  endedAt?: Date;
+  result?: unknown;
+  pausedAt?: string;
+  executionState?: {
+    executionOrder: string[];
+    currentIndex: number;
+    inputs: Record<string, unknown>;
+  };
+  intermediateFiles?: string[];
+};
+/**
+ * Overall status of a flow job.
+ *
+ * Job lifecycle: started → running → (completed | failed)
+ * Or with pauses: started → running → paused → running → (completed | failed)
+ */
+type FlowJobStatus = "pending" | "running" | "completed" | "failed" | "started" | "paused";
+//#endregion
+//#region src/flow/flow-server.d.ts
+/**
+ * Flow provider interface that applications must implement.
+ *
+ * This interface defines how the FlowServer retrieves flow definitions.
+ * Applications provide their own implementation to load flows from a database,
+ * configuration files, or any other source.
+ *
+ * @template TRequirements - Additional Effect requirements for flow execution
+ *
+ * @property getFlow - Retrieves a flow definition by ID with authorization check
+ *
+ * @example
+ * ```typescript
+ * // Implement a flow provider from database
+ * const dbFlowProvider: FlowProviderShape = {
+ *   getFlow: (flowId, clientId) => Effect.gen(function* () {
+ *     // Load flow from database
+ *     const flowData = yield* db.getFlow(flowId);
+ *
+ *     // Check authorization
+ *     if (flowData.ownerId !== clientId) {
+ *       return yield* Effect.fail(
+ *         UploadistaError.fromCode("FLOW_NOT_AUTHORIZED")
+ *       );
+ *     }
+ *
+ *     // Create flow instance
+ *     return createFlow(flowData);
+ *   })
+ * };
+ *
+ * // Provide to FlowServer
+ * const flowProviderLayer = Layer.succeed(FlowProvider, dbFlowProvider);
+ * ```
+ */
+type FlowProviderShape<TRequirements$1 = any> = {
+  getFlow: (flowId: string, clientId: string | null) => Effect.Effect<Flow<any, any, TRequirements$1>, UploadistaError>;
+};
+declare const FlowProvider_base: Context.TagClass<FlowProvider, "FlowProvider", FlowProviderShape<any>>;
+/**
+ * Effect-TS context tag for the FlowProvider service.
+ *
+ * Applications must provide an implementation of FlowProviderShape
+ * to enable the FlowServer to retrieve flow definitions.
+ *
+ * @example
+ * ```typescript
+ * // Access FlowProvider in an Effect
+ * const effect = Effect.gen(function* () {
+ *   const provider = yield* FlowProvider;
+ *   const flow = yield* provider.getFlow("flow123", "client456");
+ *   return flow;
+ * });
+ * ```
+ */
+declare class FlowProvider extends FlowProvider_base {}
+/**
+ * FlowServer service interface.
+ *
+ * This is the core flow processing service that executes DAG-based file processing pipelines.
+ * It manages flow execution, job tracking, node processing, pause/resume functionality,
+ * and real-time event broadcasting.
+ *
+ * All operations return Effect types for composable, type-safe error handling.
+ *
+ * @property getFlow - Retrieves a flow definition by ID
+ * @property getFlowData - Retrieves flow metadata (nodes, edges) without full flow instance
+ * @property runFlow - Starts a new flow execution and returns immediately with job ID
+ * @property continueFlow - Resumes a paused flow with new data for a specific node
+ * @property getJobStatus - Retrieves current status and results of a flow job
+ * @property subscribeToFlowEvents - Subscribes WebSocket to flow execution events
+ * @property unsubscribeFromFlowEvents - Unsubscribes from flow events
+ *
+ * @example
+ * ```typescript
+ * // Execute a flow
+ * const program = Effect.gen(function* () {
+ *   const server = yield* FlowServer;
+ *
+ *   // Start flow execution (returns immediately)
+ *   const job = yield* server.runFlow({
+ *     flowId: "resize-optimize",
+ *     storageId: "s3-production",
+ *     clientId: "client123",
+ *     inputs: {
+ *       input_1: { uploadId: "upload_abc123" }
+ *     }
+ *   });
+ *
+ *   // Subscribe to events
+ *   yield* server.subscribeToFlowEvents(job.id, websocket);
+ *
+ *   // Poll for status
+ *   const status = yield* server.getJobStatus(job.id);
+ *   console.log(status.status); // "running", "paused", "completed", or "failed"
+ *
+ *   return job;
+ * });
+ *
+ * // Resume a paused flow
+ * const resume = Effect.gen(function* () {
+ *   const server = yield* FlowServer;
+ *
+ *   // Flow paused waiting for user input at node "approval_1"
+ *   const job = yield* server.continueFlow({
+ *     jobId: "job123",
+ *     nodeId: "approval_1",
+ *     newData: { approved: true },
+ *     clientId: "client123"
+ *   });
+ *
+ *   return job;
+ * });
+ *
+ * // Check flow structure before execution
+ * const inspect = Effect.gen(function* () {
+ *   const server = yield* FlowServer;
+ *
+ *   const flowData = yield* server.getFlowData("resize-optimize", "client123");
+ *   console.log("Nodes:", flowData.nodes);
+ *   console.log("Edges:", flowData.edges);
+ *
+ *   return flowData;
+ * });
+ * ```
+ */
+type FlowServerShape = {
+  getFlow: <TRequirements>(flowId: string, clientId: string | null) => Effect.Effect<Flow<any, any, TRequirements>, UploadistaError>;
+  getFlowData: (flowId: string, clientId: string | null) => Effect.Effect<FlowData, UploadistaError>;
+  runFlow: <TRequirements>({
+    flowId,
+    storageId,
+    clientId,
+    inputs
+  }: {
+    flowId: string;
+    storageId: string;
+    clientId: string | null;
+    inputs: any;
+  }) => Effect.Effect<FlowJob, UploadistaError, TRequirements>;
+  continueFlow: <TRequirements>({
+    jobId,
+    nodeId,
+    newData,
+    clientId
+  }: {
+    jobId: string;
+    nodeId: string;
+    newData: unknown;
+    clientId: string | null;
+  }) => Effect.Effect<FlowJob, UploadistaError, TRequirements>;
+  getJobStatus: (jobId: string) => Effect.Effect<FlowJob, UploadistaError>;
+  subscribeToFlowEvents: (jobId: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError>;
+  unsubscribeFromFlowEvents: (jobId: string) => Effect.Effect<void, UploadistaError>;
+};
+declare const FlowServer_base: Context.TagClass<FlowServer, "FlowServer", FlowServerShape>;
+/**
+ * Effect-TS context tag for the FlowServer service.
+ *
+ * Use this tag to access the FlowServer in an Effect context.
+ * The server must be provided via a Layer or dependency injection.
+ *
+ * @example
+ * ```typescript
+ * // Access FlowServer in an Effect
+ * const flowEffect = Effect.gen(function* () {
+ *   const server = yield* FlowServer;
+ *   const job = yield* server.runFlow({
+ *     flowId: "my-flow",
+ *     storageId: "s3",
+ *     clientId: null,
+ *     inputs: {}
+ *   });
+ *   return job;
+ * });
+ *
+ * // Provide FlowServer layer
+ * const program = flowEffect.pipe(
+ *   Effect.provide(flowServer),
+ *   Effect.provide(flowProviderLayer),
+ *   Effect.provide(flowJobKvStore)
+ * );
+ * ```
+ */
+declare class FlowServer extends FlowServer_base {}
+/**
+ * Legacy configuration options for FlowServer.
+ *
+ * @deprecated Use Effect Layers and FlowProvider instead.
+ * This type is kept for backward compatibility.
+ *
+ * @property getFlow - Function to retrieve flow definitions
+ * @property kvStore - KV store for flow job metadata
+ */
+type FlowServerOptions = {
+  getFlow: <TRequirements>({
+    flowId,
+    storageId
+  }: {
+    flowId: string;
+    storageId: string;
+  }) => Promise<Flow<any, any, TRequirements>>;
+  kvStore: KvStore<FlowJob>;
+};
+declare function createFlowServer(): Effect.Effect<{
+  getFlow: <TRequirements>(flowId: string, clientId: string | null) => Effect.Effect<Flow<any, any, any>, UploadistaError, never>;
+  getFlowData: (flowId: string, clientId: string | null) => Effect.Effect<FlowData, UploadistaError, never>;
+  runFlow: ({
+    flowId,
+    storageId,
+    clientId,
+    inputs
+  }: {
+    flowId: string;
+    storageId: string;
+    clientId: string | null;
+    inputs: unknown;
+  }) => Effect.Effect<FlowJob, UploadistaError, any>;
+  getJobStatus: (jobId: string) => Effect.Effect<FlowJob, UploadistaError, never>;
+  continueFlow: ({
+    jobId,
+    nodeId,
+    newData,
+    clientId
+  }: {
+    jobId: string;
+    nodeId: string;
+    newData: unknown;
+    clientId: string | null;
+  }) => Effect.Effect<FlowJob, UploadistaError, any>;
+  subscribeToFlowEvents: (jobId: string, connection: WebSocketConnection) => Effect.Effect<void, UploadistaError, never>;
+  unsubscribeFromFlowEvents: (jobId: string) => Effect.Effect<void, UploadistaError, never>;
+}, never, FlowEventEmitter | FlowJobKVStore | UploadServer | FlowProvider>;
+declare const flowServer: Layer.Layer<FlowServer, never, FlowEventEmitter | FlowJobKVStore | UploadServer | FlowProvider>;
+type FlowServerLayer = typeof flowServer;
+//#endregion
+//#region src/flow/nodes/input-node.d.ts
+/**
+ * Union schema for all input operations.
+ * Defines the possible input data structures for the input node.
+ */
+declare const inputDataSchema: z.ZodUnion<readonly [z.ZodObject<{
+  operation: z.ZodLiteral<"init">;
+  storageId: z.ZodString;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>, z.ZodObject<{
+  operation: z.ZodLiteral<"finalize">;
+  uploadId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  operation: z.ZodLiteral<"url">;
+  url: z.ZodString;
+  storageId: z.ZodOptional<z.ZodString>;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>]>;
+/**
+ * Type representing the input data for the input node.
+ * Can be one of three operation types: init, finalize, or url.
+ */
+type InputData = z.infer<typeof inputDataSchema>;
+/**
+ * Schema for input node filtering parameters.
+ * Defines validation rules for incoming files.
+ */
+declare const inputNodeParamsSchema: z.ZodObject<{
+  allowedMimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  minSize: z.ZodOptional<z.ZodNumber>;
+  maxSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Parameters for configuring input node validation.
+ * Controls which files are accepted based on type and size constraints.
+ */
+type InputNodeParams = z.infer<typeof inputNodeParamsSchema>;
+/**
+ * Creates an input node for handling file input through multiple methods.
+ *
+ * The input node supports three operation types:
+ * - `init`: Initialize a streaming upload session
+ * - `finalize`: Complete a streaming upload after all chunks are uploaded
+ * - `url`: Fetch a file directly from a URL
+ *
+ * @param id - Unique identifier for the node
+ * @param params - Optional validation parameters for filtering incoming files
+ * @returns An Effect that creates a flow node configured for file input
+ *
+ * @example
+ * ```typescript
+ * // Create input node with validation
+ * const inputNode = yield* createInputNode("file-input", {
+ *   allowedMimeTypes: ["image/*", "application/pdf"],
+ *   maxSize: 10 * 1024 * 1024, // 10MB
+ * });
+ *
+ * // Create input node without validation
+ * const openInputNode = yield* createInputNode("open-input");
+ * ```
+ */
+declare function createInputNode(id: string, params?: InputNodeParams): Effect.Effect<FlowNode<{
+  operation: "init";
+  storageId: string;
+  metadata?: Record<string, any> | undefined;
+} | {
+  operation: "finalize";
+  uploadId: string;
+} | {
+  operation: "url";
+  url: string;
+  storageId?: string | undefined;
+  metadata?: Record<string, any> | undefined;
+}, UploadFile, UploadistaError>, never, UploadServer>;
+//#endregion
+//#region src/flow/nodes/storage-node.d.ts
+/**
+ * Schema for storage node parameters.
+ * Currently empty but can be extended for storage-specific configuration.
+ */
+declare const storageParamsSchema: z.ZodObject<{}, z.core.$strip>;
+/**
+ * Parameters for the storage node.
+ * Currently no parameters are required, but the schema is available for future extensions.
+ */
+type StorageParams = z.infer<typeof storageParamsSchema>;
+/**
+ * Creates a storage node for storing files in the specified storage.
+ *
+ * The storage node handles the process of:
+ * 1. Reading the input file from the upload server
+ * 2. Checking if the file is already in the target storage
+ * 3. If not, transferring the file to the target storage
+ * 4. Applying optional post-processing
+ * 5. Returning the final stored file
+ *
+ * @param id - Unique identifier for the node
+ * @param postProcessFile - Optional function to process the file after storage
+ * @returns An Effect that creates a flow node configured for file storage
+ *
+ * @example
+ * ```typescript
+ * // Create basic storage node
+ * const storageNode = yield* createStorageNode("store-file");
+ *
+ * // Create storage node with post-processing
+ * const storageWithProcessing = yield* createStorageNode("store-and-process", (file) => {
+ *   return Effect.succeed({
+ *     ...file,
+ *     metadata: { ...file.metadata, processed: true }
+ *   });
+ * });
+ * ```
+ */
+declare function createStorageNode(id: string, postProcessFile?: (file: UploadFile) => Effect.Effect<UploadFile>): Effect.Effect<FlowNode<{
+  id: string;
+  offset: number;
+  storage: {
+    id: string;
+    type: string;
+    path?: string | undefined;
+    uploadId?: string | undefined;
+    bucket?: string | undefined;
+  };
+  size?: number | undefined;
+  metadata?: Record<string, string | number | boolean> | undefined;
+  creationDate?: string | undefined;
+  url?: string | undefined;
+  sizeIsDeferred?: boolean | undefined;
+  checksum?: string | undefined;
+  checksumAlgorithm?: string | undefined;
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+}, UploadFile, UploadistaError>, never, UploadServer>;
+//#endregion
+//#region src/flow/nodes/transform-node.d.ts
+/**
+ * Configuration object for creating a transform node.
+ */
+interface TransformNodeConfig {
+  /** Unique identifier for the node */
+  id: string;
+  /** Human-readable name for the node */
+  name: string;
+  /** Description of what the node does */
+  description: string;
+  /** Function that transforms file bytes */
+  transform: (bytes: Uint8Array, file: UploadFile) => Effect.Effect<Uint8Array | {
+    bytes: Uint8Array;
+    type?: string;
+    fileName?: string;
+  }, UploadistaError>;
+}
+/**
+ * Creates a transform node that handles the common pattern of:
+ * 1. Reading bytes from an UploadFile
+ * 2. Transforming the bytes
+ * 3. Uploading the result as a new UploadFile
+ *
+ * This simplifies nodes that just need to transform file bytes without
+ * worrying about upload server interactions.
+ *
+ * @param config - Configuration object for the transform node
+ * @returns An Effect that creates a flow node configured for file transformation
+ *
+ * @example
+ * ```typescript
+ * // Create an image resize transform node
+ * const resizeNode = yield* createTransformNode({
+ *   id: "resize-image",
+ *   name: "Resize Image",
+ *   description: "Resizes images to specified dimensions",
+ *   transform: (bytes, file) => {
+ *     // Your transformation logic here
+ *     return Effect.succeed(transformedBytes);
+ *   }
+ * });
+ *
+ * // Create a transform node that changes file metadata
+ * const metadataTransformNode = yield* createTransformNode({
+ *   id: "add-metadata",
+ *   name: "Add Metadata",
+ *   description: "Adds custom metadata to files",
+ *   transform: (bytes, file) => {
+ *     return Effect.succeed({
+ *       bytes,
+ *       type: "application/custom",
+ *       fileName: `processed-${file.fileName}`
+ *     });
+ *   }
+ * });
+ * ```
+ */
+declare function createTransformNode({
+  id,
+  name,
+  description,
+  transform
+}: TransformNodeConfig): Effect.Effect<FlowNode<{
+  id: string;
+  offset: number;
+  storage: {
+    id: string;
+    type: string;
+    path?: string | undefined;
+    uploadId?: string | undefined;
+    bucket?: string | undefined;
+  };
+  size?: number | undefined;
+  metadata?: Record<string, string | number | boolean> | undefined;
+  creationDate?: string | undefined;
+  url?: string | undefined;
+  sizeIsDeferred?: boolean | undefined;
+  checksum?: string | undefined;
+  checksumAlgorithm?: string | undefined;
+  flow?: {
+    flowId: string;
+    nodeId: string;
+    jobId: string;
+  } | undefined;
+}, UploadFile, UploadistaError>, never, UploadServer>;
+//#endregion
+//#region src/flow/parallel-scheduler.d.ts
+/**
+ * Represents a level in the execution hierarchy where all nodes can run in parallel.
+ *
+ * @property level - The execution level (0 = first to execute, higher = later)
+ * @property nodes - Array of node IDs that can execute in parallel at this level
+ *
+ * @example
+ * ```
+ * Level 0: [input_node]           (no dependencies)
+ * Level 1: [resize, optimize]     (all depend on level 0)
+ * Level 2: [storage]              (depends on level 1)
+ * ```
+ */
+interface ExecutionLevel {
+  level: number;
+  nodes: string[];
+}
+/**
+ * Configuration options for the ParallelScheduler.
+ *
+ * @property maxConcurrency - Maximum number of nodes to execute in parallel (default: 4)
+ *                           Controls how many nodes run simultaneously within a level
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new ParallelScheduler({ maxConcurrency: 8 });
+ * ```
+ */
+interface ParallelSchedulerConfig {
+  maxConcurrency?: number;
+}
+/**
+ * Scheduler for executing flow nodes in parallel while respecting dependencies.
+ *
+ * The scheduler performs topological sorting to identify nodes that can run
+ * concurrently, groups them into execution levels, and provides methods to
+ * execute them with controlled concurrency using Effect.
+ *
+ * Key responsibilities:
+ * - Analyze flow dependencies and detect cycles
+ * - Group nodes into parallel execution levels
+ * - Execute levels in parallel with concurrency limits
+ * - Provide utilities to check parallel execution feasibility
+ */
+declare class ParallelScheduler {
+  private maxConcurrency;
+  /**
+   * Creates a new ParallelScheduler instance.
+   *
+   * @param config - Configuration for the scheduler
+   * @example
+   * ```typescript
+   * const scheduler = new ParallelScheduler({ maxConcurrency: 4 });
+   * ```
+   */
+  constructor(config?: ParallelSchedulerConfig);
+  /**
+   * Groups nodes into execution levels where nodes in the same level can run in parallel.
+   *
+   * Uses Kahn's algorithm to perform topological sorting with level identification.
+   * Nodes are grouped by their distance from source nodes (input nodes with no dependencies).
+   *
+   * @param nodes - Array of flow nodes to analyze
+   * @param edges - Array of edges defining dependencies between nodes
+   * @returns Array of execution levels, ordered from 0 (no dependencies) onwards
+   * @throws Error if a cycle is detected in the flow graph
+   *
+   * @example
+   * ```typescript
+   * const levels = scheduler.groupNodesByExecutionLevel(nodes, edges);
+   * // levels = [
+   * //   { level: 0, nodes: ['input_1'] },
+   * //   { level: 1, nodes: ['resize_1', 'optimize_1'] },
+   * //   { level: 2, nodes: ['output_1'] }
+   * // ]
+   * ```
+   */
+  groupNodesByExecutionLevel(nodes: FlowNode<unknown, unknown>[], edges: Array<{
+    source: string;
+    target: string;
+  }>): ExecutionLevel[];
+  /**
+   * Executes a batch of Effect-based node executors in parallel with concurrency control.
+   *
+   * All executors are run in parallel, but the number of concurrent executions is limited
+   * by maxConcurrency. This prevents resource exhaustion while maximizing parallelism.
+   *
+   * @template T - The return type of each executor
+   * @template E - The error type of the Effects
+   * @template R - The requirements type of the Effects
+   *
+   * @param nodeExecutors - Array of Effect-returning functions to execute in parallel
+   * @returns Effect that resolves to array of results in the same order as input
+   *
+   * @example
+   * ```typescript
+   * const results = yield* scheduler.executeNodesInParallel([
+   *   () => executeNode("node1"),
+   *   () => executeNode("node2"),
+   *   () => executeNode("node3")
+   * ]);
+   * // results will be in order: [result1, result2, result3]
+   * ```
+   */
+  executeNodesInParallel<T, E, R>(nodeExecutors: Array<() => Effect.Effect<T, E, R>>): Effect.Effect<T[], E, R>;
+  /**
+   * Determines if a set of nodes can be safely executed in parallel.
+   *
+   * Nodes can execute in parallel if all their dependencies have been completed.
+   * This is typically called to verify that nodes in an execution level are ready
+   * to run given the current node results.
+   *
+   * @param nodeIds - Array of node IDs to check
+   * @param nodeResults - Map of completed node IDs to their results
+   * @param reverseGraph - Dependency graph mapping node IDs to their incoming dependencies
+   * @returns true if all dependencies for all nodes are in nodeResults, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const canRun = scheduler.canExecuteInParallel(
+   *   ['resize_1', 'optimize_1'],
+   *   nodeResults,
+   *   reverseGraph
+   * );
+   * ```
+   */
+  canExecuteInParallel(nodeIds: string[], nodeResults: Map<string, unknown>, reverseGraph: Record<string, string[]>): boolean;
+  /**
+   * Gets execution statistics for monitoring and debugging.
+   *
+   * @returns Object containing current scheduler configuration
+   *
+   * @example
+   * ```typescript
+   * const stats = scheduler.getStats();
+   * console.log(`Max concurrency: ${stats.maxConcurrency}`);
+   * ```
+   */
+  getStats(): {
+    maxConcurrency: number;
+  };
+}
+//#endregion
+//#region src/flow/plugins/credential-provider.d.ts
+/**
+ * Shape definition for the Credential Provider interface.
+ * Defines the contract for retrieving credentials for various services.
+ */
+interface CredentialProviderShape {
+  /**
+   * Retrieves credentials for a specific service and client.
+   *
+   * @param params - Parameters for credential retrieval
+   * @param params.clientId - Unique identifier for the client, or null if not available
+   * @param params.serviceType - Optional service type to get specific credentials for
+   * @returns An Effect that resolves to a record of credential key-value pairs
+   * @throws {UploadistaError} When credential retrieval fails
+   */
+  getCredential: (params: {
+    clientId: string | null;
+    serviceType?: string;
+  }) => Effect.Effect<Record<string, unknown>, UploadistaError>;
+}
+declare const CredentialProvider_base: Context.TagClass<CredentialProvider, "CredentialProvider", CredentialProviderShape>;
+/**
+ * Context tag for the Credential Provider.
+ *
+ * This tag provides a type-safe way to access credential functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { CredentialProvider } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const credentialProvider = yield* CredentialProvider;
+ *   const credentials = yield* credentialProvider.getCredential({
+ *     clientId: "user123",
+ *     serviceType: "replicate"
+ *   });
+ *   return credentials;
+ * });
+ * ```
+ */
+declare class CredentialProvider extends CredentialProvider_base {}
+//#endregion
+//#region dist/uploadista-error-D9SONF9K.d.ts
+//#region src/errors/uploadista-error.d.ts
+
+/**
+ * Union type of all possible error codes in the Uploadista system.
+ *
+ * Each error code corresponds to a specific error condition with predefined
+ * HTTP status codes and messages in the ERROR_CATALOG.
+ */
+type UploadistaErrorCode = "MISSING_OFFSET" | "ABORTED" | "INVALID_TERMINATION" | "ERR_LOCK_TIMEOUT" | "INVALID_CONTENT_TYPE" | "FLOW_STRUCTURE_ERROR" | "FLOW_CYCLE_ERROR" | "FLOW_NODE_NOT_FOUND" | "FLOW_NODE_ERROR" | "FLOW_NOT_AUTHORIZED" | "FLOW_NOT_FOUND" | "FILE_READ_ERROR" | "FLOW_JOB_NOT_FOUND" | "FLOW_JOB_ERROR" | "DATASTORE_NOT_FOUND" | "FILE_NOT_FOUND" | "INVALID_OFFSET" | "FILE_NO_LONGER_EXISTS" | "ERR_SIZE_EXCEEDED" | "ERR_MAX_SIZE_EXCEEDED" | "INVALID_LENGTH" | "INVALID_METADATA" | "VALIDATION_ERROR" | "STORAGE_NOT_AUTHORIZED" | "UNKNOWN_ERROR" | "FILE_WRITE_ERROR" | "UPLOAD_ID_NOT_FOUND" | "FLOW_OUTPUT_VALIDATION_ERROR" | "FLOW_INPUT_VALIDATION_ERROR" | "CHECKSUM_MISMATCH" | "MIMETYPE_MISMATCH" | "UNSUPPORTED_CHECKSUM_ALGORITHM";
+/**
+ * Catalog of all predefined errors in the Uploadista system.
+ *
+ * Maps error codes to their HTTP status codes and default error messages.
+ * This centralized catalog ensures consistent error handling across all
+ * Uploadista packages and adapters.
+ *
+ * Each error entry contains:
+ * - `status`: HTTP status code (400-500 range)
+ * - `body`: Human-readable error message
+ *
+ * @example
+ * ```typescript
+ * // Access a specific error definition
+ * const fileNotFound = ERROR_CATALOG.FILE_NOT_FOUND;
+ * console.log(fileNotFound.status); // 404
+ * console.log(fileNotFound.body);   // "The file for this url was not found\n"
+ *
+ * // Use with UploadistaError
+ * const error = UploadistaError.fromCode("FILE_NOT_FOUND");
+ * ```
+ */
+
+declare const UploadistaError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "UploadistaError";
+} & Readonly<A>;
+/**
+ * Standard error class for all Uploadista operations.
+ *
+ * UploadistaError provides a consistent error handling approach across the entire
+ * Uploadista ecosystem. Each error has:
+ * - A typed error code from the ERROR_CATALOG
+ * - An HTTP-compatible status code
+ * - A human-readable error message (body)
+ * - Optional additional details and cause information
+ *
+ * This class integrates with Effect-TS for functional error handling and can be
+ * easily converted to an Effect that fails.
+ *
+ * @example
+ * ```typescript
+ * // Create from error code
+ * const error = UploadistaError.fromCode("FILE_NOT_FOUND");
+ *
+ * // Create with custom details
+ * const customError = UploadistaError.fromCode("FLOW_NODE_ERROR", {
+ *   body: "Failed to process image",
+ *   cause: originalError,
+ *   details: { nodeId: "resize-1", fileId: "abc123" }
+ * });
+ *
+ * // Use with Effect
+ * const effect = customError.toEffect<void>();
+ *
+ * // In an Effect pipeline
+ * return Effect.gen(function* () {
+ *   const file = yield* getFile(id);
+ *   if (!file) {
+ *     return yield* UploadistaError.fromCode("FILE_NOT_FOUND").toEffect();
+ *   }
+ *   return file;
+ * });
+ * ```
+ */
+declare class UploadistaError$1 extends UploadistaError_base {
+  readonly code: string;
+  readonly status: number;
+  readonly status_code: number;
+  readonly body: string;
+  readonly details?: unknown;
+  constructor({
+    code,
+    status,
+    body,
+    cause,
+    details
+  }: {
+    code: UploadistaErrorCode | string;
+    status: number;
+    body: string;
+    cause?: unknown;
+    details?: unknown;
+  });
+  /**
+   * Creates an UploadistaError from a predefined error code.
+   *
+   * This is the primary way to create errors in the Uploadista system. Each error code
+   * has a default status and message defined in ERROR_CATALOG, but these can be overridden
+   * for specific use cases.
+   *
+   * @param code - One of the predefined error codes from UploadistaErrorCode
+   * @param overrides - Optional overrides for the default error properties
+   * @param overrides.status - Custom HTTP status code (overrides the default)
+   * @param overrides.body - Custom error message (overrides the default)
+   * @param overrides.details - Additional structured data about the error
+   * @param overrides.cause - The underlying error that caused this error (for error chaining)
+   *
+   * @returns A new UploadistaError instance
+   *
+   * @example
+   * ```typescript
+   * // Use default error
+   * const error = UploadistaError.fromCode("FILE_NOT_FOUND");
+   *
+   * // Override message
+   * const customError = UploadistaError.fromCode("FILE_NOT_FOUND", {
+   *   body: `File with ID ${fileId} was not found in storage`
+   * });
+   *
+   * // Include cause and details
+   * const detailedError = UploadistaError.fromCode("DATASTORE_NOT_FOUND", {
+   *   cause: storageException,
+   *   details: { storageId: "s3-prod", region: "us-east-1" }
+   * });
+   * ```
+   */
+  static fromCode(code: UploadistaErrorCode, overrides?: Partial<Pick<UploadistaError$1, "status" | "body">> & {
+    details?: unknown;
+    cause?: unknown;
+  }): UploadistaError$1;
+  /**
+   * Converts this error to an Effect that immediately fails.
+   *
+   * This method integrates UploadistaError with Effect-TS's error handling system,
+   * allowing errors to be used in Effect pipelines with proper type checking.
+   *
+   * @template T - The success type of the Effect (defaults to never since it always fails)
+   * @returns An Effect that fails with this UploadistaError
+   *
+   * @example
+   * ```typescript
+   * const error = UploadistaError.fromCode("FILE_NOT_FOUND");
+   *
+   * // Use in an Effect pipeline
+   * return Effect.gen(function* () {
+   *   const file = yield* kvStore.get(fileId);
+   *   if (!file) {
+   *     return yield* error.toEffect();
+   *   }
+   *   return file;
+   * });
+   * ```
+   */
+  toEffect<T = never>(): Effect.Effect<T, UploadistaError$1>;
+}
+/**
+ * Type guard to check if an unknown value is an UploadistaError.
+ *
+ * Useful for error handling when catching errors that might be from
+ * different sources or libraries.
+ *
+ * @param error - The value to check
+ * @returns True if the value is an UploadistaError instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   if (isUploadistaError(error)) {
+ *     console.log(`Uploadista error: ${error.code} (${error.status})`);
+ *     console.log(error.body);
+ *   } else {
+ *     console.error("Unknown error:", error);
+ *   }
+ * }
+ * ```
+ */
+//#endregion
+//#region src/flow/plugins/image-ai-plugin.d.ts
+/**
+ * Context information for AI image processing operations.
+ * Contains client identification for tracking and billing purposes.
+ */
+type ImageAiContext = {
+  /** Unique identifier for the client making the request, or null if not available */
+  clientId: string | null;
+};
+/**
+ * Shape definition for the Image AI Plugin interface.
+ * Defines the contract that all image AI implementations must follow.
+ */
+type ImageAiPluginShape = {
+  /**
+   * Removes the background from an image using AI processing.
+   *
+   * @param inputUrl - The URL of the input image to process
+   * @param context - Context information including client ID for tracking
+   * @returns An Effect that resolves to an object containing the output image URL
+   * @throws {UploadistaError} When the background removal fails
+   */
+  removeBackground: (inputUrl: string, context: ImageAiContext) => Effect.Effect<{
+    outputUrl: string;
+  }, UploadistaError$1>;
+  /**
+   * Generates a textual description of an image using AI analysis.
+   *
+   * @param inputUrl - The URL of the input image to analyze
+   * @param context - Context information including client ID for tracking
+   * @returns An Effect that resolves to an object containing the image description
+   * @throws {UploadistaError} When the image analysis fails
+   */
+  describeImage: (inputUrl: string, context: ImageAiContext) => Effect.Effect<{
+    description: string;
+  }, UploadistaError$1>;
+};
+declare const ImageAiPlugin_base: Context.TagClass<ImageAiPlugin, "ImageAiPlugin", ImageAiPluginShape>;
+/**
+ * Context tag for the Image AI Plugin.
+ *
+ * This tag provides a type-safe way to access image AI functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { ImageAiPlugin } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const imageAi = yield* ImageAiPlugin;
+ *   const result = yield* imageAi.removeBackground(imageUrl, { clientId: "user123" });
+ *   return result.outputUrl;
+ * });
+ * ```
+ */
+declare class ImageAiPlugin extends ImageAiPlugin_base {}
+//#endregion
+//#region src/flow/plugins/types/optimize-node.d.ts
+/**
+ * Zod schema for validating image optimization parameters.
+ * Defines the structure and validation rules for image optimization requests.
+ */
+declare const optimizeParamsSchema: z.ZodObject<{
+  quality: z.ZodNumber;
+  format: z.ZodEnum<{
+    jpeg: "jpeg";
+    webp: "webp";
+    png: "png";
+    avif: "avif";
+  }>;
+}, z.core.$strip>;
+/**
+ * Parameters for the image optimization node.
+ * Controls quality and format settings for image optimization.
+ */
+type OptimizeParams = z.infer<typeof optimizeParamsSchema>;
+//#endregion
+//#region src/flow/plugins/types/resize-node.d.ts
+/**
+ * Zod schema for validating image resize parameters.
+ * Defines the structure and validation rules for image resizing requests.
+ * Requires at least one dimension (width or height) to be specified.
+ */
+declare const resizeParamsSchema: z.ZodObject<{
+  width: z.ZodOptional<z.ZodNumber>;
+  height: z.ZodOptional<z.ZodNumber>;
+  fit: z.ZodEnum<{
+    fill: "fill";
+    contain: "contain";
+    cover: "cover";
+  }>;
+}, z.core.$strip>;
+/**
+ * Parameters for the image resize node.
+ * Controls the target dimensions and fitting behavior for image resizing.
+ */
+type ResizeParams = z.infer<typeof resizeParamsSchema>;
+//#endregion
+//#region src/flow/plugins/image-plugin.d.ts
+/**
+ * Shape definition for the Image Plugin interface.
+ * Defines the contract that all image processing implementations must follow.
+ */
+type ImagePluginShape = {
+  /**
+   * Optimizes an image by adjusting quality and format.
+   *
+   * @param input - The input image as a Uint8Array
+   * @param options - Optimization parameters including quality and format
+   * @returns An Effect that resolves to the optimized image as a Uint8Array
+   * @throws {UploadistaError} When image optimization fails
+   */
+  optimize: (input: Uint8Array, options: OptimizeParams) => Effect.Effect<Uint8Array, UploadistaError$1>;
+  /**
+   * Resizes an image to specified dimensions.
+   *
+   * @param input - The input image as a Uint8Array
+   * @param options - Resize parameters including width, height, and fit mode
+   * @returns An Effect that resolves to the resized image as a Uint8Array
+   * @throws {UploadistaError} When image resizing fails
+   */
+  resize: (input: Uint8Array, options: ResizeParams) => Effect.Effect<Uint8Array, UploadistaError$1>;
+};
+declare const ImagePlugin_base: Context.TagClass<ImagePlugin, "ImagePlugin", ImagePluginShape>;
+/**
+ * Context tag for the Image Plugin.
+ *
+ * This tag provides a type-safe way to access image processing functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { ImagePlugin } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const imagePlugin = yield* ImagePlugin;
+ *   const optimized = yield* imagePlugin.optimize(imageData, { quality: 80, format: "webp" });
+ *   const resized = yield* imagePlugin.resize(optimized, { width: 800, height: 600, fit: "cover" });
+ *   return resized;
+ * });
+ * ```
+ */
+declare class ImagePlugin extends ImagePlugin_base {}
+//#endregion
+//#region src/flow/plugins/types/describe-image-node.d.ts
+/**
+ * Zod schema for validating describe image node parameters.
+ * Defines the structure and validation rules for image description requests.
+ */
+declare const describeImageParamsSchema: z.ZodObject<{
+  serviceType: z.ZodOptional<z.ZodEnum<{
+    replicate: "replicate";
+  }>>;
+}, z.core.$strip>;
+/**
+ * Parameters for the describe image node.
+ * Controls which AI service to use for generating image descriptions.
+ */
+type DescribeImageParams = z.infer<typeof describeImageParamsSchema>;
+//#endregion
+//#region src/flow/plugins/types/remove-background-node.d.ts
+/**
+ * Zod schema for validating remove background node parameters.
+ * Defines the structure and validation rules for background removal requests.
+ */
+declare const removeBackgroundParamsSchema: z.ZodObject<{
+  serviceType: z.ZodOptional<z.ZodEnum<{
+    replicate: "replicate";
+  }>>;
+}, z.core.$strip>;
+/**
+ * Parameters for the remove background node.
+ * Controls which AI service to use for background removal processing.
+ */
+type RemoveBackgroundParams = z.infer<typeof removeBackgroundParamsSchema>;
+//#endregion
+//#region src/flow/plugins/zip-plugin.d.ts
+/**
+ * Parameters for creating a ZIP archive.
+ */
+type ZipParams = {
+  /** Name of the ZIP file to create */
+  zipName: string;
+  /** Whether to include file metadata in the ZIP archive */
+  includeMetadata: boolean;
+};
+/**
+ * Input data structure for ZIP operations.
+ * Represents a single file to be included in the ZIP archive.
+ */
+type ZipInput = {
+  /** Unique identifier for the file */
+  id: string;
+  /** Binary data of the file */
+  data: Uint8Array;
+  /** File metadata including name, size, type, etc. */
+  metadata: UploadFile["metadata"];
+};
+/**
+ * Shape definition for the ZIP Plugin interface.
+ * Defines the contract that all ZIP implementations must follow.
+ */
+type ZipPluginShape = {
+  /**
+   * Creates a ZIP archive from multiple input files.
+   *
+   * @param inputs - Array of files to include in the ZIP archive
+   * @param options - Configuration options for the ZIP creation
+   * @returns An Effect that resolves to the ZIP file as a Uint8Array
+   * @throws {UploadistaError} When ZIP creation fails
+   */
+  zip: (inputs: ZipInput[], options: ZipParams) => Effect.Effect<Uint8Array, UploadistaError$1>;
+};
+declare const ZipPlugin_base: Context.TagClass<ZipPlugin, "ZipPlugin", ZipPluginShape>;
+/**
+ * Context tag for the ZIP Plugin.
+ *
+ * This tag provides a type-safe way to access ZIP functionality
+ * throughout the application using Effect's dependency injection system.
+ *
+ * @example
+ * ```typescript
+ * import { ZipPlugin } from "@uploadista/core/flow/plugins";
+ *
+ * // In your flow node
+ * const program = Effect.gen(function* () {
+ *   const zipPlugin = yield* ZipPlugin;
+ *   const zipData = yield* zipPlugin.zip(files, { zipName: "archive.zip", includeMetadata: true });
+ *   return zipData;
+ * });
+ * ```
+ */
+declare class ZipPlugin extends ZipPlugin_base {}
+//#endregion
+//#region src/flow/typed-flow.d.ts
+type NodeDefinition<TNodeError = never, TNodeRequirements = never> = FlowNode<any, any, UploadistaError> | Effect.Effect<FlowNode<any, any, UploadistaError>, TNodeError, TNodeRequirements>;
+type NodeDefinitionsRecord = Record<string, NodeDefinition<any, any>>;
+type NodeDefinitionError<T$1> = T$1 extends Effect.Effect<FlowNode<any, any, UploadistaError>, infer TError, any> ? TError : never;
+type NodeDefinitionRequirements<T$1> = T$1 extends Effect.Effect<FlowNode<any, any, UploadistaError>, any, infer TRequirements> ? TRequirements : never;
+type NodesErrorUnion<TNodes extends NodeDefinitionsRecord> = { [K in keyof TNodes]: NodeDefinitionError<TNodes[K]> }[keyof TNodes];
+type NodesRequirementsUnion<TNodes extends NodeDefinitionsRecord> = { [K in keyof TNodes]: NodeDefinitionRequirements<TNodes[K]> }[keyof TNodes];
+type FlowRequirements<TNodes extends NodeDefinitionsRecord> = NodesRequirementsUnion<TNodes>;
+type FlowPluginRequirements<TNodes extends NodeDefinitionsRecord> = Exclude<FlowRequirements<TNodes>, UploadServer>;
+type InferNode<T$1> = T$1 extends FlowNode<any, any, UploadistaError> ? T$1 : T$1 extends Effect.Effect<infer R, any, any> ? R extends FlowNode<any, any, UploadistaError> ? R : never : never;
+type ExtractKeysByNodeType<TNodes extends NodeDefinitionsRecord, TType extends NodeType> = { [K in keyof TNodes]: InferNode<TNodes[K]>["type"] extends TType ? K : never }[keyof TNodes];
+type SchemaInfer<T$1> = T$1 extends z.ZodTypeAny ? z.infer<T$1> : never;
+type FlowInputMap<TNodes extends NodeDefinitionsRecord> = { [K in Extract<ExtractKeysByNodeType<TNodes, NodeType.input>, string>]: SchemaInfer<InferNode<TNodes[K]>["inputSchema"]> };
+type FlowOutputMap<TNodes extends NodeDefinitionsRecord> = { [K in Extract<ExtractKeysByNodeType<TNodes, NodeType.output>, string>]: SchemaInfer<InferNode<TNodes[K]>["outputSchema"]> };
+type FlowInputUnion<TNodes extends NodeDefinitionsRecord> = { [K in Extract<ExtractKeysByNodeType<TNodes, NodeType.input>, string>]: SchemaInfer<InferNode<TNodes[K]>["inputSchema"]> }[Extract<ExtractKeysByNodeType<TNodes, NodeType.input>, string>];
+type FlowOutputUnion<TNodes extends NodeDefinitionsRecord> = { [K in Extract<ExtractKeysByNodeType<TNodes, NodeType.output>, string>]: SchemaInfer<InferNode<TNodes[K]>["outputSchema"]> }[Extract<ExtractKeysByNodeType<TNodes, NodeType.output>, string>];
+type NodeKey<TNodes extends NodeDefinitionsRecord> = Extract<keyof TNodes, string>;
+type TypedFlowEdge<TNodes extends NodeDefinitionsRecord> = {
+  source: NodeKey<TNodes>;
+  target: NodeKey<TNodes>;
+  sourcePort?: string;
+  targetPort?: string;
+};
+type TypedFlowConfig<TNodes extends NodeDefinitionsRecord> = {
+  flowId: string;
+  name: string;
+  nodes: TNodes;
+  edges: Array<TypedFlowEdge<TNodes>>;
+  typeChecker?: TypeCompatibilityChecker;
+  onEvent?: (event: FlowEvent) => Effect.Effect<{
+    eventId: string | null;
+  }, UploadistaError>;
+  parallelExecution?: {
+    enabled?: boolean;
+    maxConcurrency?: number;
+  };
+  inputSchema?: z.ZodTypeAny;
+  outputSchema?: z.ZodTypeAny;
+};
+declare const typedFlowInputsSymbol: unique symbol;
+declare const typedFlowOutputsSymbol: unique symbol;
+declare const typedFlowPluginsSymbol: unique symbol;
+type TypedFlow<TNodes extends NodeDefinitionsRecord, TInputSchema extends z.ZodTypeAny, TOutputSchema extends z.ZodTypeAny> = Flow<TInputSchema, TOutputSchema, FlowRequirements<TNodes>> & {
+  run: (args: {
+    inputs?: Partial<FlowInputMap<TNodes>>;
+    storageId: string;
+    jobId: string;
+  }) => Effect.Effect<FlowExecutionResult<FlowOutputMap<TNodes>>, UploadistaError, FlowRequirements<TNodes>>;
+  resume: (args: {
+    jobId: string;
+    storageId: string;
+    nodeResults: Record<string, unknown>;
+    executionState: {
+      executionOrder: string[];
+      currentIndex: number;
+      inputs: Partial<FlowInputMap<TNodes>>;
+    };
+  }) => Effect.Effect<FlowExecutionResult<FlowOutputMap<TNodes>>, UploadistaError, FlowRequirements<TNodes>>;
+  readonly [typedFlowInputsSymbol]?: FlowInputMap<TNodes>;
+  readonly [typedFlowOutputsSymbol]?: FlowOutputMap<TNodes>;
+  readonly [typedFlowPluginsSymbol]?: FlowPluginRequirements<TNodes>;
+};
+declare function createFlow<TNodes extends NodeDefinitionsRecord>(config: TypedFlowConfig<TNodes>): Effect.Effect<TypedFlow<TNodes, z.ZodType<FlowInputUnion<TNodes>>, z.ZodType<FlowOutputUnion<TNodes>>>, NodesErrorUnion<TNodes> | UploadistaError, FlowRequirements<TNodes>>;
+//#endregion
+//#region src/flow/types/flow-file.d.ts
+/**
+ * Conditional execution rules for flow nodes.
+ *
+ * Conditions allow nodes to execute conditionally based on file properties or metadata.
+ * They are evaluated before node execution and can skip nodes that don't match.
+ *
+ * @module flow/types/flow-file
+ * @see {@link FlowNode} for how conditions are used in nodes
+ *
+ * @example
+ * ```typescript
+ * // Only process images larger than 1MB
+ * const condition: FlowCondition = {
+ *   field: "size",
+ *   operator: "greaterThan",
+ *   value: 1024 * 1024
+ * };
+ *
+ * // Only process JPEG images
+ * const jpegCondition: FlowCondition = {
+ *   field: "mimeType",
+ *   operator: "startsWith",
+ *   value: "image/jpeg"
+ * };
+ * ```
+ */
+/**
+ * Represents a conditional rule for node execution.
+ *
+ * @property field - The file property to check
+ * @property operator - The comparison operator to apply
+ * @property value - The value to compare against
+ *
+ * @remarks
+ * - Fields can check file metadata (mimeType, size) or image properties (width, height)
+ * - String operators (contains, startsWith) work with string values
+ * - Numeric operators (greaterThan, lessThan) work with numeric values
+ * - The extension field checks the file extension without the dot
+ */
+type FlowCondition = {
+  field: "mimeType" | "size" | "width" | "height" | "extension";
+  operator: "equals" | "notEquals" | "greaterThan" | "lessThan" | "contains" | "startsWith";
+  value: string | number;
+};
+//#endregion
+//#region src/flow/types/run-args.d.ts
+/**
+ * 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);
+ * ```
+ */
+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.
+ */
+type RunArgs = z.infer<typeof runArgsSchema>;
+//#endregion
+//#region src/flow/utils/resolve-upload-metadata.d.ts
+type FileMetadata = UploadFile["metadata"];
+type ResolvedUploadMetadata = {
+  type: string;
+  fileName: string;
+  metadata: FileMetadata;
+  metadataJson: string | undefined;
+};
+declare function resolveUploadMetadata(metadata: FileMetadata): ResolvedUploadMetadata;
+//#endregion
+export { FlowServerShape as $, FlowJobKVStore as $t, ImageAiContext as A, FlowEventJobStart as An, flowEventEmitter as At, StorageParams as B, NodeType as Bn, BufferedUploadFileDataStore as Bt, describeImageParamsSchema as C, waitingNodeExecution as Cn, BaseEventEmitter as Ct, resizeParamsSchema as D, FlowEventFlowError as Dn, TypedEventEmitter as Dt, ResizeParams as E, FlowEventFlowEnd as En, FlowEventEmitter as Et, ExecutionLevel as F, FlowEventNodeResume as Fn, UploadEvent as Ft, createInputNode as G, UploadFileDataStore as Gt, storageParamsSchema as H, getNodeData as Hn, DataStoreCapabilities as Ht, ParallelScheduler as I, FlowEventNodeStart as In, UploadEventType as It, FlowProvider as J, UploadStrategy as Jt, inputDataSchema as K, UploadFileDataStores as Kt, ParallelSchedulerConfig as L, ConditionField as Ln, uploadEventSchema as Lt, ImageAiPluginShape as M, FlowEventNodeError as Mn, WebSocketConnection as Mt, CredentialProvider as N, FlowEventNodePause as Nn, WebSocketMessage as Nt, OptimizeParams as O, FlowEventFlowStart as On, UploadEventEmitter as Ot, CredentialProviderShape as P, FlowEventNodeResponse as Pn, webSocketMessageSchema as Pt, FlowServerOptions as Q, BaseKvStoreService as Qt, TransformNodeConfig as R, ConditionOperator as Rn, EventBroadcaster as Rt, DescribeImageParams as S, completeNodeExecution as Sn, inputFileSchema as St, ImagePluginShape as T, FlowEvent as Tn, EventEmitter as Tt, InputData as U, DataStoreConfig as Ut, createStorageNode as V, createFlowNode as Vn, DataStore as Vt, InputNodeParams as W, DataStoreWriteOptions as Wt, FlowServer as X, isDataStore as Xt, FlowProviderShape as Y, createDataStoreLayer as Yt, FlowServerLayer as Z, BaseKvStore as Zt, ZipParams as _, FlowNodeData as _n, MiddlewareContext as _t, FlowCondition as a, uploadFileKvStore as an, FlowJobTaskStatus as at, RemoveBackgroundParams as b, NodeTypeMap as bn, MiddlewareServiceLive as bt, FlowPluginRequirements as c, Flow as cn, UploadStrategyOptions as ct, NodeDefinitionsRecord as d, createFlowWithSchema as dn, UploadServerShape as dt, KvStore as en, createFlowServer as et, TypedFlow as f, getFlowData as fn, createUploadServer as ft, ZipInput as g, FlowNode as gn, Middleware as gt, createFlow as h, FlowConfig as hn, detectMimeType as ht, runArgsSchema as i, jsonSerializer as in, FlowJobTask as it, ImageAiPlugin as j, FlowEventNodeEnd as jn, uploadEventEmitter as jt, optimizeParamsSchema as k, FlowEventJobEnd as kn, eventToMessageSerializer as kt, FlowRequirements as l, FlowData as ln, UploadServer as lt, TypedFlowEdge as m, createFlowEdge as mn, compareMimeTypes as mt, resolveUploadMetadata as n, UploadFileKVStore as nn, FlowJob as nt, FlowInputMap as o, UploadFile as on, NegotiatedStrategy as ot, TypedFlowConfig as p, FlowEdge as pn, uploadServer as pt, inputNodeParamsSchema as q, UploadFileDataStoresShape as qt, RunArgs as r, flowJobKvStore as rn, FlowJobStatus as rt, FlowOutputMap as s, uploadFileSchema as sn, UploadStrategyNegotiator as st, ResolvedUploadMetadata as t, TypedKvStore as tn, flowServer as tt, NodeDefinition as u, FlowExecutionResult as un, UploadServerOptions as ut, ZipPlugin as v, NodeConnectionValidator as vn, MiddlewareNext as vt, ImagePlugin as w, EventType as wn, BaseEventEmitterService as wt, removeBackgroundParamsSchema as x, TypeCompatibilityChecker as xn, InputFile as xt, ZipPluginShape as y, NodeExecutionResult as yn, MiddlewareService as yt, createTransformNode as z, ConditionValue as zn, EventBroadcasterService as zt };
+//# sourceMappingURL=index-0xq1cArb.d.cts.map