@uploadista/core 0.0.2

package/src/flow/plugins/image-plugin.ts

@@ -0,0 +1,60 @@
+import type { UploadistaError } from "@uploadista/core/errors";
+import { Context, type Effect } from "effect";
+import type { OptimizeParams } from "./types/optimize-node";
+import type { ResizeParams } from "./types/resize-node";
+
+/**
+ * Shape definition for the Image Plugin interface.
+ * Defines the contract that all image processing implementations must follow.
+ */
+export 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>;
+  
+  /**
+   * 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>;
+};
+
+/**
+ * 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;
+ * });
+ * ```
+ */
+export class ImagePlugin extends Context.Tag("ImagePlugin")<
+  ImagePlugin,
+  ImagePluginShape
+>() {}

package/src/flow/plugins/types/describe-image-node.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for validating describe image node parameters.
+ * Defines the structure and validation rules for image description requests.
+ */
+export const describeImageParamsSchema = z.object({
+  /** Optional service type to use for image description (currently supports "replicate") */
+  serviceType: z.enum(["replicate"]).optional(),
+});
+
+/**
+ * Parameters for the describe image node.
+ * Controls which AI service to use for generating image descriptions.
+ */
+export type DescribeImageParams = z.infer<typeof describeImageParamsSchema>;

package/src/flow/plugins/types/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-exports all type definitions for flow plugin nodes.
+ * This module provides a centralized way to import all plugin node types.
+ */
+
+export * from "./describe-image-node";
+export * from "./optimize-node";
+export * from "./remove-background-node";
+export * from "./resize-node";

package/src/flow/plugins/types/optimize-node.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for validating image optimization parameters.
+ * Defines the structure and validation rules for image optimization requests.
+ */
+export const optimizeParamsSchema = z.object({
+  /** Image quality as a percentage (0-100) */
+  quality: z.number().min(0).max(100),
+  /** Output image format */
+  format: z.enum(["jpeg", "webp", "png", "avif"] as const),
+});
+
+/**
+ * Parameters for the image optimization node.
+ * Controls quality and format settings for image optimization.
+ */
+export type OptimizeParams = z.infer<typeof optimizeParamsSchema>;

package/src/flow/plugins/types/remove-background-node.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for validating remove background node parameters.
+ * Defines the structure and validation rules for background removal requests.
+ */
+export const removeBackgroundParamsSchema = z.object({
+  /** Optional service type to use for background removal (currently supports "replicate") */
+  serviceType: z.enum(["replicate"]).optional(),
+});
+
+/**
+ * Parameters for the remove background node.
+ * Controls which AI service to use for background removal processing.
+ */
+export type RemoveBackgroundParams = z.infer<
+  typeof removeBackgroundParamsSchema
+>;

package/src/flow/plugins/types/resize-node.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+/**
+ * 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.
+ */
+export const resizeParamsSchema = z
+  .object({
+    /** Target width in pixels (optional) */
+    width: z.number().positive().optional(),
+    /** Target height in pixels (optional) */
+    height: z.number().positive().optional(),
+    /** How the image should fit within the specified dimensions */
+    fit: z.enum(["contain", "cover", "fill"]),
+  })
+  .refine(
+    (data) => data.width || data.height,
+    "Either width or height must be specified for resize"
+  );
+
+/**
+ * Parameters for the image resize node.
+ * Controls the target dimensions and fitting behavior for image resizing.
+ */
+export type ResizeParams = z.infer<typeof resizeParamsSchema>;

package/src/flow/plugins/zip-plugin.ts

@@ -0,0 +1,69 @@
+import type { UploadistaError } from "@uploadista/core/errors";
+import { Context, type Effect } from "effect";
+import type { UploadFile } from "@/types";
+
+/**
+ * Parameters for creating a ZIP archive.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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>;
+  // unzip: (input: ZipInput) => Effect.Effect<Uint8Array, UploadistaError>;
+};
+
+/**
+ * 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;
+ * });
+ * ```
+ */
+export class ZipPlugin extends Context.Tag("ZipPlugin")<
+  ZipPlugin,
+  ZipPluginShape
+>() {}

package/src/flow/typed-flow.ts

