@uploadista/core 0.0.13 → 0.0.14

package/src/flow/flow.ts

@@ -20,7 +20,12 @@ import type { FlowEdge } from "./edge";
 import { EventType } from "./event";
 import { getNodeData } from "./node";
 import { ParallelScheduler } from "./parallel-scheduler";
-import type { FlowConfig, FlowNode, FlowNodeData } from "./types/flow-types";
+import type {
+  FlowConfig,
+  FlowNode,
+  FlowNodeData,
+  TypedOutput,
+} from "./types/flow-types";
 import { FlowTypeValidator } from "./types/type-validator";
 
 /**
@@ -87,7 +92,11 @@ export const getFlowData = <TRequirements>(
  * ```
  */
 export type FlowExecutionResult<TOutput> =
-  | { type: "completed"; result: TOutput }
+  | {
+      type: "completed";
+      result: TOutput;
+      outputs?: TypedOutput[]; // Typed outputs from all output nodes with registered types
+    }
   | {
       type: "paused";
       nodeId: string;
@@ -458,6 +467,33 @@ export function createFlowWithSchema<
       return flowOutputs as Record<string, z.infer<TFlowInputSchema>>;
     };
 
+    // Collect typed outputs from output nodes with metadata
+    const collectTypedOutputs = (
+      nodeResults: Map<string, unknown>,
+      nodeTypesMap: Map<string, string>,
+    ): TypedOutput[] => {
+      const outputNodes = nodes.filter((node: any) => node.type === "output");
+      const typedOutputs: TypedOutput[] = [];
+
+      outputNodes.forEach((node: any) => {
+        const result = nodeResults.get(node.id);
+        if (result !== undefined) {
+          // Get the nodeType from the nodeTypes map
+          const nodeTypeId = nodeTypesMap.get(node.id);
+
+          // Create TypedOutput with metadata
+          typedOutputs.push({
+            nodeId: node.id,
+            nodeType: nodeTypeId,
+            data: result,
+            timestamp: new Date().toISOString(),
+          });
+        }
+      });
+
+      return typedOutputs;
+    };
+
     // Execute a single node using Effect
     const executeNode = (
       nodeId: string,
@@ -468,7 +504,13 @@ export function createFlowWithSchema<
       jobId: string,
       clientId: string | null,
     ): Effect.Effect<
-      { nodeId: string; result: unknown; success: boolean; waiting: boolean },
+      {
+        nodeId: string;
+        result: unknown;
+        success: boolean;
+        waiting: boolean;
+        nodeType?: string;
+      },
       UploadistaError
     > => {
       return Effect.gen(function* () {
@@ -615,6 +657,7 @@ export function createFlowWithSchema<
                 result,
                 success: true,
                 waiting: true,
+                nodeType: executionResult.nodeType,
               };
             }
 
@@ -633,7 +676,13 @@ export function createFlowWithSchema<
               });
             }
 
-            return { nodeId, result, success: true, waiting: false };
+            return {
+              nodeId,
+              result,
+              success: true,
+              waiting: false,
+              nodeType: executionResult.nodeType,
+            };
           } catch (error) {
             // Store the error
             lastError =
@@ -712,6 +761,7 @@ export function createFlowWithSchema<
       | {
           type: "completed";
           result: Record<string, z.infer<TFlowOutputSchema>>;
+          outputs?: TypedOutput[];
         }
       | {
           type: "paused";
@@ -752,13 +802,22 @@ export function createFlowWithSchema<
           executionOrder = topologicalSort();
           nodeResults = new Map<string, unknown>();
           startIndex = 0;
+        }
 
-          // Check for cycles
-          if (executionOrder.length !== nodes.length) {
-            return yield* UploadistaError.fromCode(
-              "FLOW_CYCLE_ERROR",
-            ).toEffect();
-          }
+        // Track nodeTypes for typed outputs
+        const nodeTypes = new Map<string, string>();
+
+        // If resuming, restore any nodeTypes from previous execution
+        if (resumeFrom) {
+          // nodeTypes would need to be restored from job state if implementing pause/resume
+          // For now, fresh starts only track types going forward
+        }
+
+        // Check for cycles
+        if (executionOrder.length !== nodes.length) {
+          return yield* UploadistaError.fromCode(
+            "FLOW_CYCLE_ERROR",
+          ).toEffect();
         }
 
         // Create node map for quick lookup
@@ -849,6 +908,9 @@ export function createFlowWithSchema<
                 // Node is waiting - pause execution and return state
                 if (nodeResult.result !== undefined) {
                   nodeResults.set(nodeId, nodeResult.result);
+                  if (nodeResult.nodeType) {
+                    nodeTypes.set(nodeId, nodeResult.nodeType);
+                  }
                 }
 
                 return {
@@ -864,6 +926,9 @@ export function createFlowWithSchema<
 
               if (nodeResult.success) {
                 nodeResults.set(nodeId, nodeResult.result);
+                if (nodeResult.nodeType) {
+                  nodeTypes.set(nodeId, nodeResult.nodeType);
+                }
               }
             }
           }
