@uploadista/core 0.0.10 → 0.0.12

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

@@ -0,0 +1,283 @@
+import { z } from "zod";
+
+/**
+ * Type of transformation to apply to an image.
+ */
+export type TransformationType =
+  | "resize"
+  | "blur"
+  | "rotate"
+  | "flip"
+  | "grayscale"
+  | "sepia"
+  | "brightness"
+  | "contrast"
+  | "sharpen"
+  | "watermark"
+  | "logo"
+  | "text";
+
+// ============================================================================
+// Basic Transformations
+// ============================================================================
+
+/**
+ * Resize transformation parameters.
+ * Resizes the image to the specified dimensions with the given fit mode.
+ */
+export const resizeTransformSchema = z.object({
+  type: z.literal("resize"),
+  /** 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"]),
+});
+
+export type ResizeTransform = z.infer<typeof resizeTransformSchema>;
+
+/**
+ * Blur transformation parameters.
+ * Applies Gaussian blur to the image.
+ */
+export const blurTransformSchema = z.object({
+  type: z.literal("blur"),
+  /** Blur strength (sigma). Range: 0.3 to 1000 */
+  sigma: z.number().min(0.3).max(1000),
+});
+
+export type BlurTransform = z.infer<typeof blurTransformSchema>;
+
+/**
+ * Rotate transformation parameters.
+ * Rotates the image by the specified angle.
+ */
+export const rotateTransformSchema = z.object({
+  type: z.literal("rotate"),
+  /** Rotation angle in degrees. Positive values rotate clockwise. */
+  angle: z.number(),
+  /** Background color for exposed areas (optional, defaults to transparent) */
+  background: z.string().optional(),
+});
+
+export type RotateTransform = z.infer<typeof rotateTransformSchema>;
+
+/**
+ * Flip transformation parameters.
+ * Flips the image horizontally or vertically.
+ */
+export const flipTransformSchema = z.object({
+  type: z.literal("flip"),
+  /** Direction to flip the image */
+  direction: z.enum(["horizontal", "vertical"]),
+});
+
+export type FlipTransform = z.infer<typeof flipTransformSchema>;
+
+// ============================================================================
+// Filter Transformations
+// ============================================================================
+
+/**
+ * Grayscale transformation parameters.
+ * Converts the image to grayscale.
+ */
+export const grayscaleTransformSchema = z.object({
+  type: z.literal("grayscale"),
+});
+
+export type GrayscaleTransform = z.infer<typeof grayscaleTransformSchema>;
+
+/**
+ * Sepia transformation parameters.
+ * Applies a sepia tone effect to the image.
+ */
+export const sepiaTransformSchema = z.object({
+  type: z.literal("sepia"),
+});
+
+export type SepiaTransform = z.infer<typeof sepiaTransformSchema>;
+
+/**
+ * Brightness transformation parameters.
+ * Adjusts the brightness of the image.
+ */
+export const brightnessTransformSchema = z.object({
+  type: z.literal("brightness"),
+  /** Brightness adjustment value. Range: -100 to +100. 0 = no change. */
+  value: z.number().min(-100).max(100),
+});
+
+export type BrightnessTransform = z.infer<typeof brightnessTransformSchema>;
+
+/**
+ * Contrast transformation parameters.
+ * Adjusts the contrast of the image.
+ */
+export const contrastTransformSchema = z.object({
+  type: z.literal("contrast"),
+  /** Contrast adjustment value. Range: -100 to +100. 0 = no change. */
+  value: z.number().min(-100).max(100),
+});
+
+export type ContrastTransform = z.infer<typeof contrastTransformSchema>;
+
+// ============================================================================
+// Effect Transformations
+// ============================================================================
+
+/**
+ * Sharpen transformation parameters.
+ * Applies sharpening to the image.
+ */
+export const sharpenTransformSchema = z.object({
+  type: z.literal("sharpen"),
+  /** Sharpening strength (sigma). Optional, uses default if not specified. */
+  sigma: z.number().positive().optional(),
+});
+
+export type SharpenTransform = z.infer<typeof sharpenTransformSchema>;
+
+// ============================================================================
+// Advanced Transformations
+// ============================================================================
+
+/**
+ * Position for overlays (watermarks, logos, text).
+ */
+export type OverlayPosition =
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right"
+  | "center";
+
+/**
+ * Watermark transformation parameters.
+ * Overlays a watermark image on the main image.
+ */
+export const watermarkTransformSchema = z.object({
+  type: z.literal("watermark"),
+  /** URL to the watermark image file (e.g., https://example.com/watermark.png) */
+  imagePath: z.string().min(1).url(),
+  /** Position of the watermark on the image */
+  position: z.enum([
+    "top-left",
+    "top-right",
+    "bottom-left",
+    "bottom-right",
+    "center",
+  ]),
+  /** Opacity of the watermark. Range: 0 (transparent) to 1 (opaque) */
+  opacity: z.number().min(0).max(1),
+  /** Horizontal offset in pixels from the position anchor (optional) */
+  offsetX: z.number().optional(),
+  /** Vertical offset in pixels from the position anchor (optional) */
+  offsetY: z.number().optional(),
+});
+
+export type WatermarkTransform = z.infer<typeof watermarkTransformSchema>;
+
+/**
+ * Logo transformation parameters.
+ * Overlays a logo image on the main image with scaling.
+ */
+export const logoTransformSchema = z.object({
+  type: z.literal("logo"),
+  /** URL to the logo image file (e.g., https://example.com/logo.png) */
+  imagePath: z.string().min(1).url(),
+  /** Position of the logo on the image */
+  position: z.enum([
+    "top-left",
+    "top-right",
+    "bottom-left",
+    "bottom-right",
+    "center",
+  ]),
+  /** Scale factor for the logo. Range: 0.1 to 2.0 */
+  scale: z.number().min(0.1).max(2.0),
+  /** Horizontal offset in pixels from the position anchor (optional) */
+  offsetX: z.number().optional(),
+  /** Vertical offset in pixels from the position anchor (optional) */
+  offsetY: z.number().optional(),
+});
+
+export type LogoTransform = z.infer<typeof logoTransformSchema>;
+
+/**
+ * Text transformation parameters.
+ * Overlays text on the image.
+ */
+export const textTransformSchema = z.object({
+  type: z.literal("text"),
+  /** Text content to overlay */
+  text: z.string().min(1),
+  /** Position of the text on the image */
+  position: z.enum([
+    "top-left",
+    "top-right",
+    "bottom-left",
+    "bottom-right",
+    "center",
+  ]),
+  /** Font size in pixels */
+  fontSize: z.number().positive(),
+  /** Text color (hex code or named color) */
+  color: z.string().min(1),
+  /** Font family name (optional) */
+  fontFamily: z.string().optional(),
+  /** Horizontal offset in pixels from the position anchor (optional) */
+  offsetX: z.number().optional(),
+  /** Vertical offset in pixels from the position anchor (optional) */
+  offsetY: z.number().optional(),
+});
+
+export type TextTransform = z.infer<typeof textTransformSchema>;
+
+// ============================================================================
+// Discriminated Union
+// ============================================================================
+
+/**
+ * Schema for validating any transformation type.
+ * This is a discriminated union of all transformation schemas.
+ */
+export const transformationSchema = z.discriminatedUnion("type", [
+  resizeTransformSchema,
+  blurTransformSchema,
+  rotateTransformSchema,
+  flipTransformSchema,
+  grayscaleTransformSchema,
+  sepiaTransformSchema,
+  brightnessTransformSchema,
+  contrastTransformSchema,
+  sharpenTransformSchema,
+  watermarkTransformSchema,
+  logoTransformSchema,
+  textTransformSchema,
+]);
+
+/**
+ * A single image transformation operation.
+ * This is a discriminated union type that can represent any transformation.
+ */
+export type Transformation = z.infer<typeof transformationSchema>;
+
+// ============================================================================
+// Transform Image Node Parameters
+// ============================================================================
+
+/**
+ * Parameters for the transform image node.
+ * Contains an ordered array of transformations to apply sequentially.
+ */
+export const transformImageParamsSchema = z.object({
+  /** Ordered array of transformations to apply. Applied sequentially. */
+  transformations: z.array(transformationSchema).min(1),
+});
+
+/**
+ * Parameters for the transform image node.
+ */
+export type TransformImageParams = z.infer<typeof transformImageParamsSchema>;

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

@@ -1,5 +1,5 @@
 import type { UploadistaError } from "@uploadista/core/errors";
-import { Context, type Effect } from "effect";
+import { Context, type Effect, type Layer } from "effect";
 import type { UploadFile } from "@/types";
 
 /**
@@ -40,7 +40,7 @@ export type ZipPluginShape = {
    */
   zip: (
     inputs: ZipInput[],
-    options: ZipParams
+    options: ZipParams,
   ) => Effect.Effect<Uint8Array, UploadistaError>;
   // unzip: (input: ZipInput) => Effect.Effect<Uint8Array, UploadistaError>;
 };
@@ -67,3 +67,5 @@ export class ZipPlugin extends Context.Tag("ZipPlugin")<
   ZipPlugin,
   ZipPluginShape
 >() {}
+
+export type ZipPluginLayer = Layer.Layer<ZipPlugin, never, never>;

package/src/flow/typed-flow.ts

@@ -11,58 +11,163 @@ import type { Flow, FlowExecutionResult } from "./flow";
 import { createFlowWithSchema } from "./flow";
 import { NodeType } from "./node";
 import type {
-  FlowEdge,
-  FlowNode,
-  TypeCompatibilityChecker,
+	FlowEdge,
+	FlowNode,
+	TypeCompatibilityChecker,
 } from "./types/flow-types";
+import type { ExtractEffectRequirements, ResolveEffect } from "./types";
 
+/**
+ * Defines a node that can be used in a typed flow.
+ *
+ * A node definition can be either:
+ * - A plain FlowNode object
+ * - An Effect that resolves to a FlowNode (for nodes requiring dependencies)
+ *
+ * @template TNodeError - The error types that the node can produce
+ * @template TNodeRequirements - The services/dependencies the node requires
+ */
 export type NodeDefinition<TNodeError = never, TNodeRequirements = never> =
-  | FlowNode<any, any, CoreUploadistaError>
-  | Effect.Effect<
-      FlowNode<any, any, CoreUploadistaError>,
-      TNodeError,
-      TNodeRequirements
-    >;
+	| FlowNode<any, any, CoreUploadistaError>
+	| Effect.Effect<
+			FlowNode<any, any, CoreUploadistaError>,
+			TNodeError,
+			TNodeRequirements
+		>;
 
+/**
+ * A record mapping node IDs to their definitions.
+ *
+ * This is the primary type used for defining the nodes in a typed flow,
+ * allowing TypeScript to infer input/output schemas and requirements.
+ *
+ * @example
+ * ```typescript
+ * const nodes = {
+ *   input: fileInputNode,
+ *   resize: Effect.succeed(imageResizeNode),
+ *   output: s3OutputNode
+ * } satisfies NodeDefinitionsRecord;
+ * ```
+ */
 export type NodeDefinitionsRecord = Record<string, NodeDefinition<any, any>>;
 
+/**
+ * Extracts the error type from a NodeDefinition.
+ *
+ * If the node is an Effect, extracts its error type.
+ * If the node is a plain FlowNode, returns never (no errors).
+ */
 type NodeDefinitionError<T> = T extends Effect.Effect<
-  FlowNode<any, any, CoreUploadistaError>,
-  infer TError,
-  any
+	FlowNode<any, any, CoreUploadistaError>,
+	infer TError,
+	any
 >
-  ? TError
-  : never;
+	? TError
+	: never;
 
-type NodeDefinitionRequirements<T> = T extends Effect.Effect<
-  FlowNode<any, any, CoreUploadistaError>,
-  any,
-  infer TRequirements
->
-  ? TRequirements
-  : never;
+/**
+ * Extracts the requirements (dependencies) from a NodeDefinition.
+ *
+ * Uses the shared ExtractEffectRequirements utility for consistency.
+ */
+type NodeDefinitionRequirements<T> = ExtractEffectRequirements<T>;
 
+/**
+ * Extracts all possible errors from all nodes in a flow as a union.
+ *
+ * This iterates through all nodes in the record and combines their
+ * error types into a single union type.
+ */
 type NodesErrorUnion<TNodes extends NodeDefinitionsRecord> = {
-  [K in keyof TNodes]: NodeDefinitionError<TNodes[K]>;
+	[K in keyof TNodes]: NodeDefinitionError<TNodes[K]>;
 }[keyof TNodes];
 
+/**
+ * Extracts all service requirements from all nodes in a flow as a union.
+ *
+ * This iterates through all nodes in the record and combines their
+ * requirement types into a single union type representing all services
+ * needed by the flow.
+ *
+ * @template TNodes - The record of node definitions
+ *
+ * @example
+ * ```typescript
+ * const nodes = {
+ *   resize: imageResizeNode, // requires ImagePlugin
+ *   zip: zipNode,           // requires ZipPlugin
+ * };
+ * type Requirements = NodesRequirementsUnion<typeof nodes>;
+ * // Requirements = ImagePlugin | ZipPlugin
+ * ```
+ */
 type NodesRequirementsUnion<TNodes extends NodeDefinitionsRecord> = {
-  [K in keyof TNodes]: NodeDefinitionRequirements<TNodes[K]>;
+	[K in keyof TNodes]: NodeDefinitionRequirements<TNodes[K]>;
 }[keyof TNodes];
 
+/**
+ * Extracts all service requirements from a flow's nodes.
+ *
+ * This includes all services required by any node in the flow,
+ * including UploadServer (which is provided by the runtime).
+ *
+ * @template TNodes - The record of node definitions
+ *
+ * @example
+ * ```typescript
+ * const myFlow = createFlow({
+ *   nodes: {
+ *     input: fileInputNode,
+ *     process: imageProcessNode, // requires ImagePlugin
+ *   },
+ *   edges: [...]
+ * });
+ * type AllRequirements = FlowRequirements<typeof myFlow.nodes>;
+ * // AllRequirements = ImagePlugin | UploadServer
+ * ```
+ */
 export type FlowRequirements<TNodes extends NodeDefinitionsRecord> =
-  NodesRequirementsUnion<TNodes>;
+	NodesRequirementsUnion<TNodes>;
 
+/**
+ * Extracts plugin service requirements from a flow, excluding UploadServer.
+ *
+ * This type is useful for determining which plugin layers need to be
+ * provided when creating a server, as UploadServer is automatically
+ * provided by the runtime.
+ *
+ * @template TNodes - The record of node definitions
+ *
+ * @example
+ * ```typescript
+ * const myFlow = createFlow({
+ *   nodes: {
+ *     resize: imageResizeNode, // requires ImagePlugin
+ *     upload: s3OutputNode,   // requires UploadServer
+ *   },
+ *   edges: [...]
+ * });
+ * type PluginRequirements = FlowPluginRequirements<typeof myFlow.nodes>;
+ * // PluginRequirements = ImagePlugin (UploadServer excluded)
+ * ```
+ */
 export type FlowPluginRequirements<TNodes extends NodeDefinitionsRecord> =
-  Exclude<FlowRequirements<TNodes>, UploadServer>;
+	Exclude<FlowRequirements<TNodes>, UploadServer>;
 
+/**
+ * Infers the concrete FlowNode type from a NodeDefinition.
+ *
+ * If the definition is already a FlowNode, returns it as-is.
+ * If the definition is an Effect, extracts the FlowNode from the Effect's success type.
+ *
+ * Uses the shared ResolveEffect utility for consistency.
+ */
 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;
+	? T
+	: ResolveEffect<T> extends FlowNode<any, any, CoreUploadistaError>
+		? ResolveEffect<T>
+		: never;
 
 type ResolvedNodesRecord<TNodes extends NodeDefinitionsRecord> = {
   [K in keyof TNodes]: InferNode<TNodes[K]>;
@@ -138,37 +243,71 @@ declare const typedFlowInputsSymbol: unique symbol;
 declare const typedFlowOutputsSymbol: unique symbol;
 declare const typedFlowPluginsSymbol: unique symbol;
 
+/**
+ * A type-safe Flow that infers input/output types and requirements from its nodes.
+ *
+ * TypedFlow extends the base Flow type with additional type information that
+ * allows TypeScript to verify inputs, outputs, and plugin requirements at compile time.
+ *
+ * The phantom type properties (using unique symbols) enable type-level metadata
+ * without affecting runtime behavior, allowing other type utilities to extract
+ * this information for validation purposes.
+ *
+ * @template TNodes - Record of node definitions used in the flow
+ * @template TInputSchema - Zod schema for flow inputs (inferred from input nodes)
+ * @template TOutputSchema - Zod schema for flow outputs (inferred from output nodes)
+ *
+ * @example
+ * ```typescript
+ * const myFlow = createFlow({
+ *   nodes: {
+ *     input: fileInputNode,
+ *     resize: imageResizeNode,
+ *     output: s3OutputNode
+ *   },
+ *   edges: [
+ *     { source: 'input', target: 'resize' },
+ *     { source: 'resize', target: 'output' }
+ *   ]
+ * });
+ *
+ * // TypeScript infers:
+ * // - Input types from fileInputNode.inputSchema
+ * // - Output types from s3OutputNode.outputSchema
+ * // - Requirements: ImagePlugin (from resize node)
+ * ```
+ */
 export type TypedFlow<
-  TNodes extends NodeDefinitionsRecord,
-  TInputSchema extends z.ZodTypeAny,
-  TOutputSchema extends z.ZodTypeAny,
+	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>;
+	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 = (

package/src/flow/types/index.ts

@@ -4,3 +4,6 @@ export type { FlowCondition } from "./flow-file";
 export * from "./flow-types";
 
 export * from "./type-validator";
+
+// Export shared type utilities
+export * from "./type-utils";