@uploadista/core 0.0.13-beta.5 → 0.0.13

package/{src → tests}/streams/stream-limiter.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
-import { UploadistaError } from "../errors/uploadista-error";
-import { streamLimiter } from "./stream-limiter";
+import { UploadistaError } from "../../src/errors";
+import { streamLimiter } from "../../src/streams/stream-limiter";
 
 // Helper function to convert stream to array
 async function streamToArray(

package/tests/types/typed-event-emitter.test.ts

@@ -0,0 +1,282 @@
+import type { WebSocketConnection } from "@uploadista/core/types";
+import {
+  type BaseEventEmitter,
+  TypedEventEmitter,
+  eventToMessageSerializer,
+} from "@uploadista/core/types";
+import { Effect } from "effect";
+import { describe, expect, it, vi } from "vitest";
+
+interface TestEvent {
+  id: string;
+  type: string;
+  data: string;
+}
+
+class MockWebSocketConnection implements WebSocketConnection {
+  id = "test-conn";
+  readyState = 1;
+  sentMessages: string[] = [];
+
+  send(data: string): void {
+    this.sentMessages.push(data);
+  }
+
+  close(): void {
+    this.readyState = 3;
+  }
+}
+
+describe("TypedEventEmitter", () => {
+  describe("Event Serialization", () => {
+    it("should serialize event using eventToMessage function", async () => {
+      const emittedMessages: Array<{ key: string; message: string }> = [];
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: (key: string, message: string) =>
+          Effect.sync(() => {
+            emittedMessages.push({ key, message });
+          }),
+        subscribe: () => Effect.void,
+        unsubscribe: () => Effect.void,
+      };
+
+      const serializer = (event: TestEvent) =>
+        JSON.stringify({ custom: "format", event });
+
+      const typedEmitter = new TypedEventEmitter(mockBaseEmitter, serializer);
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const event: TestEvent = { id: "1", type: "test", data: "hello" };
+          yield* typedEmitter.emit("key1", event);
+
+          expect(emittedMessages).toHaveLength(1);
+          expect(emittedMessages[0].key).toBe("key1");
+
+          const parsed = JSON.parse(emittedMessages[0].message);
+          expect(parsed.custom).toBe("format");
+          expect(parsed.event).toEqual(event);
+        }),
+      );
+    });
+
+    it("should delegate emit to BaseEventEmitter with serialized message", async () => {
+      const emitSpy = vi.fn().mockReturnValue(Effect.void);
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: emitSpy,
+        subscribe: () => Effect.void,
+        unsubscribe: () => Effect.void,
+      };
+
+      const typedEmitter = new TypedEventEmitter(
+        mockBaseEmitter,
+        (event: TestEvent) => JSON.stringify(event),
+      );
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const event: TestEvent = { id: "2", type: "action", data: "world" };
+          yield* typedEmitter.emit("key2", event);
+
+          expect(emitSpy).toHaveBeenCalledWith("key2", JSON.stringify(event));
+          expect(emitSpy).toHaveBeenCalledTimes(1);
+        }),
+      );
+    });
+
+    it("should delegate subscribe to BaseEventEmitter", async () => {
+      const subscribeSpy = vi.fn().mockReturnValue(Effect.void);
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: () => Effect.void,
+        subscribe: subscribeSpy,
+        unsubscribe: () => Effect.void,
+      };
+
+      const typedEmitter = new TypedEventEmitter(
+        mockBaseEmitter,
+        (event: TestEvent) => JSON.stringify(event),
+      );
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const connection = new MockWebSocketConnection();
+          yield* typedEmitter.subscribe("key3", connection);
+
+          expect(subscribeSpy).toHaveBeenCalledWith("key3", connection);
+          expect(subscribeSpy).toHaveBeenCalledTimes(1);
+        }),
+      );
+    });
+
+    it("should delegate unsubscribe to BaseEventEmitter", async () => {
+      const unsubscribeSpy = vi.fn().mockReturnValue(Effect.void);
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: () => Effect.void,
+        subscribe: () => Effect.void,
+        unsubscribe: unsubscribeSpy,
+      };
+
+      const typedEmitter = new TypedEventEmitter(
+        mockBaseEmitter,
+        (event: TestEvent) => JSON.stringify(event),
+      );
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          yield* typedEmitter.unsubscribe("key4");
+
+          expect(unsubscribeSpy).toHaveBeenCalledWith("key4");
+          expect(unsubscribeSpy).toHaveBeenCalledTimes(1);
+        }),
+      );
+    });
+  });
+
+  describe("Standard Serializers", () => {
+    it("should produce correct format for upload_event", async () => {
+      const emittedMessages: string[] = [];
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: (key: string, message: string) =>
+          Effect.sync(() => {
+            emittedMessages.push(message);
+          }),
+        subscribe: () => Effect.void,
+        unsubscribe: () => Effect.void,
+      };
+
+      const serializer = eventToMessageSerializer("upload_event");
+      const typedEmitter = new TypedEventEmitter(
+        mockBaseEmitter,
+        serializer.eventToMessage,
+      );
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const event: TestEvent = { id: "upload-1", type: "progress", data: "50%" };
+          yield* typedEmitter.emit("upload-key", event);
+
+          expect(emittedMessages).toHaveLength(1);
+
+          const parsed = JSON.parse(emittedMessages[0]);
+          expect(parsed.type).toBe("upload_event");
+          expect(parsed.payload).toEqual(event);
+          expect(parsed.timestamp).toBeDefined();
+          expect(typeof parsed.timestamp).toBe("string");
+        }),
+      );
+    });
+
+    it("should produce correct format for flow_event", async () => {
+      const emittedMessages: string[] = [];
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: (key: string, message: string) =>
+          Effect.sync(() => {
+            emittedMessages.push(message);
+          }),
+        subscribe: () => Effect.void,
+        unsubscribe: () => Effect.void,
+      };
+
+      const serializer = eventToMessageSerializer("flow_event");
+      const typedEmitter = new TypedEventEmitter(
+        mockBaseEmitter,
+        serializer.eventToMessage,
+      );
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const event: TestEvent = { id: "flow-1", type: "complete", data: "done" };
+          yield* typedEmitter.emit("flow-key", event);
+
+          expect(emittedMessages).toHaveLength(1);
+
+          const parsed = JSON.parse(emittedMessages[0]);
+          expect(parsed.type).toBe("flow_event");
+          expect(parsed.payload).toEqual(event);
+          expect(parsed.timestamp).toBeDefined();
+        }),
+      );
+    });
+
+    it("should include valid ISO 8601 timestamp", async () => {
+      const emittedMessages: string[] = [];
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: (key: string, message: string) =>
+          Effect.sync(() => {
+            emittedMessages.push(message);
+          }),
+        subscribe: () => Effect.void,
+        unsubscribe: () => Effect.void,
+      };
+
+      const serializer = eventToMessageSerializer("upload_event");
+      const typedEmitter = new TypedEventEmitter(
+        mockBaseEmitter,
+        serializer.eventToMessage,
+      );
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const event: TestEvent = { id: "test", type: "test", data: "test" };
+          yield* typedEmitter.emit("test-key", event);
+
+          const parsed = JSON.parse(emittedMessages[0]);
+          const timestamp = new Date(parsed.timestamp);
+
+          expect(timestamp.toISOString()).toBe(parsed.timestamp);
+          expect(isNaN(timestamp.getTime())).toBe(false);
+        }),
+      );
+    });
+  });
+
+  describe("Custom Serializers", () => {
+    it("should use custom eventToMessage function", async () => {
+      const emittedMessages: string[] = [];
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: (key: string, message: string) =>
+          Effect.sync(() => {
+            emittedMessages.push(message);
+          }),
+        subscribe: () => Effect.void,
+        unsubscribe: () => Effect.void,
+      };
+
+      const customSerializer = (event: TestEvent) => `CUSTOM:${event.id}:${event.type}:${event.data}`;
+
+      const typedEmitter = new TypedEventEmitter(mockBaseEmitter, customSerializer);
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const event: TestEvent = { id: "123", type: "action", data: "payload" };
+          yield* typedEmitter.emit("custom-key", event);
+
+          expect(emittedMessages).toHaveLength(1);
+          expect(emittedMessages[0]).toBe("CUSTOM:123:action:payload");
+        }),
+      );
+    });
+
+    it("should pass custom serializer output to BaseEventEmitter", async () => {
+      const emitSpy = vi.fn().mockReturnValue(Effect.void);
+      const mockBaseEmitter: BaseEventEmitter = {
+        emit: emitSpy,
+        subscribe: () => Effect.void,
+        unsubscribe: () => Effect.void,
+      };
+
+      const customSerializer = (event: TestEvent) => `EVENT-${event.id}`;
+
+      const typedEmitter = new TypedEventEmitter(mockBaseEmitter, customSerializer);
+
+      await Effect.runPromise(
+        Effect.gen(function* () {
+          const event: TestEvent = { id: "456", type: "test", data: "data" };
+          yield* typedEmitter.emit("key", event);
+
+          expect(emitSpy).toHaveBeenCalledWith("key", "EVENT-456");
+        }),
+      );
+    });
+  });
+});