@@ -910,6 +975,9 @@ export function createFlowWithSchema<
               // Node is waiting - pause execution and return state
               if (nodeResult.result !== undefined) {
                 nodeResults.set(nodeResult.nodeId, nodeResult.result);
+                if (nodeResult.nodeType) {
+                  nodeTypes.set(nodeResult.nodeId, nodeResult.nodeType);
+                }
               }
 
               return {
@@ -925,12 +993,16 @@ export function createFlowWithSchema<
 
             if (nodeResult.success) {
               nodeResults.set(nodeResult.nodeId, nodeResult.result);
+              if (nodeResult.nodeType) {
+                nodeTypes.set(nodeResult.nodeId, nodeResult.nodeType);
+              }
             }
           }
         }
 
         // All nodes completed - collect outputs
         const finalResult = collectFlowOutputs(nodeResults);
+        const typedOutputs = collectTypedOutputs(nodeResults, nodeTypes);
 
         const finalResultSchema = z.record(z.string(), outputSchema);
 
@@ -961,17 +1033,22 @@ export function createFlowWithSchema<
         }
         const validatedResult = parseResult.data;
 
-        // Emit FlowEnd event
+        // Emit FlowEnd event with typed outputs
         if (onEvent) {
           yield* onEvent({
             jobId,
             eventType: EventType.FlowEnd,
             flowId,
-            result: validatedResult,
+            outputs: typedOutputs,
+            result: validatedResult, // Keep for backward compatibility
           });
         }
 
-        return { type: "completed" as const, result: validatedResult };
+        return {
+          type: "completed" as const,
+          result: validatedResult,
+          outputs: typedOutputs,
+        };
       });
     };
 
