@uploadista/server 0.0.10 → 0.0.12

package/src/core/__tests__/plugin-validation.test.ts

@@ -0,0 +1,472 @@
+/**
+ * Integration tests for plugin validation utilities.
+ *
+ * These tests verify runtime plugin validation behavior.
+ */
+
+import { Layer } from "effect";
+import { describe, expect, it } from "vitest";
+import {
+	extractServiceIdentifiers,
+	formatPluginValidationError,
+	validatePluginRequirements,
+	validatePluginsOrThrow,
+} from "../plugin-validation";
+
+// ============================================================================
+// Test Fixtures
+// ============================================================================
+
+class TestImagePlugin {
+	readonly _tag = "ImagePlugin";
+	resize(data: Buffer, width: number): Buffer {
+		return data;
+	}
+}
+
+class TestZipPlugin {
+	readonly _tag = "ZipPlugin";
+	compress(files: Buffer[]): Buffer {
+		return Buffer.from([]);
+	}
+}
+
+class TestVideoPlugin {
+	readonly _tag = "VideoPlugin";
+	transcode(data: Buffer): Buffer {
+		return data;
+	}
+}
+
+const imagePluginLayer = Layer.succeed(TestImagePlugin, new TestImagePlugin());
+const zipPluginLayer = Layer.succeed(TestZipPlugin, new TestZipPlugin());
+const videoPluginLayer = Layer.succeed(TestVideoPlugin, new TestVideoPlugin());
+
+// ============================================================================
+// extractServiceIdentifiers Tests
+// ============================================================================
+
+describe("extractServiceIdentifiers", () => {
+	it("should extract identifiers from plugin array", () => {
+		const plugins = [imagePluginLayer, zipPluginLayer];
+		const identifiers = extractServiceIdentifiers(plugins);
+
+		// Should return array of strings (exact values depend on Effect internals)
+		expect(Array.isArray(identifiers)).toBe(true);
+		expect(identifiers.length).toBeGreaterThanOrEqual(0);
+	});
+
+	it("should handle empty plugin array", () => {
+		const plugins: never[] = [];
+		const identifiers = extractServiceIdentifiers(plugins);
+
+		expect(Array.isArray(identifiers)).toBe(true);
+		expect(identifiers).toHaveLength(0);
+	});
+
+	it("should handle single plugin", () => {
+		const plugins = [imagePluginLayer];
+		const identifiers = extractServiceIdentifiers(plugins);
+
+		expect(Array.isArray(identifiers)).toBe(true);
+	});
+});
+
+// ============================================================================
+// validatePluginRequirements Tests
+// ============================================================================
+
+describe("validatePluginRequirements", () => {
+	it("should return success when no services are expected", () => {
+		const result = validatePluginRequirements({
+			plugins: [imagePluginLayer],
+			expectedServices: [],
+		});
+
+		expect(result.success).toBe(true);
+	});
+
+	it("should return success when expected services is undefined", () => {
+		const result = validatePluginRequirements({
+			plugins: [imagePluginLayer],
+		});
+
+		expect(result.success).toBe(true);
+	});
+
+	it("should detect missing services", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin", "ZipPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.missing).toEqual(["ImagePlugin", "ZipPlugin"]);
+			expect(result.required).toEqual(["ImagePlugin", "ZipPlugin"]);
+			expect(result.provided).toEqual([]);
+		}
+	});
+
+	it("should detect partially missing services", () => {
+		const result = validatePluginRequirements({
+			plugins: [imagePluginLayer],
+			expectedServices: ["ImagePlugin", "ZipPlugin"],
+		});
+
+		// Since we can't reliably extract service identifiers from Effect layers,
+		// this test verifies the validation logic structure
+		expect(result).toHaveProperty("success");
+	});
+
+	it("should generate suggestions for known plugins", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.suggestions.length).toBeGreaterThan(0);
+			const suggestion = result.suggestions[0];
+			expect(suggestion).toHaveProperty("name");
+			expect(suggestion).toHaveProperty("packageName");
+			expect(suggestion).toHaveProperty("importStatement");
+			expect(suggestion.name).toBe("ImagePlugin");
+		}
+	});
+
+	it("should handle unknown plugin services", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["UnknownPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.missing).toContain("UnknownPlugin");
+			// Should not generate suggestion for unknown plugins
+			const unknownSuggestion = result.suggestions.find(
+				(s) => s.name === "UnknownPlugin",
+			);
+			expect(unknownSuggestion).toBeUndefined();
+		}
+	});
+
+	it("should handle multiple known plugins", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin", "ZipPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.suggestions.length).toBe(2);
+			expect(result.suggestions.map((s) => s.name)).toEqual([
+				"ImagePlugin",
+				"ZipPlugin",
+			]);
+		}
+	});
+});
+
+// ============================================================================
+// formatPluginValidationError Tests
+// ============================================================================
+
+describe("formatPluginValidationError", () => {
+	it("should format error message with suggestions", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin", "ZipPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const message = formatPluginValidationError(result);
+
+			expect(message).toContain("Server initialization failed");
+			expect(message).toContain("Missing required plugins");
+			expect(message).toContain("ImagePlugin");
+			expect(message).toContain("ZipPlugin");
+			expect(message).toContain("Required:");
+			expect(message).toContain("Missing:");
+		}
+	});
+
+	it("should include import statements in error message", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const message = formatPluginValidationError(result);
+
+			expect(message).toContain("import");
+			expect(message).toContain("@uploadista/flow-images-sharp");
+			expect(message).toContain("sharpImagePlugin");
+		}
+	});
+
+	it("should include example server configuration", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const message = formatPluginValidationError(result);
+
+			expect(message).toContain("createUploadistaServer");
+			expect(message).toContain("plugins:");
+		}
+	});
+
+	it("should handle missing suggestions gracefully", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["UnknownPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const message = formatPluginValidationError(result);
+
+			expect(message).toContain("Server initialization failed");
+			expect(message).toContain("UnknownPlugin");
+			expect(message).toContain(
+				"Could not determine package names for missing plugins",
+			);
+		}
+	});
+
+	it("should show provided services when some are present", () => {
+		const result = validatePluginRequirements({
+			plugins: [imagePluginLayer],
+			expectedServices: ["ImagePlugin", "ZipPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			const message = formatPluginValidationError(result);
+
+			expect(message).toContain("Provided:");
+			// The exact provided services depend on Effect's internal representation
+		}
+	});
+});
+
+// ============================================================================
+// validatePluginsOrThrow Tests
+// ============================================================================
+
+describe("validatePluginsOrThrow", () => {
+	it("should not throw when validation passes", () => {
+		expect(() => {
+			validatePluginsOrThrow({
+				plugins: [imagePluginLayer],
+				expectedServices: [],
+			});
+		}).not.toThrow();
+	});
+
+	it("should throw when validation fails", () => {
+		expect(() => {
+			validatePluginsOrThrow({
+				plugins: [],
+				expectedServices: ["ImagePlugin"],
+			});
+		}).toThrow("Server initialization failed");
+	});
+
+	it("should throw error with detailed message", () => {
+		expect(() => {
+			validatePluginsOrThrow({
+				plugins: [],
+				expectedServices: ["ImagePlugin", "ZipPlugin"],
+			});
+		}).toThrow(/Missing required plugins/);
+	});
+
+	it("should include plugin names in error", () => {
+		try {
+			validatePluginsOrThrow({
+				plugins: [],
+				expectedServices: ["ImagePlugin", "ZipPlugin"],
+			});
+			expect.fail("Should have thrown");
+		} catch (error) {
+			expect(error).toBeInstanceOf(Error);
+			if (error instanceof Error) {
+				expect(error.message).toContain("ImagePlugin");
+				expect(error.message).toContain("ZipPlugin");
+			}
+		}
+	});
+});
+
+// ============================================================================
+// Integration Tests
+// ============================================================================
+
+describe("Plugin Validation Integration", () => {
+	it("should handle realistic server configuration scenario", () => {
+		// Scenario: Server configured with image plugin, but flow needs both image and zip
+		const result = validatePluginRequirements({
+			plugins: [imagePluginLayer],
+			expectedServices: ["ImagePlugin", "ZipPlugin"],
+		});
+
+		if (!result.success) {
+			const message = formatPluginValidationError(result);
+
+			// Should provide actionable error message
+			expect(message).toContain("Missing required plugins");
+			expect(message).toContain("@uploadista/flow-utility-zipjs");
+			expect(message).toContain("zipPlugin");
+		}
+	});
+
+	it("should handle empty configuration", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: [],
+		});
+
+		expect(result.success).toBe(true);
+	});
+
+	it("should handle over-provisioned plugins", () => {
+		// More plugins than required should still pass
+		const result = validatePluginRequirements({
+			plugins: [imagePluginLayer, zipPluginLayer, videoPluginLayer],
+			expectedServices: ["ImagePlugin"],
+		});
+
+		// This would pass if we could extract identifiers reliably
+		// For now, just verify structure
+		expect(result).toHaveProperty("success");
+	});
+
+	it("should provide helpful error for complete plugin set missing", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin", "ZipPlugin", "VideoPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.missing).toHaveLength(3);
+			const message = formatPluginValidationError(result);
+
+			// Should list all missing plugins
+			expect(message).toContain("ImagePlugin");
+			expect(message).toContain("ZipPlugin");
+			expect(message).toContain("VideoPlugin");
+		}
+	});
+});
+
+// ============================================================================
+// Known Plugins Mapping Tests
+// ============================================================================
+
+describe("Known Plugins Mapping", () => {
+	it("should generate suggestions for missing plugins", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			// Verify suggestions array exists
+			expect(result.suggestions).toBeDefined();
+			expect(Array.isArray(result.suggestions)).toBe(true);
+
+			// If there are suggestions, check the structure
+			if (result.suggestions.length > 0) {
+				const suggestion = result.suggestions[0];
+				expect(suggestion).toHaveProperty("name");
+				expect(suggestion).toHaveProperty("packageName");
+				expect(suggestion).toHaveProperty("importStatement");
+			}
+		}
+	});
+
+	it("should provide correct package for ImagePlugin", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImagePlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success && result.suggestions.length > 0) {
+			const suggestion = result.suggestions[0];
+			expect(suggestion.name).toBe("ImagePlugin");
+			expect(suggestion.packageName).toBe("@uploadista/flow-images-sharp");
+			expect(suggestion.importStatement).toContain("sharpImagePlugin");
+			expect(suggestion.importStatement).toContain("@uploadista/flow-images-sharp");
+		}
+	});
+
+	it("should provide correct package for ZipPlugin", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ZipPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.suggestions.length).toBeGreaterThan(0);
+
+			const suggestion = result.suggestions[0];
+			expect(suggestion).toBeDefined();
+			expect(suggestion.name).toBe("ZipPlugin");
+			expect(suggestion.packageName).toBe("@uploadista/flow-utility-zipjs");
+			expect(suggestion.importStatement).toContain("zipPlugin");
+			expect(suggestion.importStatement).toContain("@uploadista/flow-utility-zipjs");
+		}
+	});
+
+	it("should provide correct package for ImageAiPlugin", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["ImageAiPlugin"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.suggestions.length).toBeGreaterThan(0);
+
+			const suggestion = result.suggestions[0];
+			expect(suggestion).toBeDefined();
+			expect(suggestion.name).toBe("ImageAiPlugin");
+			expect(suggestion.packageName).toBe("@uploadista/flow-images-replicate");
+			expect(suggestion.importStatement).toContain("replicateImagePlugin");
+			expect(suggestion.importStatement).toContain("@uploadista/flow-images-replicate");
+		}
+	});
+
+	it("should provide correct package for CredentialProvider", () => {
+		const result = validatePluginRequirements({
+			plugins: [],
+			expectedServices: ["CredentialProvider"],
+		});
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.suggestions.length).toBeGreaterThan(0);
+
+			const suggestion = result.suggestions[0];
+			expect(suggestion).toBeDefined();
+			expect(suggestion.name).toBe("CredentialProvider");
+			expect(suggestion.packageName).toBe("@uploadista/core");
+			expect(suggestion.importStatement).toContain("credentialProviderLayer");
+			expect(suggestion.importStatement).toContain("@uploadista/core");
+		}
+	});
+});