@@ -0,0 +1,279 @@
+/**
+ * biome-ignore-all lint/suspicious/noExplicitAny: broadly-typed generics require runtime schema placeholders
+ */
+import { Effect } from "effect";
+import { z } from "zod";
+import type { UploadistaError as CoreUploadistaError } from "../errors";
+import { UploadistaError } from "../errors";
+import type { UploadServer } from "../upload";
+import type { FlowEvent } from "./event";
+import type { Flow, FlowExecutionResult } from "./flow";
+import { createFlowWithSchema } from "./flow";
+import { NodeType } from "./node";
+import type {
+  FlowEdge,
+  FlowNode,
+  TypeCompatibilityChecker,
+} from "./types/flow-types";
+
+export type NodeDefinition<TNodeError = never, TNodeRequirements = never> =
+  | FlowNode<any, any, CoreUploadistaError>
+  | Effect.Effect<
+      FlowNode<any, any, CoreUploadistaError>,
+      TNodeError,
+      TNodeRequirements
+    >;
+
+export type NodeDefinitionsRecord = Record<string, NodeDefinition<any, any>>;
+
+type NodeDefinitionError<T> = T extends Effect.Effect<
+  FlowNode<any, any, CoreUploadistaError>,
+  infer TError,
+  any
+>
+  ? TError
+  : never;
+
+type NodeDefinitionRequirements<T> = T extends Effect.Effect<
+  FlowNode<any, any, CoreUploadistaError>,
+  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];
+
+export type FlowRequirements<TNodes extends NodeDefinitionsRecord> =
+  NodesRequirementsUnion<TNodes>;
+
+export type FlowPluginRequirements<TNodes extends NodeDefinitionsRecord> =
+  Exclude<FlowRequirements<TNodes>, UploadServer>;
+
+type InferNode<T> = T extends FlowNode<any, any, CoreUploadistaError>
+  ? T
+  : T extends Effect.Effect<infer R, any, any>
+    ? R extends FlowNode<any, any, CoreUploadistaError>
+      ? R
+      : never
+    : never;
+
+type ResolvedNodesRecord<TNodes extends NodeDefinitionsRecord> = {
+  [K in keyof TNodes]: InferNode<TNodes[K]>;
+};
+
+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> = T extends z.ZodTypeAny ? z.infer<T> : never;
+
+export type FlowInputMap<TNodes extends NodeDefinitionsRecord> = {
+  [K in Extract<
+    ExtractKeysByNodeType<TNodes, NodeType.input>,
+    string
+  >]: SchemaInfer<InferNode<TNodes[K]>["inputSchema"]>;
+};
+
+export 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
+>;
+
+export type TypedFlowEdge<TNodes extends NodeDefinitionsRecord> = {
+  source: NodeKey<TNodes>;
+  target: NodeKey<TNodes>;
+  sourcePort?: string;
+  targetPort?: string;
+};
+
+export 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 }, CoreUploadistaError>;
+  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;
+
+export 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>>,
+    CoreUploadistaError,
+    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>>,
+    CoreUploadistaError,
+    FlowRequirements<TNodes>
+  >;
+  readonly [typedFlowInputsSymbol]?: FlowInputMap<TNodes>;
+  readonly [typedFlowOutputsSymbol]?: FlowOutputMap<TNodes>;
+  readonly [typedFlowPluginsSymbol]?: FlowPluginRequirements<TNodes>;
+};
+
+const buildUnionSchema = (
+  schemas: z.ZodTypeAny[],
+  fallback: z.ZodTypeAny,
+): z.ZodTypeAny => {
+  if (schemas.length === 0) {
+    return fallback;
+  }
+
+  const [first, ...rest] = schemas as [z.ZodTypeAny, ...z.ZodTypeAny[]];
+  return rest.reduce<z.ZodTypeAny>(
+    (acc, schema) => z.union([acc, schema]),
+    first,
+  );
+};
+
+export 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>
+> {
+  return Effect.gen(function* () {
+    const nodeEntries = Object.entries(config.nodes) as Array<
+      [NodeKey<TNodes>, NodeDefinition]
+    >;
+
+    const resolveNode = (
+      node: NodeDefinition,
+    ): Effect.Effect<
+      FlowNode<any, any, CoreUploadistaError>,
+      NodesErrorUnion<TNodes>,
+      FlowRequirements<TNodes>
+    > =>
+      Effect.isEffect(node)
+        ? (node as Effect.Effect<
+            FlowNode<any, any, CoreUploadistaError>,
+            NodesErrorUnion<TNodes>,
+            FlowRequirements<TNodes>
+          >)
+        : Effect.succeed(node as FlowNode<any, any, CoreUploadistaError>);
+
+    const resolvedEntries = yield* Effect.forEach(nodeEntries, ([key, node]) =>
+      Effect.flatMap(resolveNode(node), (resolvedNode) => {
+        if (resolvedNode.id !== key) {
+          return Effect.fail(
+            UploadistaError.fromCode("FLOW_NODE_ERROR", {
+              cause: new Error(
+                `Node key ${key} does not match node id ${resolvedNode.id}`,
+              ),
+            }),
+          );
+        }
+        return Effect.succeed([key, resolvedNode] as const);
+      }),
+    );
+
+    const resolvedRecord = Object.fromEntries(
+      resolvedEntries,
+    ) as ResolvedNodesRecord<TNodes>;
+    const resolvedNodes = resolvedEntries.map(([, node]) => node);
+
+    const inputSchemas = resolvedEntries
+      .filter(([, node]) => node.type === NodeType.input)
+      .map(([, node]) => node.inputSchema);
+
+    const outputSchemas = resolvedEntries
+      .filter(([, node]) => node.type === NodeType.output)
+      .map(([, node]) => node.outputSchema);
+
+    const inputSchema =
+      config.inputSchema ?? buildUnionSchema(inputSchemas, z.unknown());
+
+    const outputSchema =
+      config.outputSchema ?? buildUnionSchema(outputSchemas, z.unknown());
+
+    const flowEdges: FlowEdge[] = config.edges.map((edge) => ({
+      source: resolvedRecord[edge.source]?.id ?? edge.source,
+      target: resolvedRecord[edge.target]?.id ?? edge.target,
+      sourcePort: edge.sourcePort,
+      targetPort: edge.targetPort,
+    }));
+
+    const flow = yield* createFlowWithSchema({
+      flowId: config.flowId,
+      name: config.name,
+      nodes: resolvedNodes,
+      edges: flowEdges,
+      inputSchema,
+      outputSchema,
+      typeChecker: config.typeChecker,
+      onEvent: config.onEvent,
+      parallelExecution: config.parallelExecution,
+    });
+
+    return flow as unknown as TypedFlow<
+      TNodes,
+      z.ZodType<FlowInputUnion<TNodes>>,
+      z.ZodType<FlowOutputUnion<TNodes>>
+    >;
+  });
+}

