@voidhash/mimic-effect 1.0.0-beta.1 → 1.0.0-beta.2

package/src/testing/index.ts

@@ -0,0 +1,83 @@
+/**
+ * @voidhash/mimic-effect/testing
+ *
+ * Test utilities for verifying ColdStorage and HotStorage adapter implementations.
+ *
+ * These utilities help ensure that custom storage adapters correctly implement
+ * the required interfaces and can reliably persist/retrieve data without loss.
+ *
+ * @example
+ * ```typescript
+ * import { ColdStorageTestSuite, HotStorageTestSuite } from "@voidhash/mimic-effect/testing";
+ * import { describe, it } from "vitest";
+ * import { Effect } from "effect";
+ *
+ * // Test your ColdStorage adapter
+ * describe("MyColdStorageAdapter", () => {
+ *   const layer = MyColdStorageAdapter.make();
+ *
+ *   for (const test of ColdStorageTestSuite.makeTests()) {
+ *     it(test.name, () =>
+ *       Effect.runPromise(test.run.pipe(Effect.provide(layer)))
+ *     );
+ *   }
+ * });
+ *
+ * // Test your HotStorage adapter
+ * describe("MyHotStorageAdapter", () => {
+ *   const layer = MyHotStorageAdapter.make();
+ *
+ *   for (const test of HotStorageTestSuite.makeTests()) {
+ *     it(test.name, () =>
+ *       Effect.runPromise(test.run.pipe(Effect.provide(layer)))
+ *     );
+ *   }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  StorageTestCase,
+  TestResults,
+  FailedTest,
+} from "./types";
+
+export { TestError } from "./types";
+
+// =============================================================================
+// Test Suites
+// =============================================================================
+
+export {
+  ColdStorageTestSuite,
+  type ColdStorageTestError,
+} from "./ColdStorageTestSuite";
+export {
+  HotStorageTestSuite,
+  type HotStorageTestError,
+} from "./HotStorageTestSuite";
+export { StorageIntegrationTestSuite } from "./StorageIntegrationTestSuite";
+
+// =============================================================================
+// Test Utilities
+// =============================================================================
+
+export {
+  FailingStorage,
+  type FailingColdStorageConfig,
+  type FailingHotStorageConfig,
+} from "./FailingStorage";
+
+// =============================================================================
+// Re-export Categories for Convenience
+// =============================================================================
+
+export { Categories as ColdStorageCategories } from "./ColdStorageTestSuite";
+export { Categories as HotStorageCategories } from "./HotStorageTestSuite";
+export { Categories as IntegrationCategories } from "./StorageIntegrationTestSuite";

package/src/testing/types.ts

@@ -0,0 +1,100 @@
+/**
+ * @voidhash/mimic-effect/testing - Core Types
+ *
+ * Types used by the storage adapter test utilities.
+ */
+import { Data, Effect } from "effect";
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/**
+ * Error thrown when a test assertion fails.
+ */
+export class TestError extends Data.TaggedError("TestError")<{
+  /** Description of what failed */
+  readonly message: string;
+  /** Expected value (if applicable) */
+  readonly expected?: unknown;
+  /** Actual value received (if applicable) */
+  readonly actual?: unknown;
+}> {}
+
+// =============================================================================
+// Test Case Types
+// =============================================================================
+
+/**
+ * A single storage adapter test case.
+ *
+ * Test cases are framework-agnostic Effects that can be run with any test runner.
+ *
+ * @template E - The error type for this test case
+ * @template R - The Effect requirements (e.g., ColdStorageTag or HotStorageTag)
+ *
+ * @example
+ * ```typescript
+ * // Using with vitest
+ * const tests = ColdStorageTestSuite.makeTests();
+ *
+ * describe("MyAdapter", () => {
+ *   for (const test of tests) {
+ *     it(test.name, () =>
+ *       Effect.runPromise(test.run.pipe(Effect.provide(myAdapterLayer)))
+ *     );
+ *   }
+ * });
+ * ```
+ */
+export interface StorageTestCase<E, R> {
+  /** Human-readable test name */
+  readonly name: string;
+  /** Category for grouping (e.g., "Basic Operations", "Data Integrity") */
+  readonly category: string;
+  /** The test as an Effect - succeeds if test passes, fails with error if not */
+  readonly run: Effect.Effect<void, E, R>;
+}
+
+// =============================================================================
+// Test Results Types
+// =============================================================================
+
+/**
+ * Result of a failed test.
+ */
+export interface FailedTest<E, R> {
+  /** The test case that failed */
+  readonly test: StorageTestCase<E, R>;
+  /** The error that caused the failure */
+  readonly error: E;
+}
+
+/**
+ * Results from running all tests in a suite.
+ *
+ * @example
+ * ```typescript
+ * const results = await Effect.runPromise(
+ *   ColdStorageTestSuite.runAll().pipe(Effect.provide(myAdapterLayer))
+ * );
+ *
+ * console.log(`Passed: ${results.passCount}/${results.total}`);
+ *
+ * for (const { test, error } of results.failed) {
+ *   console.error(`FAIL: ${test.name} - ${error._tag}`);
+ * }
+ * ```
+ */
+export interface TestResults<E, R> {
+  /** Tests that passed */
+  readonly passed: StorageTestCase<E, R>[];
+  /** Tests that failed with their errors */
+  readonly failed: FailedTest<E, R>[];
+  /** Total number of tests run */
+  readonly total: number;
+  /** Number of tests that passed */
+  readonly passCount: number;
+  /** Number of tests that failed */
+  readonly failCount: number;
+}

