@uploadista/core 0.0.13 → 0.0.14

package/src/flow/type-guards.ts

@@ -0,0 +1,293 @@
+/**
+ * Type guards and helpers for safe type narrowing of flow results.
+ *
+ * This module provides runtime type guards for discriminating between different
+ * types of flow outputs. Type guards validate both the type tag and the data
+ * structure against registered schemas.
+ *
+ * @module flow/type-guards
+ *
+ * @example
+ * ```typescript
+ * import { isStorageOutput, filterOutputsByType } from "@uploadista/core/flow";
+ *
+ * // Type-safe result consumption
+ * if (result.success && result.flowOutputs) {
+ *   const storageOutputs = filterOutputsByType(result.flowOutputs, isStorageOutput);
+ *   for (const output of storageOutputs) {
+ *     // output.data is typed as UploadFile
+ *     console.log("Stored at:", output.data.url);
+ *   }
+ * }
+ * ```
+ */
+
+import { Effect } from "effect";
+import { UploadistaError } from "../errors";
+import type { UploadFile } from "../types";
+import type { TypedOutput } from "./types/flow-types";
+import { flowTypeRegistry } from "./type-registry";
+
+/**
+ * Factory function to create type guards for specific node types.
+ *
+ * Creates a TypeScript type guard that validates both the type tag and
+ * the data structure against the registered schema. This enables type-safe
+ * narrowing of TypedOutput objects in TypeScript.
+ *
+ * @template T - The expected TypeScript type after narrowing
+ * @param typeId - The registered type ID to check against (e.g., "storage-output-v1")
+ * @returns A type guard function that narrows TypedOutput to TypedOutput<T>
+ *
+ * @example
+ * ```typescript
+ * import { createTypeGuard } from "@uploadista/core/flow";
+ * import { z } from "zod";
+ *
+ * const descriptionSchema = z.object({
+ *   description: z.string(),
+ *   confidence: z.number(),
+ * });
+ *
+ * type DescriptionOutput = z.infer<typeof descriptionSchema>;
+ *
+ * const isDescriptionOutput = createTypeGuard<DescriptionOutput>(
+ *   "description-output-v1"
+ * );
+ *
+ * // Use in code
+ * if (isDescriptionOutput(output)) {
+ *   // output.data is typed as DescriptionOutput
+ *   console.log(output.data.description);
+ * }
+ * ```
+ */
+export function createTypeGuard<T>(
+  typeId: string,
+): (output: TypedOutput) => output is TypedOutput<T> {
+  return (output: TypedOutput): output is TypedOutput<T> => {
+    // Check type matches
+    if (output.nodeType !== typeId) return false;
+
+    // Validate against registered schema
+    const typeDef = flowTypeRegistry.get(typeId);
+    if (!typeDef) return false;
+
+    const result = typeDef.schema.safeParse(output.data);
+    return result.success;
+  };
+}
+
+/**
+ * Type guard for storage output nodes.
+ *
+ * Validates that an output is from a storage node and contains valid UploadFile data.
+ *
+ * @param output - The output to check
+ * @returns True if the output is a storage output with valid UploadFile data
+ *
+ * @example
+ * ```typescript
+ * import { isStorageOutput } from "@uploadista/core/flow";
+ *
+ * if (isStorageOutput(output)) {
+ *   // output.data is typed as UploadFile
+ *   console.log("File URL:", output.data.url);
+ *   console.log("File size:", output.data.size);
+ * }
+ * ```
+ */
+export const isStorageOutput = createTypeGuard<UploadFile>(
+  "storage-output-v1",
+);
+
+/**
+ * Filter an array of outputs to only those matching a specific type.
+ *
+ * This helper function filters outputs using a type guard and returns a
+ * properly typed array of results. It's useful for extracting specific
+ * output types from multi-output flows.
+ *
+ * @template T - The expected output data type
+ * @param outputs - Array of typed outputs to filter
+ * @param typeGuard - Type guard function to use for filtering
+ * @returns Array of outputs that match the type guard, properly typed
+ *
+ * @example
+ * ```typescript
+ * import { filterOutputsByType, isStorageOutput } from "@uploadista/core/flow";
+ *
+ * // Get all storage outputs from a multi-output flow
+ * const storageOutputs = filterOutputsByType(
+ *   flowResult.outputs,
+ *   isStorageOutput
+ * );
+ *
+ * for (const output of storageOutputs) {
+ *   // Each output.data is typed as UploadFile
+ *   console.log("Saved file:", output.data.url);
+ * }
+ * ```
+ */
+export function filterOutputsByType<T>(
+  outputs: TypedOutput[],
+  typeGuard: (output: TypedOutput) => output is TypedOutput<T>,
+): TypedOutput<T>[] {
+  return outputs.filter(typeGuard);
+}
+
+/**
+ * Get a single output of a specific type from an array of outputs.
+ *
+ * This helper function finds exactly one output matching the type guard.
+ * It throws an error if no outputs match or if multiple outputs match,
+ * ensuring the caller receives exactly the expected result.
+ *
+ * @template T - The expected output data type
+ * @param outputs - Array of typed outputs to search
+ * @param typeGuard - Type guard function to use for matching
+ * @returns The single matching output, properly typed
+ * @throws {UploadistaError} If no outputs match (OUTPUT_NOT_FOUND)
+ * @throws {UploadistaError} If multiple outputs match (MULTIPLE_OUTPUTS_FOUND)
+ *
+ * @example
+ * ```typescript
+ * import { getSingleOutputByType, isStorageOutput } from "@uploadista/core/flow";
+ *
+ * try {
+ *   const storageOutput = getSingleOutputByType(
+ *     flowResult.outputs,
+ *     isStorageOutput
+ *   );
+ *   // storageOutput.data is typed as UploadFile
+ *   console.log("File saved at:", storageOutput.data.url);
+ * } catch (error) {
+ *   if (error.code === "OUTPUT_NOT_FOUND") {
+ *     console.error("No storage output found");
+ *   } else if (error.code === "MULTIPLE_OUTPUTS_FOUND") {
+ *     console.error("Multiple storage outputs found, expected one");
+ *   }
+ * }
+ * ```
+ */
+export function getSingleOutputByType<T>(
+  outputs: TypedOutput[],
+  typeGuard: (output: TypedOutput) => output is TypedOutput<T>,
+): Effect.Effect<TypedOutput<T>, UploadistaError> {
+  return Effect.gen(function* () {
+    const filtered = filterOutputsByType(outputs, typeGuard);
+
+    if (filtered.length === 0) {
+      return yield* UploadistaError.fromCode("OUTPUT_NOT_FOUND", {
+        body: "No output of the specified type was found in the flow results",
+      }).toEffect();
+    }
+
+    if (filtered.length > 1) {
+      return yield* UploadistaError.fromCode("MULTIPLE_OUTPUTS_FOUND", {
+        body: `Found ${filtered.length} outputs of the specified type, expected exactly one`,
+        details: {
+          foundCount: filtered.length,
+          nodeIds: filtered.map((o) => o.nodeId),
+        },
+      }).toEffect();
+    }
+
+    // TypeScript knows filtered.length is 1 here due to the checks above
+    // biome-ignore lint/style/noNonNullAssertion: We've checked the length above
+    return filtered[0]!;
+  });
+}
+
+/**
+ * Get the first output of a specific type, if any exists.
+ *
+ * Unlike getSingleOutputByType, this function returns undefined if no outputs
+ * match, and returns the first match if multiple outputs exist. This is useful
+ * when you want a more lenient matching strategy.
+ *
+ * @template T - The expected output data type
+ * @param outputs - Array of typed outputs to search
+ * @param typeGuard - Type guard function to use for matching
+ * @returns The first matching output, or undefined if none match
+ *
+ * @example
+ * ```typescript
+ * import { getFirstOutputByType, isStorageOutput } from "@uploadista/core/flow";
+ *
+ * const storageOutput = getFirstOutputByType(
+ *   flowResult.outputs,
+ *   isStorageOutput
+ * );
+ *
+ * if (storageOutput) {
+ *   console.log("First storage output:", storageOutput.data.url);
+ * } else {
+ *   console.log("No storage outputs found");
+ * }
+ * ```
+ */
+export function getFirstOutputByType<T>(
+  outputs: TypedOutput[],
+  typeGuard: (output: TypedOutput) => output is TypedOutput<T>,
+): TypedOutput<T> | undefined {
+  const filtered = filterOutputsByType(outputs, typeGuard);
+  return filtered[0];
+}
+
+/**
+ * Get an output by its node ID.
+ *
+ * This helper finds an output produced by a specific node instance,
+ * regardless of its type. Useful when you know the specific node ID
+ * you're looking for.
+ *
+ * @param outputs - Array of typed outputs to search
+ * @param nodeId - The node ID to match
+ * @returns The output from the specified node, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * import { getOutputByNodeId } from "@uploadista/core/flow";
+ *
+ * const cdnOutput = getOutputByNodeId(flowResult.outputs, "cdn-storage");
+ * if (cdnOutput) {
+ *   console.log("CDN output:", cdnOutput.data);
+ * }
+ * ```
+ */
+export function getOutputByNodeId(
+  outputs: TypedOutput[],
+  nodeId: string,
+): TypedOutput | undefined {
+  return outputs.find((output) => output.nodeId === nodeId);
+}
+
+/**
+ * Check if any outputs match a specific type.
+ *
+ * Simple predicate function to check if at least one output of a given
+ * type exists in the results.
+ *
+ * @template T - The expected output data type
+ * @param outputs - Array of typed outputs to check
+ * @param typeGuard - Type guard function to use for checking
+ * @returns True if at least one output matches the type guard
+ *
+ * @example
+ * ```typescript
+ * import { hasOutputOfType, isStorageOutput } from "@uploadista/core/flow";
+ *
+ * if (hasOutputOfType(flowResult.outputs, isStorageOutput)) {
+ *   console.log("Flow produced at least one storage output");
+ * } else {
+ *   console.log("No storage outputs in this flow");
+ * }
+ * ```
+ */
+export function hasOutputOfType<T>(
+  outputs: TypedOutput[],
+  typeGuard: (output: TypedOutput) => output is TypedOutput<T>,
+): boolean {
+  return outputs.some(typeGuard);
+}