package/{src → tests}/utils/debounce.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { debounce } from "./debounce";
+import { debounce } from "../../src/utils/debounce";
 
 describe("debounce", () => {
   beforeEach(() => {

package/{src → tests}/utils/once.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { once } from "./once";
+import { once } from "../../src/utils/once";
 
 describe("once", () => {
   it("should call the function only once", () => {

package/tests/utils/test-layers.ts

@@ -0,0 +1,183 @@
+/**
+ * Test Utilities for Effect-based Testing
+ *
+ * This file provides reusable test utilities and Layer mocking patterns
+ * for testing Effect-based code in the uploadista-sdk.
+ *
+ * ## Effect Testing Patterns
+ *
+ * ### 1. Using it.effect()
+ * For testing Effect operations with automatic TestContext provision:
+ *
+ * ```typescript
+ * import { it } from "@effect/vitest";
+ * import { Effect } from "effect";
+ *
+ * it.effect("should process data", () =>
+ *   Effect.gen(function* () {
+ *     const result = yield* processData();
+ *     expect(result).toBe(expected);
+ *   })
+ * );
+ * ```
+ *
+ * ### 2. Using TestClock for Time Control
+ * For testing timeouts, delays, and scheduled operations:
+ *
+ * ```typescript
+ * import { it } from "@effect/vitest";
+ * import { Effect, TestClock } from "effect";
+ *
+ * it.effect("should handle timeout", () =>
+ *   Effect.gen(function* () {
+ *     const fiber = yield* Effect.timeout(operation, "5 seconds").pipe(
+ *       Effect.fork
+ *     );
+ *
+ *     // Advance time without real delay
+ *     yield* TestClock.adjust("6 seconds");
+ *
+ *     const result = yield* Fiber.join(fiber);
+ *     expect(result).toBe(None);
+ *   })
+ * );
+ * ```
+ *
+ * ### 3. Using Layer.mock() for Service Mocking
+ * For mocking Effect services with partial implementations:
+ *
+ * ```typescript
+ * import { Layer, Context } from "effect";
+ *
+ * // Define Test layer (mock)
+ * const DataStoreTest = Layer.succeed(
+ *   DataStore,
+ *   DataStore.of({
+ *     upload: () => Effect.succeed({ key: "test-key" }),
+ *     download: () => Effect.fail(new Error("Not implemented")),
+ *   })
+ * );
+ *
+ * // Use in tests
+ * it.effect("should upload file", () =>
+ *   Effect.gen(function* () {
+ *     const store = yield* DataStore;
+ *     const result = yield* store.upload(file);
+ *     expect(result.key).toBe("test-key");
+ *   }).pipe(Effect.provide(DataStoreTest))
+ * );
+ * ```
+ *
+ * ### 4. Using it.scoped() for Resource Management
+ * For tests requiring Scope lifecycle management:
+ *
+ * ```typescript
+ * import { it } from "@effect/vitest";
+ * import { Effect } from "effect";
+ *
+ * it.scoped("should manage resources", () =>
+ *   Effect.gen(function* () {
+ *     const resource = yield* acquireResource();
+ *     // Resource will be automatically released after test
+ *     yield* useResource(resource);
+ *   })
+ * );
+ * ```
+ *
+ * ### 5. Test vs Live Layer Naming Convention
+ * Follow Effect's convention for layer naming:
+ * - `ServiceNameLive` - Production layer with real implementation
+ * - `ServiceNameTest` - Test layer with mocked implementation
+ *
+ * Example:
+ * ```typescript
+ * export const S3StoreLive = Layer.effect(...)  // Real S3 client
+ * export const S3StoreTest = Layer.succeed(...)  // Mocked S3 client
+ * ```
+ */
+
+import { Context, Effect, Layer } from "effect";
+
+/**
+ * Example: Mock Data Store Layer
+ *
+ * This demonstrates creating a mock layer for a data store service.
+ * Replace with actual service interfaces as needed.
+ */
+
+// Example service interface (replace with actual interfaces from core)
+export interface MockDataStore {
+  readonly upload: (data: Uint8Array) => Effect.Effect<{ key: string }, Error>;
+  readonly download: (key: string) => Effect.Effect<Uint8Array, Error>;
+  readonly delete: (key: string) => Effect.Effect<void, Error>;
+}
+
+export const MockDataStore = Context.GenericTag<MockDataStore>(
+  "@uploadista/MockDataStore",
+);
+
+/**
+ * Test layer for MockDataStore with in-memory storage
+ */
+export const MockDataStoreTest = Layer.succeed(
+  MockDataStore,
+  MockDataStore.of({
+    upload: (data: Uint8Array) =>
+      Effect.succeed({ key: `mock-key-${data.length}` }),
+    download: (_key: string) =>
+      Effect.succeed(new Uint8Array([1, 2, 3])) as Effect.Effect<
+        Uint8Array,
+        Error
+      >,
+    delete: (_key: string) => Effect.void,
+  }),
+);
+
+/**
+ * Example: Mock KV Store Layer
+ */
+export interface MockKVStore {
+  readonly get: (key: string) => Effect.Effect<string | null, Error>;
+  readonly set: (
+    key: string,
+    value: string,
+    ttl?: number,
+  ) => Effect.Effect<void, Error>;
+  readonly delete: (key: string) => Effect.Effect<void, Error>;
+}
+
+export const MockKVStore = Context.GenericTag<MockKVStore>(
+  "@uploadista/MockKVStore",
+);
+
+/**
+ * Test layer for MockKVStore with in-memory Map
+ */
+export const MockKVStoreTest = (() => {
+  const store = new Map<string, string>();
+
+  return Layer.succeed(
+    MockKVStore,
+    MockKVStore.of({
+      get: (key: string) => Effect.succeed(store.get(key) ?? null),
+      set: (key: string, value: string) =>
+        Effect.sync(() => {
+          store.set(key, value);
+        }),
+      delete: (key: string) =>
+        Effect.sync(() => {
+          store.delete(key);
+        }),
+    }),
+  );
+})();
+
+/**
+ * Utility to create a Layer that fails (useful for testing error scenarios)
+ */
+export const createFailingLayer = <T>(
+  _tag: Context.Tag<T, T>,
+  error: Error,
+): Layer.Layer<T, Error, never> => {
+  return Layer.fail(error);
+};

package/{src → tests}/utils/throttle.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { throttle } from "./throttle";
+import { throttle } from "../../src/utils/throttle";
 
 describe("throttle", () => {
   beforeEach(() => {

package/tsdown.config.ts

@@ -9,6 +9,7 @@ export default defineConfig({
     "upload/index": "src/upload/index.ts",
     "streams/index": "src/streams/index.ts",
     "utils/index": "src/utils/index.ts",
+    "testing/index": "src/testing/index.ts",
   },
   minify: true,
   format: ["esm", "cjs"],

package/type-tests/flow.test-d.ts

@@ -0,0 +1,93 @@
+import { Effect } from "effect";
+import { expectType } from "tsd";
+import { z } from "zod";
+import {
+  createFlow,
+  createFlowNode,
+  type FlowInputMap,
+  type FlowOutputMap,
+  NodeType,
+} from "../src/flow";
+import type { ResolveEffect } from "../src/flow/types/type-utils";
+
+// Test 1: Verify node type preservation
+const inputNode = createFlowNode({
+  id: "input-node",
+  name: "Input Node",
+  description: "Input Node",
+  type: NodeType.input,
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+  run: ({ data }) =>
+    Effect.succeed({ type: "complete", data: { result: data.value } }),
+});
+
+type TestInputNode = ResolveEffect<typeof inputNode>;
+
+// The node's type field should be the literal "input", not the union NodeType
+expectType<NodeType.input>(({} as TestInputNode).type);
+
+const outputNode = createFlowNode({
+  id: "output-node",
+  name: "Output Node",
+  description: "Output Node",
+  type: NodeType.output,
+  inputSchema: z.object({ result: z.string() }),
+  outputSchema: z.object({ value: z.string() }),
+  run: ({ data }) =>
+    Effect.succeed({ type: "complete", data: { value: data.result } }),
+});
+
+type TestOutputNode = ResolveEffect<typeof outputNode>;
+
+// The node's type field should be the literal "output", not the union NodeType
+expectType<NodeType.output>(({} as TestOutputNode).type);
+
+// Test 2: Verify FlowInputMap and FlowOutputMap
+const nodes = {
+  input: inputNode,
+  output: outputNode,
+};
+
+type NodesType = typeof nodes;
+
+// FlowInputMap should only include keys of input nodes
+type InputMapTest = FlowInputMap<NodesType>;
+expectType<{
+  input: { value: string };
+}>({} as InputMapTest);
+
+// FlowOutputMap should only include keys of output nodes
+type OutputMapTest = FlowOutputMap<NodesType>;
+expectType<{
+  output: { value: string };
+}>({} as OutputMapTest);
+
+// Test 3: Verify typed flow
+const flow = createFlow({
+  flowId: "test-flow",
+  name: "Test Flow",
+  nodes,
+  edges: [{ source: "input", target: "output" }],
+});
+
+// Test that run() returns the correct output type
+Effect.runPromise(
+  Effect.gen(function* () {
+    const typedFlow = yield* flow;
+    const result = yield* typedFlow.run({
+      inputs: { input: { value: "test" } },
+      storageId: "storage-1",
+      jobId: "job-1",
+    });
+
+    if (result.type === "completed") {
+      // result.result should be FlowOutputMap<NodesType>
+      // Which means it should have an "output" key with the output schema
+      expectType<{ output: { value: string } }>(result.result);
+
+      // We should be able to access output node result
+      expectType<{ value: string }>(result.result.output);
+    }
+  }),
+);