@uploadista/server 0.0.10 → 0.0.12

package/src/core/server.ts

@@ -1,4 +1,4 @@
-import type { UploadistaError } from "@uploadista/core";
+import type { PluginLayer, UploadistaError } from "@uploadista/core";
 import { type Flow, FlowProvider, FlowWaitUntil } from "@uploadista/core/flow";
 import {
   createDataStoreLayer,
@@ -18,31 +18,113 @@ import { createFlowServerLayer, createUploadServerLayer } from "../layer-utils";
 import { AuthContextServiceLive } from "../service";
 import type { AuthContext } from "../types";
 import { handleUploadistaRequest } from "./http-handlers/http-handlers";
+import type { ExtractFlowPluginRequirements } from "./plugin-types";
 import type { NotFoundResponse } from "./routes";
 import type { UploadistaServer, UploadistaServerConfig } from "./types";
 
 /**
  * Creates the unified Uploadista server with framework-specific adapter.
  *
- * This function composes all layers (upload server, flow server, auth, metrics)
- * and returns a handler that works with any framework via the provided adapter.
+ * This is the single, unified API for creating an Uploadista server. It handles
+ * all server initialization, layer composition, and runtime setup.
  *
- * The core server handles:
+ * ## Core Responsibilities
+ *
+ * The server handles:
+ * - Layer composition (upload/flow servers, auth cache, metrics, plugins)
  * - Route parsing and matching
  * - Auth middleware execution with timeout protection
- * - Layer composition (upload/flow servers, auth cache, metrics)
  * - Error handling and response formatting
  * - Effect program execution with optional tracing
+ * - Plugin validation and dependency injection
+ *
+ * ## Plugin Validation
+ *
+ * The server supports two validation approaches:
+ *
+ * ### 1. Runtime Validation (Recommended for Most Cases)
+ *
+ * The server relies on Effect-TS's dependency injection to validate plugins
+ * at runtime. If a required plugin is missing, Effect will fail with a clear
+ * MissingService error.
+ *
+ * ```typescript
+ * const server = await createUploadistaServer({
+ *   flows: getFlowById,
+ *   plugins: [sharpImagePlugin, zipPlugin],
+ *   dataStore: s3DataStore,
+ *   kvStore: redisKvStore,
+ *   adapter: honoAdapter({ ... })
+ * });
+ * // If plugins don't match flow requirements, Effect fails with clear error
+ * ```
+ *
+ * ### 2. Compile-Time Validation (Optional)
+ *
+ * For IDE feedback during development, use the ValidatePlugins type utility:
+ *
+ * ```typescript
+ * import {
+ *   createUploadistaServer,
+ *   ValidatePlugins,
+ *   ExtractFlowPluginRequirements
+ * } from '@uploadista/server';
+ *
+ * // Extract requirements from flows
+ * type Requirements = ExtractFlowPluginRequirements<typeof getFlowById>;
+ *
+ * // Define plugins
+ * const plugins = [sharpImagePlugin, zipPlugin] as const;
+ *
+ * // Validate at compile time (optional, for IDE feedback)
+ * type Validation = ValidatePlugins<typeof plugins, Requirements>;
+ * // IDE shows error if plugins don't match requirements
+ *
+ * const server = await createUploadistaServer({
+ *   flows: getFlowById,
+ *   plugins,
+ *   // ...
+ * });
+ * ```
+ *
+ * ### 3. Early Runtime Validation (Optional)
+ *
+ * For better error messages before server starts:
+ *
+ * ```typescript
+ * import { validatePluginsOrThrow } from '@uploadista/server/core';
+ *
+ * validatePluginsOrThrow({
+ *   plugins: [sharpImagePlugin],
+ *   expectedServices: ['ImagePlugin', 'ZipPlugin']
+ * });
+ * // Throws with helpful error message including import suggestions
+ * ```
+ *
+ * ## Type Safety
+ *
+ * - Plugin requirements are inferred from flow definitions
+ * - Effect-TS ensures dependencies are satisfied at runtime
+ * - Type casting is intentional (see inline docs for rationale)
+ * - Optional compile-time validation available via type utilities
+ *
+ * @template TContext - Framework-specific context type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocketHandler - WebSocket handler type (if supported)
+ * @template TFlows - Flow function type with plugin requirements
+ * @template TPlugins - Tuple of plugin layers provided
  *
  * @param config - Server configuration including adapter and business logic
- * @returns Object with handler function, optional WebSocket handler, and base URL
+ * @returns Promise resolving to server instance with handler and metadata
  *
- * @example
+ * @example Basic Usage
  * ```typescript
  * import { createUploadistaServer, honoAdapter } from "@uploadista/server";
+ * import { sharpImagePlugin } from "@uploadista/flow-images-sharp";
  *
  * const server = await createUploadistaServer({
  *   flows: getFlowById,
+ *   plugins: [sharpImagePlugin],
  *   dataStore: { type: "s3", config: { bucket: "uploads" } },
  *   kvStore: redisKvStore,
  *   adapter: honoAdapter({
@@ -53,16 +135,53 @@ import type { UploadistaServer, UploadistaServerConfig } from "./types";
  * // Use with Hono
  * app.all("/uploadista/*", server.handler);
  * ```
+ *
+ * @example With Compile-Time Validation
+ * ```typescript
+ * import {
+ *   createUploadistaServer,
+ *   ValidatePlugins,
+ *   ExtractFlowPluginRequirements
+ * } from "@uploadista/server";
+ *
+ * type Requirements = ExtractFlowPluginRequirements<typeof getFlowById>;
+ * const plugins = [sharpImagePlugin, zipPlugin] as const;
+ * type Validation = ValidatePlugins<typeof plugins, Requirements>;
+ *
+ * const server = await createUploadistaServer({
+ *   flows: getFlowById,
+ *   plugins,
+ *   // ... rest of config
+ * });
+ * ```
+ *
+ * @see ValidatePlugins - Compile-time plugin validation
+ * @see ExtractFlowPluginRequirements - Extract requirements from flows
+ * @see validatePluginRequirements - Runtime validation helper
+ * @see API_DECISION_GUIDE.md - Complete guide for choosing validation approach
  */
 export const createUploadistaServer = async <
   TContext,
   TResponse,
   TWebSocketHandler = unknown,
+  TFlows extends (
+    flowId: string,
+    clientId: string | null,
+  ) => Effect.Effect<
+    // biome-ignore lint/suspicious/noExplicitAny: Flow requirements can be any plugin services
+    Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, any>,
+    UploadistaError,
+    // biome-ignore lint/suspicious/noExplicitAny: Flow return type allows any requirements
+    any
+    // biome-ignore lint/suspicious/noExplicitAny: Generic type constraint allows any flow function type with any requirements
+  > = any,
+  TPlugins extends readonly PluginLayer[] = readonly PluginLayer[],
 >({
   flows,
   dataStore,
   kvStore,
-  plugins = [],
+  // Default to an empty plugin list while preserving the generic type
+  plugins = [] as unknown as TPlugins,
   eventEmitter,
   eventBroadcaster = memoryEventBroadcaster,
   withTracing = false,
@@ -72,9 +191,13 @@ export const createUploadistaServer = async <
   bufferedDataStore,
   adapter,
   authCacheConfig,
-}: UploadistaServerConfig<TContext, TResponse, TWebSocketHandler>): Promise<
-  UploadistaServer<TContext, TResponse, TWebSocketHandler>
-> => {
+}: UploadistaServerConfig<
+  TContext,
+  TResponse,
+  TWebSocketHandler,
+  TFlows,
+  TPlugins
+>): Promise<UploadistaServer<TContext, TResponse, TWebSocketHandler>> => {
   // Default eventEmitter to webSocketEventEmitter with the provided eventBroadcaster
   const finalEventEmitter =
     eventEmitter ?? webSocketEventEmitter(eventBroadcaster);
@@ -84,6 +207,8 @@ export const createUploadistaServer = async <
     ? configBaseUrl.slice(0, -1)
     : configBaseUrl;
 
+  type FlowReq = ExtractFlowPluginRequirements<TFlows>;
+
   // Create flow provider layer from flows function
   const flowProviderLayer = Layer.effect(
     FlowProvider,
@@ -92,9 +217,8 @@ export const createUploadistaServer = async <
         // Cast the flows function to match FlowProvider expectations
         // The context requirements will be provided at the layer level
         return flows(flowId, clientId) as Effect.Effect<
-          Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, unknown>,
-          UploadistaError,
-          never
+          Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, FlowReq>,
+          UploadistaError
         >;
       },
     }),