@@ -989,6 +1066,7 @@ export function createFlowWithSchema<
       | {
           type: "completed";
           result: Record<string, z.infer<TFlowOutputSchema>>;
+          outputs?: TypedOutput[];
         }
       | {
           type: "paused";
@@ -1025,6 +1103,7 @@ export function createFlowWithSchema<
       | {
           type: "completed";
           result: Record<string, z.infer<TFlowOutputSchema>>;
+          outputs?: TypedOutput[];
         }
       | {
           type: "paused";

package/src/flow/index.ts

@@ -4,6 +4,13 @@ export * from "./edge";
 
 export * from "./event";
 export type { Flow, FlowData } from "./flow";
+// Type registry
+export * from "./type-registry";
+// Built-in node types (auto-registers on import)
+import "./node-types";
+export * from "./node-types";
+// Type guards
+export * from "./type-guards";
 export * from "./flow";
 // Core flow engine
 export { createFlowWithSchema } from "./flow";

package/src/flow/node-types/index.ts

@@ -0,0 +1,85 @@
+/**
+ * Built-in node type registrations for the flow engine.
+ *
+ * This module automatically registers the standard input and output node types
+ * when imported. These types enable type-safe result consumption in clients.
+ *
+ * @module flow/node-types
+ *
+ * @remarks
+ * This module should be imported by the flow engine initialization to ensure
+ * built-in types are registered before any flows are created.
+ *
+ * @example
+ * ```typescript
+ * // Types are automatically registered on import
+ * import "@uploadista/core/flow/node-types";
+ * import { flowTypeRegistry } from "@uploadista/core/flow";
+ *
+ * // Check registered types
+ * const inputTypes = flowTypeRegistry.listByCategory("input");
+ * console.log(inputTypes.map(t => t.id)); // ["streaming-input-v1"]
+ * ```
+ */
+
+import { uploadFileSchema } from "../../types/upload-file";
+import { flowTypeRegistry } from "../type-registry";
+
+/**
+ * Type ID constants for built-in node types.
+ *
+ * Use these constants when creating nodes with type information to ensure
+ * consistency and avoid typos.
+ *
+ * @example
+ * ```typescript
+ * import { STREAMING_INPUT_TYPE_ID } from "@uploadista/core/flow/node-types";
+ *
+ * const inputNode = createFlowNode({
+ *   // ... other config
+ *   nodeTypeId: STREAMING_INPUT_TYPE_ID
+ * });
+ * ```
+ */
+export const STREAMING_INPUT_TYPE_ID = "streaming-input-v1";
+export const STORAGE_OUTPUT_TYPE_ID = "storage-output-v1";
+
+/**
+ * Register streaming input node type.
+ *
+ * This is the standard input type for flows that accept chunked file uploads.
+ * It produces UploadFile objects as output after processing chunks.
+ */
+flowTypeRegistry.register({
+  id: STREAMING_INPUT_TYPE_ID,
+  category: "input",
+  schema: uploadFileSchema,
+  version: "1.0.0",
+  description: "Streaming file input node that accepts chunked uploads",
+});
+
+/**
+ * Register storage output node type.
+ *
+ * This is the standard output type for flows that save files to storage backends
+ * (S3, Azure, GCS, etc.). It produces UploadFile objects with final storage URLs.
+ */
+flowTypeRegistry.register({
+  id: STORAGE_OUTPUT_TYPE_ID,
+  category: "output",
+  schema: uploadFileSchema,
+  version: "1.0.0",
+  description: "Storage output node that saves files to configured storage backend",
+});
+
+/**
+ * Future type registrations can be added here.
+ *
+ * Examples:
+ * - description-output-v1: AI-powered image description output
+ * - webhook-output-v1: HTTP webhook notification output
+ * - metadata-output-v1: File metadata extraction output
+ */
+
+// Export the registry for convenience
+export { flowTypeRegistry } from "../type-registry";

package/src/flow/node.ts

@@ -6,6 +6,7 @@ import type {
   FlowNodeData,
   NodeExecutionResult,
 } from "./types/flow-types";
+import { flowTypeRegistry } from "./type-registry";
 
 /**
  * Defines the type of node in a flow, determining its role in the processing pipeline.
@@ -81,6 +82,7 @@ export type ConditionValue = string | number;
  * @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)
+ * @param config.nodeTypeId - Optional type ID from the registry (e.g., "storage-output-v1"). If provided, the node type must be registered and its category must match the node type (input/output).
  *
  * @returns An Effect that succeeds with the created FlowNode
  *
@@ -127,6 +129,7 @@ export function createFlowNode<Input, Output, TType extends NodeType = NodeType>
   multiOutput = false,
   pausable = false,
   retry,
+  nodeTypeId,
 }: {
   id: string;
   name: string;
@@ -154,8 +157,35 @@ export function createFlowNode<Input, Output, TType extends NodeType = NodeType>
     retryDelay?: number;
     exponentialBackoff?: boolean;
   };
-}): Effect.Effect<FlowNode<Input, Output, UploadistaError> & { type: TType }> {
-  return Effect.succeed({
+  nodeTypeId?: string;
+}): Effect.Effect<FlowNode<Input, Output, UploadistaError> & { type: TType }, UploadistaError> {
+  return Effect.gen(function* () {
+    // Validate type registration if nodeTypeId provided
+    if (nodeTypeId) {
+      const typeDef = flowTypeRegistry.get(nodeTypeId);
+      if (!typeDef) {
+        return yield* UploadistaError.fromCode("INVALID_NODE_TYPE", {
+          body: `Node type "${nodeTypeId}" is not registered`,
+          details: { nodeTypeId, nodeId: id },
+        }).toEffect();
+      }
+
+      // Validate category matches for input/output nodes
+      if (type === NodeType.input && typeDef.category !== "input") {
+        return yield* UploadistaError.fromCode("TYPE_CATEGORY_MISMATCH", {
+          body: `Node type "${nodeTypeId}" is registered as "${typeDef.category}" but node "${id}" is type "${type}"`,
+          details: { nodeTypeId, nodeId: id, expectedCategory: "input", actualCategory: typeDef.category },
+        }).toEffect();
+      }
+      if (type === NodeType.output && typeDef.category !== "output") {
+        return yield* UploadistaError.fromCode("TYPE_CATEGORY_MISMATCH", {
+          body: `Node type "${nodeTypeId}" is registered as "${typeDef.category}" but node "${id}" is type "${type}"`,
+          details: { nodeTypeId, nodeId: id, expectedCategory: "output", actualCategory: typeDef.category },
+        }).toEffect();
+      }
+    }
+
+    return {
     id,
     name,
     description,
@@ -199,9 +229,14 @@ export function createFlowNode<Input, Output, TType extends NodeType = NodeType>
           clientId,
         });
 
-        // If the node returned waiting state, pass it through
+        // If the node returned waiting state, add type information and pass through
         if (result.type === "waiting") {
-          return result;
+          return {
+            type: "waiting" as const,
+            partialData: result.partialData,
+            nodeType: nodeTypeId,
+            nodeId: id,
+          };
         }
 
         // Validate output data against schema for completed results
@@ -217,13 +252,20 @@ export function createFlowNode<Input, Output, TType extends NodeType = NodeType>
           },
         });
 
-        return { type: "complete" as const, data: validatedResult };
+        // Return with type information
+        return {
+          type: "complete" as const,
+          data: validatedResult,
+          nodeType: nodeTypeId,
+          nodeId: id,
+        };
       }),
     condition,
     multiInput,
     multiOutput,
     retry,
-  } as FlowNode<Input, Output, UploadistaError> & { type: TType });
+  } as FlowNode<Input, Output, UploadistaError> & { type: TType };
+  });
 }
 
 /**

package/src/flow/nodes/input-node.ts

@@ -6,6 +6,7 @@ import { uploadFileSchema } from "../../types";
 import { UploadServer } from "../../upload";
 import { arrayBuffer, fetchFile } from "../../upload/upload-url";
 import { createFlowNode, NodeType } from "../node";
+import { STREAMING_INPUT_TYPE_ID } from "../node-types";
 import { completeNodeExecution, waitingNodeExecution } from "../types";
 import { resolveUploadMetadata } from "../utils/resolve-upload-metadata";
 
@@ -177,6 +178,7 @@ export function createInputNode(id: string, params?: InputNodeParams) {
       type: NodeType.input,
       inputSchema: inputDataSchema,
       outputSchema: uploadFileSchema,
+      nodeTypeId: STREAMING_INPUT_TYPE_ID,
       run: ({ data, flowId, jobId, clientId }) => {
         return Effect.gen(function* () {
           switch (data.operation) {

package/src/flow/nodes/storage-node.ts

@@ -4,6 +4,7 @@ import { UploadistaError } from "../../errors";
 import { type UploadFile, uploadFileSchema } from "../../types";
 import { UploadServer } from "../../upload";
 import { createFlowNode, NodeType } from "../node";
+import { STORAGE_OUTPUT_TYPE_ID } from "../node-types";
 import { completeNodeExecution } from "../types";
 import { resolveUploadMetadata } from "../utils/resolve-upload-metadata";
 
@@ -61,6 +62,7 @@ export function createStorageNode(
       type: NodeType.output,
       inputSchema: uploadFileSchema,
       outputSchema: uploadFileSchema,
+      nodeTypeId: STORAGE_OUTPUT_TYPE_ID,
       run: ({ data: file, storageId, flowId, jobId, clientId }) => {
         return Effect.gen(function* () {
           const { type, fileName, metadata, metadataJson } =