package/src/flow/type-registry.ts

@@ -0,0 +1,345 @@
+/**
+ * Type registry system for flow input and output nodes.
+ *
+ * This module provides a centralized registry for node type definitions with schemas
+ * and metadata. The registry enables type-safe flow result consumption in dynamic
+ * client environments by allowing clients to safely cast flow results based on
+ * registered node types.
+ *
+ * @module flow/type-registry
+ * @see {@link FlowTypeRegistry} for the registry implementation
+ * @see {@link NodeTypeDefinition} for type definition structure
+ *
+ * @example
+ * ```typescript
+ * // Register a custom output type
+ * import { flowTypeRegistry } from "@uploadista/core/flow";
+ * import { z } from "zod";
+ *
+ * const descriptionOutputSchema = z.object({
+ *   description: z.string(),
+ *   confidence: z.number(),
+ * });
+ *
+ * flowTypeRegistry.register({
+ *   id: "description-output-v1",
+ *   category: "output",
+ *   schema: descriptionOutputSchema,
+ *   version: "1.0.0",
+ *   description: "AI-powered image description output",
+ * });
+ *
+ * // Later, validate data against the registered type
+ * const result = flowTypeRegistry.validate("description-output-v1", data);
+ * if (result.success) {
+ *   console.log(result.data.description);
+ * }
+ * ```
+ */
+
+import type { z } from "zod";
+import { UploadistaError } from "../errors";
+
+/**
+ * Node type category - determines where the node appears in the flow.
+ *
+ * - `input`: Nodes that receive data from external sources (e.g., file uploads)
+ * - `output`: Nodes that produce final results (e.g., storage, webhooks, descriptions)
+ */
+export type NodeTypeCategory = "input" | "output";
+
+/**
+ * Defines a registered node type with its schema and metadata.
+ *
+ * Node type definitions are registered globally and used to validate and type-narrow
+ * flow results at runtime. Each definition includes:
+ * - A unique identifier with versioning
+ * - A category (input or output)
+ * - A Zod schema for runtime validation
+ * - A semantic version for evolution
+ * - A human-readable description
+ *
+ * @template TSchema - The Zod schema type for this node's data
+ *
+ * @property id - Unique identifier (e.g., "storage-output-v1", "webhook-output-v1")
+ * @property category - Whether this is an input or output node type
+ * @property schema - Zod schema for validating data produced by this node type
+ * @property version - Semantic version (e.g., "1.0.0") for tracking type evolution
+ * @property description - Human-readable explanation of what this node type does
+ *
+ * @example
+ * ```typescript
+ * const storageOutputDef: NodeTypeDefinition<z.infer<typeof uploadFileSchema>> = {
+ *   id: "storage-output-v1",
+ *   category: "output",
+ *   schema: uploadFileSchema,
+ *   version: "1.0.0",
+ *   description: "Storage output node that saves files to configured storage backend",
+ * };
+ * ```
+ */
+export interface NodeTypeDefinition<TSchema = unknown> {
+  id: string;
+  category: NodeTypeCategory;
+  schema: z.ZodSchema<TSchema>;
+  version: string;
+  description: string;
+}
+
+/**
+ * Result type for validation operations.
+ *
+ * @template T - The expected type on successful validation
+ */
+export type ValidationResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: UploadistaError };
+
+/**
+ * Central registry for node type definitions.
+ *
+ * The FlowTypeRegistry maintains a global registry of node types with their schemas
+ * and metadata. It provides methods for:
+ * - Registering new node types
+ * - Retrieving type definitions
+ * - Listing types by category
+ * - Validating data against registered schemas
+ *
+ * The registry is immutable after registration - types cannot be modified or removed
+ * once registered to prevent runtime errors.
+ *
+ * @remarks
+ * - This is a singleton - use the exported `flowTypeRegistry` instance
+ * - Types cannot be unregistered or modified after registration
+ * - Duplicate type IDs are rejected
+ * - Version strings should follow semantic versioning
+ *
+ * @example
+ * ```typescript
+ * // Register a new type
+ * flowTypeRegistry.register({
+ *   id: "webhook-output-v1",
+ *   category: "output",
+ *   schema: webhookResponseSchema,
+ *   version: "1.0.0",
+ *   description: "HTTP webhook notification output",
+ * });
+ *
+ * // Retrieve a type definition
+ * const def = flowTypeRegistry.get("webhook-output-v1");
+ * if (def) {
+ *   console.log(def.description);
+ * }
+ *
+ * // List all output types
+ * const outputTypes = flowTypeRegistry.listByCategory("output");
+ * console.log(outputTypes.map(t => t.id));
+ *
+ * // Validate data
+ * const result = flowTypeRegistry.validate("webhook-output-v1", data);
+ * if (result.success) {
+ *   // data is now typed according to the schema
+ *   processWebhookResponse(result.data);
+ * }
+ * ```
+ */
+export class FlowTypeRegistry {
+  private readonly types: Map<string, NodeTypeDefinition<unknown>>;
+
+  constructor() {
+    this.types = new Map();
+  }
+
+  /**
+   * Register a new node type in the registry.
+   *
+   * Once registered, a type cannot be modified or removed. Attempting to register
+   * a type with a duplicate ID will throw an error.
+   *
+   * @template T - The TypeScript type inferred from the Zod schema
+   * @param definition - The complete type definition including schema and metadata
+   * @throws {UploadistaError} If a type with the same ID is already registered
+   *
+   * @example
+   * ```typescript
+   * import { z } from "zod";
+   *
+   * flowTypeRegistry.register({
+   *   id: "description-output-v1",
+   *   category: "output",
+   *   schema: z.object({
+   *     description: z.string(),
+   *     confidence: z.number().min(0).max(1),
+   *     tags: z.array(z.string()).optional(),
+   *   }),
+   *   version: "1.0.0",
+   *   description: "AI-generated image description with confidence score",
+   * });
+   * ```
+   */
+  register<T>(definition: NodeTypeDefinition<T>): void {
+    if (this.types.has(definition.id)) {
+      throw UploadistaError.fromCode("VALIDATION_ERROR", {
+        body: `Node type "${definition.id}" is already registered. Types cannot be modified or re-registered.`,
+        details: { typeId: definition.id },
+      });
+    }
+
+    // Store as unknown to avoid generic constraints in the Map
+    this.types.set(definition.id, definition as NodeTypeDefinition<unknown>);
+  }
+
+  /**
+   * Retrieve a registered type definition by its ID.
+   *
+   * @param id - The unique type identifier (e.g., "storage-output-v1")
+   * @returns The type definition if found, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * const def = flowTypeRegistry.get("storage-output-v1");
+   * if (def) {
+   *   console.log(`Found ${def.description} (v${def.version})`);
+   * } else {
+   *   console.warn("Type not registered");
+   * }
+   * ```
+   */
+  get(id: string): NodeTypeDefinition<unknown> | undefined {
+    return this.types.get(id);
+  }
+
+  /**
+   * List all registered types in a specific category.
+   *
+   * @param category - The node category to filter by ("input" or "output")
+   * @returns Array of type definitions in the specified category
+   *
+   * @example
+   * ```typescript
+   * // List all registered output types
+   * const outputTypes = flowTypeRegistry.listByCategory("output");
+   * console.log("Available output types:");
+   * for (const type of outputTypes) {
+   *   console.log(`- ${type.id}: ${type.description}`);
+   * }
+   * ```
+   */
+  listByCategory(category: NodeTypeCategory): NodeTypeDefinition<unknown>[] {
+    const result: NodeTypeDefinition<unknown>[] = [];
+    for (const definition of this.types.values()) {
+      if (definition.category === category) {
+        result.push(definition);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Validate data against a registered type's schema.
+   *
+   * This method performs runtime validation using the Zod schema associated with
+   * the type. If validation succeeds, the data is returned with proper typing.
+   * If validation fails, an UploadistaError is returned with details.
+   *
+   * @template T - The expected TypeScript type after validation
+   * @param typeId - The ID of the registered type to validate against
+   * @param data - The data to validate
+   * @returns A result object with either the validated data or an error
+   *
+   * @example
+   * ```typescript
+   * const result = flowTypeRegistry.validate("storage-output-v1", unknownData);
+   *
+   * if (result.success) {
+   *   // TypeScript knows result.data is an UploadFile
+   *   console.log(`File stored at: ${result.data.url}`);
+   * } else {
+   *   console.error(`Validation failed: ${result.error.body}`);
+   * }
+   * ```
+   */
+  validate<T>(typeId: string, data: unknown): ValidationResult<T> {
+    const typeDef = this.types.get(typeId);
+
+    if (!typeDef) {
+      return {
+        success: false,
+        error: UploadistaError.fromCode("VALIDATION_ERROR", {
+          body: `Node type "${typeId}" is not registered`,
+          details: { typeId },
+        }),
+      };
+    }
+
+    try {
+      const parsed = typeDef.schema.parse(data);
+      return { success: true, data: parsed as T };
+    } catch (error) {
+      return {
+        success: false,
+        error: UploadistaError.fromCode("VALIDATION_ERROR", {
+          body: `Data validation failed for type "${typeId}"`,
+          cause: error,
+          details: { typeId, validationErrors: error },
+        }),
+      };
+    }
+  }
+
+  /**
+   * Check if a type is registered.
+   *
+   * @param id - The unique type identifier to check
+   * @returns True if the type is registered, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (flowTypeRegistry.has("custom-output-v1")) {
+   *   console.log("Custom output type is available");
+   * }
+   * ```
+   */
+  has(id: string): boolean {
+    return this.types.has(id);
+  }
+
+  /**
+   * Get the total number of registered types.
+   *
+   * @returns The count of registered types
+   *
+   * @example
+   * ```typescript
+   * console.log(`Registry contains ${flowTypeRegistry.size()} types`);
+   * ```
+   */
+  size(): number {
+    return this.types.size;
+  }
+}
+
+/**
+ * Global singleton instance of the flow type registry.
+ *
+ * Use this instance to register and access node type definitions throughout
+ * your application. The registry is initialized once and shared globally.
+ *
+ * @example
+ * ```typescript
+ * import { flowTypeRegistry } from "@uploadista/core/flow";
+ *
+ * // Register a type
+ * flowTypeRegistry.register({
+ *   id: "my-output-v1",
+ *   category: "output",
+ *   schema: mySchema,
+ *   version: "1.0.0",
+ *   description: "My custom output type",
+ * });
+ *
+ * // Validate data
+ * const result = flowTypeRegistry.validate("my-output-v1", data);
+ * ```
+ */
+export const flowTypeRegistry = new FlowTypeRegistry();