package/tests/ColdStorage.test.ts

@@ -1,131 +1,19 @@
 import { describe, it, expect } from "vitest";
-import { Effect, Layer } from "effect";
+import { Effect } from "effect";
 import { ColdStorage, ColdStorageTag } from "../src/ColdStorage";
-import type { StoredDocument } from "../src/Types";
+import { ColdStorageTestSuite } from "../src/testing";
 
 describe("ColdStorage", () => {
   describe("InMemory", () => {
+    // Use the test suite utilities for comprehensive testing
     const layer = ColdStorage.InMemory.make();
 
-    it("should return undefined for missing document", async () => {
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* ColdStorageTag;
-          return yield* storage.load("non-existent");
-        }).pipe(Effect.provide(layer))
+    // Run all test suite tests
+    for (const test of ColdStorageTestSuite.makeTests()) {
+      it(`[${test.category}] ${test.name}`, () =>
+        Effect.runPromise(test.run.pipe(Effect.provide(layer)))
       );
-
-      expect(result).toBeUndefined();
-    });
-
-    it("should save and load document", async () => {
-      const doc: StoredDocument = {
-        state: { title: "Test", count: 42 },
-        version: 5,
-        schemaVersion: 1,
-        savedAt: Date.now(),
-      };
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* ColdStorageTag;
-          yield* storage.save("doc-1", doc);
-          return yield* storage.load("doc-1");
-        }).pipe(Effect.provide(layer))
-      );
-
-      expect(result).toEqual(doc);
-    });
-
-    it("should update existing document", async () => {
-      const doc1: StoredDocument = {
-        state: { title: "First" },
-        version: 1,
-        schemaVersion: 1,
-        savedAt: Date.now(),
-      };
-
-      const doc2: StoredDocument = {
-        state: { title: "Second" },
-        version: 2,
-        schemaVersion: 1,
-        savedAt: Date.now(),
-      };
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* ColdStorageTag;
-          yield* storage.save("doc-1", doc1);
-          yield* storage.save("doc-1", doc2);
-          return yield* storage.load("doc-1");
-        }).pipe(Effect.provide(layer))
-      );
-
-      expect(result).toEqual(doc2);
-    });
-
-    it("should delete document", async () => {
-      const doc: StoredDocument = {
-        state: { title: "To Delete" },
-        version: 1,
-        schemaVersion: 1,
-        savedAt: Date.now(),
-      };
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* ColdStorageTag;
-          yield* storage.save("doc-1", doc);
-          yield* storage.delete("doc-1");
-          return yield* storage.load("doc-1");
-        }).pipe(Effect.provide(layer))
-      );
-
-      expect(result).toBeUndefined();
-    });
-
-    it("should handle multiple documents independently", async () => {
-      const doc1: StoredDocument = {
-        state: { title: "Doc 1" },
-        version: 1,
-        schemaVersion: 1,
-        savedAt: Date.now(),
-      };
-
-      const doc2: StoredDocument = {
-        state: { title: "Doc 2" },
-        version: 2,
-        schemaVersion: 1,
-        savedAt: Date.now(),
-      };
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* ColdStorageTag;
-          yield* storage.save("doc-1", doc1);
-          yield* storage.save("doc-2", doc2);
-
-          const loaded1 = yield* storage.load("doc-1");
-          const loaded2 = yield* storage.load("doc-2");
-
-          return { loaded1, loaded2 };
-        }).pipe(Effect.provide(layer))
-      );
-
-      expect(result.loaded1).toEqual(doc1);
-      expect(result.loaded2).toEqual(doc2);
-    });
-
-    it("should not error when deleting non-existent document", async () => {
-      await expect(
-        Effect.runPromise(
-          Effect.gen(function* () {
-            const storage = yield* ColdStorageTag;
-            yield* storage.delete("non-existent");
-          }).pipe(Effect.provide(layer))
-        )
-      ).resolves.toBeUndefined();
-    });
+    }
   });
 
   describe("Tag", () => {

package/tests/HotStorage.test.ts

@@ -1,138 +1,19 @@
 import { describe, it, expect } from "vitest";
 import { Effect } from "effect";
 import { HotStorage, HotStorageTag } from "../src/HotStorage";
-import type { WalEntry } from "../src/Types";
-import { Transaction } from "@voidhash/mimic";
+import { HotStorageTestSuite } from "../src/testing";
 
 describe("HotStorage", () => {
   describe("InMemory", () => {
+    // Use the test suite utilities for comprehensive testing
     const layer = HotStorage.InMemory.make();
 
-    const makeEntry = (version: number): WalEntry => ({
-      transaction: Transaction.make([]),
-      version,
-      timestamp: Date.now(),
-    });
-
-    it("should return empty array for missing document", async () => {
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* HotStorageTag;
-          return yield* storage.getEntries("non-existent", 0);
-        }).pipe(Effect.provide(layer))
-      );
-
-      expect(result).toEqual([]);
-    });
-
-    it("should append and retrieve entries", async () => {
-      const entry1 = makeEntry(1);
-      const entry2 = makeEntry(2);
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* HotStorageTag;
-          yield* storage.append("doc-1", entry1);
-          yield* storage.append("doc-1", entry2);
-          return yield* storage.getEntries("doc-1", 0);
-        }).pipe(Effect.provide(layer))
-      );
-
-      expect(result.length).toBe(2);
-      expect(result[0]!.version).toBe(1);
-      expect(result[1]!.version).toBe(2);
-    });
-
-    it("should filter entries by sinceVersion", async () => {
-      const entries = [makeEntry(1), makeEntry(2), makeEntry(3), makeEntry(4)];
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* HotStorageTag;
-          for (const entry of entries) {
-            yield* storage.append("doc-1", entry);
-          }
-          return yield* storage.getEntries("doc-1", 2);
-        }).pipe(Effect.provide(layer))
-      );
-
-      expect(result.length).toBe(2);
-      expect(result[0]!.version).toBe(3);
-      expect(result[1]!.version).toBe(4);
-    });
-
-    it("should truncate entries up to version", async () => {
-      const entries = [makeEntry(1), makeEntry(2), makeEntry(3), makeEntry(4)];
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* HotStorageTag;
-          for (const entry of entries) {
-            yield* storage.append("doc-1", entry);
-          }
-          yield* storage.truncate("doc-1", 2);
-          return yield* storage.getEntries("doc-1", 0);
-        }).pipe(Effect.provide(layer))
+    // Run all test suite tests
+    for (const test of HotStorageTestSuite.makeTests()) {
+      it(`[${test.category}] ${test.name}`, () =>
+        Effect.runPromise(test.run.pipe(Effect.provide(layer)))
       );
-
-      expect(result.length).toBe(2);
-      expect(result[0]!.version).toBe(3);
-      expect(result[1]!.version).toBe(4);
-    });
-
-    it("should maintain order after append", async () => {
-      const entries = [makeEntry(3), makeEntry(1), makeEntry(2)];
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* HotStorageTag;
-          for (const entry of entries) {
-            yield* storage.append("doc-1", entry);
-          }
-          return yield* storage.getEntries("doc-1", 0);
-        }).pipe(Effect.provide(layer))
-      );
-
-      // Should be sorted by version
-      expect(result.length).toBe(3);
-      expect(result[0]!.version).toBe(1);
-      expect(result[1]!.version).toBe(2);
-      expect(result[2]!.version).toBe(3);
-    });
-
-    it("should isolate documents", async () => {
-      const entry1 = makeEntry(1);
-      const entry2 = makeEntry(2);
-
-      const result = await Effect.runPromise(
-        Effect.gen(function* () {
-          const storage = yield* HotStorageTag;
-          yield* storage.append("doc-1", entry1);
-          yield* storage.append("doc-2", entry2);
-
-          const entries1 = yield* storage.getEntries("doc-1", 0);
-          const entries2 = yield* storage.getEntries("doc-2", 0);
-
-          return { entries1, entries2 };
-        }).pipe(Effect.provide(layer))
-      );
-
-      expect(result.entries1.length).toBe(1);
-      expect(result.entries1[0]!.version).toBe(1);
-      expect(result.entries2.length).toBe(1);
-      expect(result.entries2[0]!.version).toBe(2);
-    });
-
-    it("should not error when truncating non-existent document", async () => {
-      await expect(
-        Effect.runPromise(
-          Effect.gen(function* () {
-            const storage = yield* HotStorageTag;
-            yield* storage.truncate("non-existent", 5);
-          }).pipe(Effect.provide(layer))
-        )
-      ).resolves.toBeUndefined();
-    });
+    }
   });
 
   describe("Tag", () => {