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

package/src/testing/assertions.ts

@@ -0,0 +1,188 @@
+/**
+ * @voidhash/mimic-effect/testing - Assertion Helpers
+ *
+ * Internal assertion helpers used by the test suites.
+ */
+import { Effect } from "effect";
+import { TestError } from "./types";
+
+// =============================================================================
+// Deep Equality
+// =============================================================================
+
+/**
+ * Deep equality check that handles objects, arrays, and primitives.
+ * Skips function properties since reconstructed objects (like OperationPath)
+ * will have new function instances even when the underlying data is identical.
+ */
+export const isDeepEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+
+  if (a === null || b === null) return a === b;
+  if (a === undefined || b === undefined) return a === b;
+
+  if (typeof a !== typeof b) return false;
+
+  // Skip function comparison - functions with same behavior but different references should be considered equal
+  if (typeof a === "function" && typeof b === "function") return true;
+
+  if (typeof a === "number" && typeof b === "number") {
+    if (Number.isNaN(a) && Number.isNaN(b)) return true;
+    return a === b;
+  }
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!isDeepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  if (typeof a === "object" && typeof b === "object") {
+    const aObj = a as Record<string, unknown>;
+    const bObj = b as Record<string, unknown>;
+
+    // Filter out function properties for comparison
+    const aKeys = Object.keys(aObj).filter(k => typeof aObj[k] !== "function");
+    const bKeys = Object.keys(bObj).filter(k => typeof bObj[k] !== "function");
+
+    if (aKeys.length !== bKeys.length) return false;
+
+    for (const key of aKeys) {
+      if (!Object.prototype.hasOwnProperty.call(bObj, key)) return false;
+      if (!isDeepEqual(aObj[key], bObj[key])) return false;
+    }
+
+    return true;
+  }
+
+  return false;
+};
+
+// =============================================================================
+// Assertion Helpers
+// =============================================================================
+
+/**
+ * Assert that two values are deeply equal.
+ */
+export const assertEqual = <T>(
+  actual: T,
+  expected: T,
+  message: string
+): Effect.Effect<void, TestError> =>
+  Effect.gen(function* () {
+    if (!isDeepEqual(actual, expected)) {
+      yield* Effect.fail(new TestError({ message, expected, actual }));
+    }
+  });
+
+/**
+ * Assert that a condition is true.
+ */
+export const assertTrue = (
+  condition: boolean,
+  message: string
+): Effect.Effect<void, TestError> =>
+  Effect.gen(function* () {
+    if (!condition) {
+      yield* Effect.fail(new TestError({ message }));
+    }
+  });
+
+/**
+ * Assert that a condition is false.
+ */
+export const assertFalse = (
+  condition: boolean,
+  message: string
+): Effect.Effect<void, TestError> =>
+  Effect.gen(function* () {
+    if (condition) {
+      yield* Effect.fail(new TestError({ message }));
+    }
+  });
+
+/**
+ * Assert that a value is undefined.
+ */
+export const assertUndefined = (
+  value: unknown,
+  message: string
+): Effect.Effect<void, TestError> =>
+  Effect.gen(function* () {
+    if (value !== undefined) {
+      yield* Effect.fail(
+        new TestError({ message, expected: undefined, actual: value })
+      );
+    }
+  });
+
+/**
+ * Assert that a value is defined (not undefined).
+ */
+export const assertDefined = <T>(
+  value: T | undefined,
+  message: string
+): Effect.Effect<T, TestError> =>
+  Effect.gen(function* () {
+    if (value === undefined) {
+      yield* Effect.fail(
+        new TestError({ message, expected: "defined value", actual: undefined })
+      );
+    }
+    return value as T;
+  });
+
+/**
+ * Assert that an array has the expected length.
+ */
+export const assertLength = <T>(
+  array: T[],
+  expectedLength: number,
+  message: string
+): Effect.Effect<void, TestError> =>
+  Effect.gen(function* () {
+    if (array.length !== expectedLength) {
+      yield* Effect.fail(
+        new TestError({
+          message,
+          expected: expectedLength,
+          actual: array.length,
+        })
+      );
+    }
+  });
+
+/**
+ * Assert that an array is empty.
+ */
+export const assertEmpty = <T>(
+  array: T[],
+  message: string
+): Effect.Effect<void, TestError> => assertLength(array, 0, message);
+
+/**
+ * Assert that an array is sorted by a key.
+ */
+export const assertSortedBy = <T>(
+  array: T[],
+  key: keyof T,
+  message: string
+): Effect.Effect<void, TestError> =>
+  Effect.gen(function* () {
+    for (let i = 1; i < array.length; i++) {
+      const prev = array[i - 1]![key];
+      const curr = array[i]![key];
+      if (prev > curr) {
+        yield* Effect.fail(
+          new TestError({
+            message,
+            expected: `array sorted by ${String(key)}`,
+            actual: `element at index ${i - 1} (${prev}) > element at index ${i} (${curr})`,
+          })
+        );
+      }
+    }
+  });

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", () => {