package/src/flow/types/flow-file.ts

@@ -0,0 +1,51 @@
+/**
+ * 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
+ */
+export type FlowCondition = {
+  field: "mimeType" | "size" | "width" | "height" | "extension";
+  operator:
+    | "equals"
+    | "notEquals"
+    | "greaterThan"
+    | "lessThan"
+    | "contains"
+    | "startsWith";
+  value: string | number;
+};

package/src/flow/types/flow-job.ts

@@ -0,0 +1,138 @@
+/**
+ * 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
+ */
+
+// import type { FlowData } from "@/flow";
+
+/**
+ * Status of an individual node within a flow job.
+ *
+ * Node tasks follow this lifecycle:
+ * started → pending → running → (completed | paused | failed)
+ */
+export 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
+ */
+export type FlowJobTask = {
+  nodeId: string;
+  status: FlowJobTaskStatus;
+  result?: unknown; // Node execution result
+  error?: string; // Error message from failed execution
+  retryCount?: number; // Number of retry attempts made
+  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
+ *   });
+ * }
+ * ```
+ */
+export type FlowJob = {
+  id: string;
+  flowId: string;
+  storageId: string;
+  clientId: string | null;
+  status: FlowJobStatus;
+  createdAt: Date;
+  updatedAt: Date;
+  tasks: FlowJobTask[];
+  error?: string;
+  endedAt?: Date;
+  // Final flow execution result (only populated when completed)
+  result?: unknown;
+  // Paused execution state
+  pausedAt?: string; // nodeId where execution is paused
+  executionState?: {
+    executionOrder: string[]; // Topological sort order
+    currentIndex: number; // Where we are in execution
+    inputs: Record<string, unknown>; // Original inputs
+  };
+  // Intermediate files to cleanup after flow completion
+  intermediateFiles?: string[]; // UploadFile IDs from non-output nodes
+};
+
+/**
+ * Overall status of a flow job.
+ *
+ * Job lifecycle: started → running → (completed | failed)
+ * Or with pauses: started → running → paused → running → (completed | failed)
+ */
+export type FlowJobStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed"
+  | "started"
+  | "paused";