@@ -137,7 +261,13 @@ export const createUploadistaServer = async <
   // Metrics layer (defaults to NoOp if not provided)
   const effectiveMetricsLayer = metricsLayer ?? NoOpMetricsServiceLive;
 
-  const serverLayer = Layer.mergeAll(
+  /**
+   * Merge all server layers including plugins.
+   *
+   * This combines the core server infrastructure (upload server, flow server,
+   * metrics, auth cache) with user-provided plugin layers.
+   */
+  const serverLayerRaw = Layer.mergeAll(
     uploadServerLayer,
     flowServerLayer,
     effectiveMetricsLayer,
@@ -145,9 +275,94 @@ export const createUploadistaServer = async <
     ...plugins,
   );
 
+  /**
+   * Type Casting Rationale for Plugin System
+   *
+   * The type assertion below is intentional and safe. This is not a bug or workaround,
+   * but follows Effect-TS's design for dynamic dependency injection.
+   *
+   * ## Why Type Casting is Necessary
+   *
+   * 1. **Plugin Requirements are Dynamic**
+   *    Different flows require different plugins (ImagePlugin, ZipPlugin, etc.).
+   *    These requirements are only known when flows are loaded at runtime.
+   *    Flow A might need ImagePlugin, Flow B might need ZipPlugin.
+   *
+   * 2. **TypeScript's Static Limitation**
+   *    TypeScript cannot statically verify that all possible flow combinations
+   *    will have their requirements satisfied. The plugin array is typed as
+   *    `readonly PluginLayer[]` which could be any combination of plugins.
+   *
+   * 3. **Effect-TS Runtime Resolution**
+   *    Effect-TS is designed to resolve service requirements at runtime using
+   *    its dependency injection system. When a flow executes and accesses a service:
+   *
+   *    ```typescript
+   *    const imagePlugin = yield* ImagePlugin;
+   *    ```
+   *
+   *    Effect checks if ImagePlugin exists in the provided layer context.
+   *    If missing, Effect fails with a clear MissingService error.
+   *
+   * 4. **Layer Composition Guarantees**
+   *    Layer.mergeAll() combines all layers. At runtime, Effect ensures that
+   *    when a service is requested, it's either:
+   *    - Provided by one of the merged layers, OR
+   *    - Results in a MissingService error with the service name
+   *
+   * ## Safety Guarantees
+   *
+   * This pattern is safe because:
+   *
+   * 1. **Runtime Validation** (Optional but Recommended)
+   *    We provide validatePluginRequirements() that checks plugins before
+   *    server initialization, giving excellent error messages early.
+   *
+   * 2. **Effect's Built-in Validation**
+   *    If runtime validation is skipped, Effect will fail during flow execution
+   *    with a MissingService error containing the service identifier.
+   *
+   * 3. **Optional Compile-Time Validation**
+   *    Developers can use ValidatePlugins<> type utility for IDE feedback:
+   *
+   *    ```typescript
+   *    type Validation = ValidatePlugins<typeof plugins, Requirements>;
+   *    // Shows compile error if plugins don't match requirements
+   *    ```
+   *
+   * 4. **No Silent Failures**
+   *    There's no scenario where missing plugins cause silent failures.
+   *    Either runtime validation catches it, or Effect fails with clear error.
+   *
+   * ## This is Effect-TS's Idiomatic Pattern
+   *
+   * Effect-TS separates compile-time structure from runtime resolution:
+   * - Compile-time: Types ensure layer structure is correct
+   * - Runtime: Effect resolves actual dependencies and fails if missing
+   *
+   * The type system provides structure and IDE support, while Effect's
+   * runtime handles actual requirement resolution.
+   *
+   * ## Further Reading
+   *
+   * - Effect-TS Context Management: https://effect.website/docs/guides/context-management
+   * - Runtime Validation: See plugin-validation.ts for helper functions
+   * - Type Utilities: See plugin-types.ts for compile-time validation
+   *
+   * @see validatePluginRequirements - Runtime validation helper
+   * @see ValidatePlugins - Compile-time validation type utility
+   */
+  const serverLayer = serverLayerRaw as unknown as Layer.Layer<
+    // biome-ignore lint/suspicious/noExplicitAny: Dynamic plugin requirements require any - see comprehensive explanation above
+    any,
+    never,
+    never
+  >;
+
   // Create a shared managed runtime from the server layer
   // This ensures all requests use the same layer instances (including event broadcaster)
   // ManagedRuntime properly handles scoped resources and provides convenient run methods
+
   const managedRuntime = ManagedRuntime.make(serverLayer);
 
   /**
@@ -247,6 +462,7 @@ export const createUploadistaServer = async <
 
       // Extract waitUntil callback if available (for Cloudflare Workers)
       // This must be extracted per-request since it comes from the framework context
+      // biome-ignore lint/suspicious/noExplicitAny: Layer array needs to accept any service type from waitUntil
       const waitUntilLayers: Layer.Layer<any, never, never>[] = [];
       if (adapter.extractWaitUntil) {
         const waitUntilCallback = adapter.extractWaitUntil(ctx);

package/src/core/types.ts

@@ -1,4 +1,4 @@
-import type { UploadistaError } from "@uploadista/core";
+import type { PluginLayer, UploadistaError } from "@uploadista/core";
 import type { Flow } from "@uploadista/core/flow";
 import type {
   BaseEventEmitterService,
@@ -9,6 +9,7 @@ import type {
   UploadFileKVStore,
 } from "@uploadista/core/types";
 import type { GenerateId } from "@uploadista/core/utils";
+import type { MetricsService } from "@uploadista/observability";
 import type { Effect, Layer } from "effect";
 import type { z } from "zod";
 import type { ServerAdapter } from "../adapter";
@@ -56,6 +57,8 @@ export type FlowsFunction = (
  * @template TRequest - Framework-specific request type
  * @template TResponse - Framework-specific response type
  * @template TWebSocket - Framework-specific WebSocket type (optional)
+ * @template TFlows - Function type for retrieving flows
+ * @template TPlugins - Tuple of plugin layers that provide requirements for flows
  *
  * @example
  * ```typescript
@@ -84,6 +87,18 @@ export interface UploadistaServerConfig<
   TRequest,
   TResponse,
   TWebSocket = unknown,
+  TFlows extends (
+    flowId: string,
+    clientId: string | null,
+  ) => Effect.Effect<
+    // biome-ignore lint/suspicious/noExplicitAny: Flow requirements can be any plugin services
+    Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, any>,
+    UploadistaError,
+    // biome-ignore lint/suspicious/noExplicitAny: Flow return type allows any requirements
+    any
+    // biome-ignore lint/suspicious/noExplicitAny: Generic type constraint allows any flow function type with any requirements
+  > = any,
+  TPlugins extends readonly PluginLayer[] = readonly PluginLayer[],
 > {
   /**
    * Function for retrieving flows by ID.
@@ -97,7 +112,7 @@ export interface UploadistaServerConfig<
    * flows: (flowId, clientId) => Effect.succeed(myFlows[flowId])
    * ```
    */
-  flows: FlowsFunction;
+  flows: TFlows;
 
   /**
    * Data store configuration for file storage.
@@ -144,8 +159,7 @@ export interface UploadistaServerConfig<
    * plugins: [imageProcessingPlugin, virusScanPlugin]
    * ```
    */
-  // biome-ignore lint/suspicious/noExplicitAny: Permissive constraint allows plugin tuples
-  plugins?: readonly Layer.Layer<any, never, never>[];
+  plugins?: TPlugins;
 
   /**
    * Optional: Event emitter layer for progress notifications.
@@ -227,8 +241,7 @@ export interface UploadistaServerConfig<
    * metricsLayer: prometheusMetrics()
    * ```
    */
-  // biome-ignore lint/suspicious/noExplicitAny: MetricsService is defined in @uploadista/observability
-  metricsLayer?: Layer.Layer<any, never, never>;
+  metricsLayer?: Layer.Layer<MetricsService, never, never>;
 
   /**
    * Optional: Buffered data store layer for performance optimization.

package/src/plugins-typing.ts

@@ -1,57 +1,139 @@
+/**
+ * @deprecated This module is deprecated and will be removed in a future version.
+ *
+ * Please migrate to the new consolidated plugin types from `@uploadista/server/core/plugin-types`:
+ *
+ * Migration guide:
+ * - `LayerSuccessUnion<T>` → `ExtractLayerServices<T>` from `@uploadista/core/flow/types`
+ * - `FlowRequirementsOf<T>` → `ExtractFlowPluginRequirements<T>` from `@uploadista/server/core/plugin-types`
+ * - `RequiredPluginsOf<T>` → `ExtractFlowPluginRequirements<T>` from `@uploadista/server/core/plugin-types`
+ * - `PluginAssertion<TFlows, TPlugins>` → `ValidatePlugins<TPlugins, TRequirements>` from `@uploadista/server/core/plugin-types`
+ *
+ * See the migration guide in the documentation for more details.
+ *
+ * @module plugins-typing
+ */
+
 import type { Flow, UploadServer } from "@uploadista/core";
+import type { ExtractLayerServices } from "@uploadista/core/flow/types";
 import type { Effect, Layer } from "effect";
 import type z from "zod";
 
+/**
+ * @deprecated Use `ExtractLayerServices` from `@uploadista/core/flow/types` instead.
+ *
+ * Extracts service types from a tuple of layers.
+ *
+ * @example Migration
+ * ```typescript
+ * // Old
+ * import { LayerSuccessUnion } from '@uploadista/server/plugins-typing';
+ * type Services = LayerSuccessUnion<[ImagePluginLayer, ZipPluginLayer]>;
+ *
+ * // New
+ * import { ExtractLayerServices } from '@uploadista/core/flow/types';
+ * type Services = ExtractLayerServices<[ImagePluginLayer, ZipPluginLayer]>;
+ * ```
+ */
 export type LayerSuccessUnion<
-  Layers extends readonly Layer.Layer<any, never, never>[],
-> = Layers[number] extends Layer.Layer<infer Success, never, never>
-  ? Success
-  : never;
+	Layers extends readonly Layer.Layer<any, never, never>[],
+> = ExtractLayerServices<Layers>;
 
+/**
+ * @deprecated This type is deprecated. Extract flow requirements directly from your flow types instead.
+ *
+ * Extracts the success type from a flow function's Effect return value.
+ */
 export type FlowSuccess<
-  TFlows extends (
-    flowId: string,
-    clientId: string | null,
-  ) => Effect.Effect<unknown, unknown, unknown>,
+	TFlows extends (
+		flowId: string,
+		clientId: string | null,
+	) => Effect.Effect<unknown, unknown, unknown>,
 > = ReturnType<TFlows> extends Effect.Effect<infer Success, unknown, unknown>
-  ? Success
-  : never;
+	? Success
+	: never;
 
+/**
+ * @deprecated Use `ExtractFlowPluginRequirements` from `@uploadista/server/core/plugin-types` instead.
+ *
+ * Extracts plugin requirements from a flow function, excluding UploadServer.
+ *
+ * @example Migration
+ * ```typescript
+ * // Old
+ * import { FlowRequirementsOf } from '@uploadista/server/plugins-typing';
+ * type Requirements = FlowRequirementsOf<typeof myFlowFunction>;
+ *
+ * // New
+ * import { ExtractFlowPluginRequirements } from '@uploadista/server/core/plugin-types';
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlowFunction>;
+ * ```
+ */
 export type FlowRequirementsOf<
-  TFlows extends (
-    flowId: string,
-    clientId: string | null,
-  ) => Effect.Effect<unknown, unknown, unknown>,
+	TFlows extends (
+		flowId: string,
+		clientId: string | null,
+	) => Effect.Effect<unknown, unknown, unknown>,
 > = FlowSuccess<TFlows> extends Flow<
-  z.ZodSchema<unknown>,
-  z.ZodSchema<unknown>,
-  infer R
+	z.ZodSchema<unknown>,
+	z.ZodSchema<unknown>,
+	infer R
 >
-  ? Exclude<R, UploadServer>
-  : never;
+	? Exclude<R, UploadServer>
+	: never;
 
+/**
+ * @deprecated Use `ExtractFlowPluginRequirements` from `@uploadista/server/core/plugin-types` instead.
+ *
+ * This is an alias for FlowRequirementsOf and provides the same functionality.
+ *
+ * @example Migration
+ * ```typescript
+ * // Old
+ * import { RequiredPluginsOf } from '@uploadista/server/plugins-typing';
+ * type Requirements = RequiredPluginsOf<typeof myFlowFunction>;
+ *
+ * // New
+ * import { ExtractFlowPluginRequirements } from '@uploadista/server/core/plugin-types';
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlowFunction>;
+ * ```
+ */
 export type RequiredPluginsOf<
-  TFlows extends (
-    flowId: string,
-    clientId: string | null,
-  ) => Effect.Effect<unknown, unknown, unknown>,
+	TFlows extends (
+		flowId: string,
+		clientId: string | null,
+	) => Effect.Effect<unknown, unknown, unknown>,
 > = Exclude<FlowRequirementsOf<TFlows>, UploadServer>;
 
+/**
+ * @deprecated Use `ValidatePlugins` from `@uploadista/server/core/plugin-types` instead.
+ *
+ * This type validates plugin requirements at compile time.
+ *
+ * @example Migration
+ * ```typescript
+ * // Old
+ * import { PluginAssertion } from '@uploadista/server/plugins-typing';
+ * type Validation = PluginAssertion<typeof myFlowFunction, typeof plugins>;
+ *
+ * // New
+ * import { ValidatePlugins, ExtractFlowPluginRequirements } from '@uploadista/server/core/plugin-types';
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlowFunction>;
+ * type Validation = ValidatePlugins<typeof plugins, Requirements>;
+ * ```
+ */
 export type PluginAssertion<
-  TFlows extends (
-    flowId: string,
-    clientId: string | null,
-  ) => Effect.Effect<unknown, unknown, unknown>,
-  // biome-ignore lint/suspicious/noExplicitAny: Permissive constraint allows plugin tuples where each plugin provides subset of requirements
-  TPlugins extends readonly Layer.Layer<any, never, never>[],
-> = Exclude<
-  RequiredPluginsOf<TFlows>,
-  LayerSuccessUnion<TPlugins>
-> extends never
-  ? unknown
-  : {
-      __missingPlugins: Exclude<
-        RequiredPluginsOf<TFlows>,
-        LayerSuccessUnion<TPlugins>
-      >;
-    };
+	TFlows extends (
+		flowId: string,
+		clientId: string | null,
+	) => Effect.Effect<unknown, unknown, unknown>,
+	// biome-ignore lint/suspicious/noExplicitAny: Permissive constraint allows plugin tuples where each plugin provides subset of requirements
+	TPlugins extends readonly Layer.Layer<any, never, never>[],
+> = Exclude<RequiredPluginsOf<TFlows>, LayerSuccessUnion<TPlugins>> extends never
+	? unknown
+	: {
+			__missingPlugins: Exclude<
+				RequiredPluginsOf<TFlows>,
+				LayerSuccessUnion<TPlugins>
+			>;
+		};