package/src/core/create-type-safe-server.ts

@@ -0,0 +1,204 @@
+import type {
+  PluginServices,
+  PluginTuple,
+  TypeSafeFlowFunction,
+  ValidatePlugins,
+} from "./plugin-types";
+import { createUploadistaServer } from "./server";
+import type { UploadistaServer, UploadistaServerConfig } from "./types";
+
+/**
+ * Type-safe configuration for Uploadista server with compile-time plugin validation.
+ *
+ * This configuration extends the base UploadistaServerConfig with stricter typing
+ * that validates plugins match flow requirements at compile time.
+ *
+ * @template TContext - Framework-specific request context type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocket - Framework-specific WebSocket handler type
+ * @template TPlugins - Tuple of plugin layers provided to the server
+ * @template TFlowRequirements - Union of plugin services required by flows
+ */
+export type TypeSafeServerConfig<
+  TContext,
+  TResponse,
+  TWebSocket,
+  TPlugins extends PluginTuple,
+  TFlowRequirements = PluginServices<TPlugins>,
+> = Omit<
+  UploadistaServerConfig<TContext, TResponse, TWebSocket>,
+  "flows" | "plugins"
+> & {
+  /**
+   * Tuple of plugin layers that provide services to flows.
+   * The plugins must satisfy all requirements declared by the flows.
+   */
+  plugins: TPlugins;
+
+  /**
+   * Type-safe flow function with explicit requirements.
+   * TypeScript validates that all required plugins are provided.
+   */
+  flows: TypeSafeFlowFunction<TFlowRequirements>;
+
+  /**
+   * Compile-time validation that plugins satisfy flow requirements.
+   * If this field has type errors, required plugins are missing.
+   */
+  __validate?: ValidatePlugins<TPlugins, TFlowRequirements>;
+};
+
+/**
+ * @deprecated Use `createUploadistaServer` with optional type utilities instead.
+ *
+ * This function is deprecated in favor of the unified `createUploadistaServer` API.
+ * The new approach separates validation concerns from server creation, making the
+ * API simpler while still providing compile-time validation when desired.
+ *
+ * ## Migration Guide
+ *
+ * ### Old Approach (Deprecated)
+ * ```typescript
+ * import { createTypeSafeServer } from "@uploadista/server";
+ *
+ * const server = await createTypeSafeServer({
+ *   plugins: [sharpImagePlugin] as const,
+ *   flows: myFlowFunction,
+ *   // ...
+ * });
+ * ```
+ *
+ * ### New Approach (Recommended)
+ *
+ * **Option 1: Runtime validation only (simplest)**
+ * ```typescript
+ * import { createUploadistaServer } from "@uploadista/server";
+ *
+ * const server = await createUploadistaServer({
+ *   plugins: [sharpImagePlugin, zipPlugin],
+ *   flows: myFlowFunction,
+ *   // ... Effect validates at runtime
+ * });
+ * ```
+ *
+ * **Option 2: With compile-time validation (optional)**
+ * ```typescript
+ * import {
+ *   createUploadistaServer,
+ *   ValidatePlugins,
+ *   ExtractFlowPluginRequirements
+ * } from "@uploadista/server";
+ *
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlowFunction>;
+ * const plugins = [sharpImagePlugin, zipPlugin] as const;
+ * type Validation = ValidatePlugins<typeof plugins, Requirements>;
+ * // IDE shows error if plugins don't match requirements
+ *
+ * const server = await createUploadistaServer({
+ *   plugins,
+ *   flows: myFlowFunction,
+ *   // ...
+ * });
+ * ```
+ *
+ * ## Why This Changed
+ *
+ * 1. **Simpler API**: One function instead of two reduces confusion
+ * 2. **Separation of Concerns**: Validation is now optional and separate
+ * 3. **Better Flexibility**: Choose validation approach per use case
+ * 4. **Clearer Intent**: Explicit validation via type utilities
+ * 5. **Same Safety**: Effect-TS still validates at runtime
+ *
+ * The new approach trusts Effect-TS's design for dynamic dependency injection
+ * while providing optional compile-time validation through type utilities.
+ *
+ * @see createUploadistaServer - The unified server creation API
+ * @see ValidatePlugins - Compile-time validation type utility
+ * @see ExtractFlowPluginRequirements - Extract requirements from flows
+ * @see API_DECISION_GUIDE.md - Complete migration and usage guide
+ *
+ * @template TContext - Framework-specific request context type
+ * @template TResponse - Framework-specific response type
+ * @template TWebSocket - Framework-specific WebSocket handler type
+ * @template TPlugins - Tuple of plugin layers
+ * @template TFlowRequirements - Union of services required by flows
+ *
+ * @param config - Type-safe server configuration
+ * @returns Promise resolving to UploadistaServer instance
+ */
+export async function createTypeSafeServer<
+  TContext,
+  TResponse,
+  TWebSocket = unknown,
+  TPlugins extends PluginTuple = PluginTuple,
+  TFlowRequirements = PluginServices<TPlugins>,
+>(
+  config: TypeSafeServerConfig<
+    TContext,
+    TResponse,
+    TWebSocket,
+    TPlugins,
+    TFlowRequirements
+  > &
+    // Enforce validation at function call site
+    (ValidatePlugins<TPlugins, TFlowRequirements> extends true
+      ? object
+      : ValidatePlugins<TPlugins, TFlowRequirements>),
+): Promise<UploadistaServer<TContext, TResponse, TWebSocket>> {
+  return createUploadistaServer(config);
+}
+
+/**
+ * Helper function to define flow functions with explicit type requirements.
+ * Provides better type inference and autocomplete for plugin services.
+ *
+ * @template TRequirements - Union of plugin services this flow needs
+ *
+ * @param fn - The flow function implementation
+ * @returns The same function with explicit type annotation
+ *
+ * @example
+ * ```typescript
+ * import { ImagePlugin } from "@uploadista/core/flow";
+ * import { defineFlow } from "@uploadista/server";
+ *
+ * // Explicitly declare that this flow requires ImagePlugin
+ * const imageProcessingFlow = defineFlow<ImagePlugin>((flowId, clientId) =>
+ *   Effect.gen(function* () {
+ *     const imageService = yield* ImagePlugin;  // Autocomplete works!
+ *     const optimized = yield* imageService.optimize(data, { quality: 80 });
+ *     return createFlow({ ... });
+ *   })
+ * );
+ * ```
+ */
+export function defineFlow<TRequirements = never>(
+  fn: TypeSafeFlowFunction<TRequirements>,
+): TypeSafeFlowFunction<TRequirements> {
+  return fn;
+}
+
+/**
+ * Helper to create a flow that requires no plugins.
+ * Useful for simple flows that only use built-in functionality.
+ *
+ * @example
+ * ```typescript
+ * import { defineSimpleFlow } from "@uploadista/server";
+ *
+ * const simpleFlow = defineSimpleFlow((flowId, clientId) =>
+ *   Effect.succeed(createFlow({
+ *     id: "simple",
+ *     nodes: [],
+ *     edges: [],
+ *     inputSchema: myInputSchema,
+ *     outputSchema: myOutputSchema
+ *   }))
+ * );
+ * ```
+ */
+export function defineSimpleFlow(
+  fn: TypeSafeFlowFunction<never>,
+): TypeSafeFlowFunction<never> {
+  return fn;
+}

package/src/core/index.ts

@@ -5,6 +5,9 @@
  * all framework adapters (Hono, Express, Fastify, etc.).
  */
 
+export * from "./create-type-safe-server";
+export * from "./plugin-types";
+export * from "./plugin-validation";
 export * from "./routes";
 export * from "./server";
 export * from "./types";