@evolu/common 8.0.0-next.5 → 8.0.0

package/src/Test.ts

@@ -1,171 +1,21 @@
 /**
- * Test utilities for deterministic testing.
+ * Cross-module test utilities for deterministic testing.
+ *
+ * Test helpers are usually colocated with the code they test. Helpers that
+ * cannot be colocated because they would create dependency cycles belong here.
  *
  * @module
  */
 
-import type { Brand } from "./Brand.js";
-import {
-  testCreateConsole,
-  type TestConsole,
-  type TestConsoleDep,
-} from "./Console.js";
-import { testCreateRandomBytes, type RandomBytes } from "./Crypto.js";
-import {
-  testCreateRandom,
-  testCreateRandomLib,
-  type Random,
-  type RandomLibDep,
-} from "./Random.js";
-import { createRun, type Run, type RunDefaultDeps } from "./Task.js";
-import {
-  minMillis,
-  setTimeout,
-  testCreateTime,
-  type Duration,
-  type TestTime,
-  type TestTimeDep,
-} from "./Time.js";
-import { createId, type Id } from "./Type.js";
+import type { Brand } from "./Brand.ts";
+import { testCreateRandomBytes } from "./Crypto.ts";
+import { testCreateRandomLib } from "./Random.ts";
+import { createId, type Id } from "./Type.ts";
 
 export type TestCreateId = <B extends string = never>() => [B] extends [never]
   ? Id
   : Id & Brand<B>;
 
-/**
- * Cheap deterministic baseline deps for tests.
- *
- * `TestDeps` includes test-friendly replacements for {@link RunDefaultDeps},
- * such as {@link TestConsole} and {@link TestTime}, plus extra helpers commonly
- * useful in tests and fixtures, such as `randomLib` (only that for now).
- *
- * Use it directly for synchronous test setup, fixtures, and helpers. It is also
- * intentionally the base deps used by {@link testCreateRun}.
- */
-export type TestDeps = Omit<RunDefaultDeps, "console" | "time"> &
-  TestConsoleDep &
-  TestTimeDep &
-  RandomLibDep;
-
-/**
- * Creates deterministic {@link TestDeps}.
- *
- * Each call creates fresh instances, so tests don't share state.
- *
- * Includes these deps:
- *
- * - `console`: {@link TestConsole}
- * - `random`: {@link Random}
- * - `randomLib`: seeded `random` package instance
- * - `randomBytes`: {@link RandomBytes}
- * - `time`: {@link TestTime}
- *
- * Use this for synchronous code that accepts deps directly. For tests that run
- * Tasks, use {@link testCreateRun}.
- *
- * ### Example
- *
- * ```ts
- * test("Callbacks with no argument", () => {
- *   const deps = testCreateDeps();
- *   const callbacks = createCallbacks(deps);
- *
- *   let called = false;
- *   const id = callbacks.register(() => {
- *     called = true;
- *   });
- *
- *   callbacks.execute(id);
- *   expect(called).toBe(true);
- * });
- * ```
- */
-export const testCreateDeps = (options?: {
-  readonly seed?: string;
-}): TestDeps => {
-  const seed = options?.seed ?? "evolu";
-  const console = testCreateConsole();
-  const random = testCreateRandom(seed);
-  const randomLib = testCreateRandomLib(seed);
-  const randomBytes = testCreateRandomBytes({ randomLib });
-  const time = testCreateTime();
-  return { console, randomBytes, random, randomLib, time };
-};
-
-/**
- * Creates a test {@link Run} with deterministic default deps or optional custom
- * deps.
- *
- * Use this as the default composition root in tests. Each call creates fresh
- * {@link TestDeps} via {@link testCreateDeps}, then merges any provided custom
- * deps.
- *
- * ### Example
- *
- * ```ts
- * // Default TestTime
- * await using run = testCreateRun();
- * const fiber = run(sleep("1s"));
- * run.deps.time.advance("1s");
- * await fiber;
- *
- * // For a single test, create the dependency using the Run.
- * await using run = testCreateRun();
- * await using foo = await run.orThrow(createFoo());
- * await run.orThrow(taskThatNeedsFoo, { foo });
- *
- * // If multiple tests need the same setup, create a disposable helper.
- * // Then `await using setup` disposes everything the helper owns.
- * const setupFoo = async () => {
- *   await using disposer = new AsyncDisposableStack();
- *   const run = disposer.use(testCreateRun());
- *   const foo = disposer.use(await run.orThrow(createFoo()));
- *   const runWithFoo = disposer.use(run.create({ ...run.deps, foo }));
- *   const disposables = disposer.move();
- *
- *   // Return whatever the tests need: a Run with the dependency,
- *   // the dependency itself, or both.
- *   return {
- *     run: runWithFoo,
- *     foo,
- *     [Symbol.asyncDispose]: () => disposables.disposeAsync(),
- *   };
- * };
- *
- * await using setup = await setupFoo();
- * const { run, foo } = setup;
- * expect(run.deps.foo).toBe(foo);
- * ```
- *
- * Name reusable setup helpers after what they set up:
- *
- * - `setupFoo` for reusable test setup for `Foo`
- * - `testSetupFoo` when a library module exports the helper as part of its public
- *   test API, e.g. `testSetupSqlite`.
- */
-export function testCreateRun(): Run<TestDeps>;
-
-/** With custom dependencies merged into {@link TestDeps}. */
-export function testCreateRun<D>(deps: D): Run<TestDeps & D>;
-
-export function testCreateRun<D>(deps?: D): Run<TestDeps & D> {
-  const defaults = testCreateDeps();
-  return createRun<TestDeps & D>({ ...defaults, ...deps } as TestDeps & D);
-}
-
-/**
- * Returns a Promise that resolves after a macrotask delay.
- *
- * Use this to model a real async boundary in a test double, for example an
- * async disposer that should not complete in the same turn.
- *
- * Avoid using it to coordinate assertions. Waiting for a macrotask tends to
- * make tests indirect and brittle.
- */
-export const testWaitForMacrotask = (
-  duration: Duration = minMillis,
-): Promise<void> => setTimeout(duration);
-
 /**
  * Creates a deterministic `createId` helper.
  *
@@ -181,13 +31,18 @@ export const testWaitForMacrotask = (
  * ### Example
  *
  * ```ts
- * test("creates stable ids", () => {
- *   const createId = testCreateId();
+ * import { testCreateId, type Brand, type Id } from "@evolu/common";
+ *
+ * const createId = testCreateId();
+ *
+ * const callbackId = createId();
+ * const secondCallbackId = createId();
+ * const todoId = createId<"Todo">();
+ * expect(new Set([callbackId, secondCallbackId, todoId]).size).toBe(3);
  *
- *   const callbackId = createId();
- *   const secondCallbackId = createId();
- *   const todoId = createId<"Todo">();
- * });
+ * const replayCreateId = testCreateId();
+ * expect(replayCreateId()).toBe(callbackId);
+ * expectTypeOf(todoId).toEqualTypeOf<Id & Brand<"Todo">>();
  * ```
  */
 export const testCreateId = (): TestCreateId => {
@@ -195,7 +50,5 @@ export const testCreateId = (): TestCreateId => {
     randomLib: testCreateRandomLib(),
   });
 
-  return <B extends string = never>(): [B] extends [never]
-    ? Id
-    : Id & Brand<B> => createId<B>({ randomBytes });
+  return (() => createId<never>({ randomBytes })) as TestCreateId;
 };