@evolu/common 8.6.2 → 8.8.0

package/src/Task.ts

@@ -76,7 +76,7 @@
  * });
  *
  * const result = await run(getUser(user.id));
- * assertType<Result<User, UserNotFoundError>, typeof result>();
+ * assertType<typeof result, Result<User, UserNotFoundError>>();
  * assertOk(result, user);
  * ```
  *
@@ -181,11 +181,11 @@
  * await using run = createRun();
  * const result = await run(getUserWithProfile("user-1"));
  * assertType<
+ *   typeof result,
  *   Result<
  *     { readonly user: User; readonly profile: Profile },
  *     UserNotFoundError | ProfileNotFoundError
- *   >,
- *   typeof result
+ *   >
  * >();
  * assertOk(result, {
  *   user: { id: "user-1", profileId: "profile-1" },
@@ -228,8 +228,8 @@
  *   );
  *
  * assertType<
- *   Task<string, RetryTaskError<FetchError | TimeoutError>>,
- *   ReturnType<typeof fetchWithRetry>
+ *   ReturnType<typeof fetchWithRetry>,
+ *   Task<string, RetryTaskError<FetchError | TimeoutError>>
  * >();
  * ```
  *
@@ -685,7 +685,7 @@ import {
   type RandomBytes,
   type RandomBytesDep,
 } from "./Crypto.ts";
-import { eqArrayStrict } from "./Eq.ts";
+import { eqArraySameValue } from "./Eq.ts";
 import { constTrue, constVoid, identity } from "./Function.ts";
 import type { fetch, NativeFetch, NativeFetchDep } from "./Http.ts";
 import {
@@ -742,7 +742,6 @@ import {
   type TestTimeDep,
 } from "./Time.ts";
 import {
-  assertType,
   createId,
   type InferType,
   maxPositiveInt,
@@ -1177,7 +1176,7 @@ export interface Run<D = unknown> {
    *
    * await using run = createRun();
    * const fiber = run.abortable(loadUser, { db });
-   * assertType<AbortableFiber<string, never, DbDep>, typeof fiber>();
+   * assertType<typeof fiber, AbortableFiber<string, never, DbDep>>();
    * fiber.abort();
    * const userResult = await fiber;
    * assertFalse(userResult.ok);
@@ -1629,7 +1628,7 @@ export interface DisposableRun<D = unknown>
  * const userResult = await fiber;
  * const snapshot = fiber.run.snapshot();
  *
- * assertType<Fiber<string, never>, typeof fiber>();
+ * assertType<typeof fiber, Fiber<string, never>>();
  * assertOk(userResult, "Ada");
  * assertEqual(snapshot.id, fiber.run.id);
  * ```
@@ -1710,7 +1709,7 @@ export type InferFiberDeps<TFiber extends AnyFiber> =
  * };
  *
  * const fiber = run.abortable<string, never>(fetchData);
- * assertType<AbortableFiber<string, never>, typeof fiber>();
+ * assertType<typeof fiber, AbortableFiber<string, never>>();
  * fiber.abort();
  * const result = await fiber;
  * assertFalse(result.ok);
@@ -2721,7 +2720,7 @@ const createRunInternal = <D extends object>(
       // concern. Attach this late so V8 captures the defect stack before any
       // catch observes the Fiber.
       void fiber.catch(constVoid);
-      // eslint-disable-next-line @typescript-eslint/only-throw-error -- AbortError is Task abort control flow; aborts intentionally carry no stack.
+      // oxlint-disable-next-line typescript/only-throw-error -- AbortError is Task abort control flow; aborts intentionally carry no stack.
       throw taskExit.error;
     };
 
@@ -2743,13 +2742,13 @@ const createRunInternal = <D extends object>(
 
   const root = rootRun ?? run;
 
-  /* eslint-disable @typescript-eslint/no-unsafe-return -- Internal overload assignments implement public generics via TaskInternal. */
+  /* oxlint-disable typescript/no-unsafe-return -- Internal overload assignments implement public generics via TaskInternal. */
   run.orThrow = (async (task: TaskInternal, taskDeps?: object) =>
     getOrThrow(await run(task, taskDeps))) as Run<D>["orThrow"];
 
   run.ok = (async (task: TaskInternal, taskDeps?: object) =>
     getOk((await run(task, taskDeps)) as Result<any>)) as Run<D>["ok"];
-  /* eslint-enable @typescript-eslint/no-unsafe-return */
+  /* oxlint-enable typescript/no-unsafe-return */
 
   run.abortable = ((task: TaskInternal, deps?: object) =>
     run(task, deps, { abortable: true })) as Run<D>["abortable"];
@@ -2812,7 +2811,7 @@ const createRunInternal = <D extends object>(
 
     if (
       snapshot?.state !== state ||
-      !eqArrayStrict(snapshot.children, childSnapshots)
+      !eqArraySameValue(snapshot.children, childSnapshots)
     ) {
       snapshot = {
         id: run.id,
@@ -2855,7 +2854,7 @@ const createRunInternal = <D extends object>(
 
   run[Symbol.asyncDispose] = async (): Promise<void> => {
     await dispose();
-    // eslint-disable-next-line @typescript-eslint/only-throw-error -- AbortError is Task abort control flow; rethrowing it avoids reporting the finalizer defect twice in Task code.
+    // oxlint-disable-next-line typescript/only-throw-error -- AbortError is Task abort control flow; rethrowing it avoids reporting the finalizer defect twice in Task code.
     if (finalizerAbortError) throw finalizerAbortError;
   };
 
@@ -3017,7 +3016,7 @@ export type InferTasksOk<TTasks> = {
  *     collect: false,
  *   }),
  * );
- * assertType<Result<void, SaveUserFailedError>, typeof saveResult>();
+ * assertType<typeof saveResult, Result<void, SaveUserFailedError>>();
  * assertErr(saveResult, {
  *   type: "SaveUserFailed",
  *   userId: "missing",
@@ -3069,8 +3068,8 @@ export function all<const TTasks extends TaskRecord>(
  * await using run = createRun();
  * const dashboard = await run(all([fetchUser, fetchPosts]));
  * assertType<
- *   Result<readonly [User, ReadonlyArray<Post>]>,
- *   typeof dashboard
+ *   typeof dashboard,
+ *   Result<readonly [User, ReadonlyArray<Post>]>
  * >();
  * assertOk(dashboard, [{ id: "user-1" }, [{ id: "post-1" }]]);
  * ```
@@ -3116,8 +3115,8 @@ export function all<const TTasks extends ReadonlyArray<AnyTask>>(
  * const result = await run(all({ user: fetchUser, posts: fetchPosts }));
  *
  * assertType<
- *   Result<{ readonly user: User; readonly posts: ReadonlyArray<Post> }>,
- *   typeof result
+ *   typeof result,
+ *   Result<{ readonly user: User; readonly posts: ReadonlyArray<Post> }>
  * >();
  * assertOk(result, {
  *   user: { id: "user-1" },
@@ -3194,7 +3193,7 @@ export function all<
  *
  * await using run = createRun();
  * const result = await run(loadUsers);
- * assertType<Result<readonly [User, User]>, typeof result>();
+ * assertType<typeof result, Result<readonly [User, User]>>();
  * assertOk(result, [{ id: "user-1" }, { id: "user-2" }]);
  * ```
  */
@@ -3253,8 +3252,8 @@ export function all<
  * await using run = createRun();
  * const result = await run(loadUsersByRole);
  * assertType<
- *   Result<{ readonly admin: User; readonly reviewer: User }>,
- *   typeof result
+ *   typeof result,
+ *   Result<{ readonly admin: User; readonly reviewer: User }>
  * >();
  * assertOk(result, {
  *   admin: { id: "user-1" },
@@ -3362,13 +3361,13 @@ export type InferTasksSettled<TTasks> = {
  * await using run = createRun();
  * const results = await run(allSettled([loadProfile, loadActivity]));
  * assertType<
+ *   typeof results,
  *   Result<
  *     readonly [
  *       Result<string, ProfileNotFoundError>,
  *       Result<ReadonlyArray<string>>,
  *     ]
- *   >,
- *   typeof results
+ *   >
  * >();
  * assertOk(results, [
  *   { ok: false, error: { type: "ProfileNotFound" } },
@@ -3419,11 +3418,11 @@ export function allSettled<const TTasks extends ReadonlyArray<AnyTask>>(
  * );
  *
  * assertType<
+ *   typeof results,
  *   Result<{
  *     readonly user: Result<User>;
  *     readonly profile: Result<string, ProfileNotFoundError>;
- *   }>,
- *   typeof results
+ *   }>
  * >();
  * assertOk(results, {
  *   user: { ok: true, value: { id: "user-1" } },
@@ -3479,13 +3478,13 @@ export function allSettled<const TTasks extends TaskRecord>(
  * await using run = createRun();
  * const results = await run(loadUsers);
  * assertType<
+ *   typeof results,
  *   Result<
  *     readonly [
  *       Result<User, UserNotFoundError>,
  *       Result<User, UserNotFoundError>,
  *     ]
- *   >,
- *   typeof results
+ *   >
  * >();
  * assertOk(results, [
  *   { ok: true, value: { id: "user-1" } },
@@ -3554,11 +3553,11 @@ export function allSettled<
  * await using run = createRun();
  * const results = await run(loadUsersByRole);
  * assertType<
+ *   typeof results,
  *   Result<{
  *     readonly admin: Result<User, UserNotFoundError>;
  *     readonly reviewer: Result<User, UserNotFoundError>;
- *   }>,
- *   typeof results
+ *   }>
  * >();
  * assertOk(results, {
  *   admin: { ok: true, value: { id: "user-1" } },
@@ -3806,7 +3805,7 @@ export const sleep = (duration: PositiveDuration): Task<void> =>
  * await using run = createRun();
  *
  * const result = await run(timeout(waitForAbort, "1ms"));
- * assertType<Result<never, TimeoutError>, typeof result>();
+ * assertType<typeof result, Result<never, TimeoutError>>();
  * assertErr(result, timeoutError);
  * ```
  *
@@ -3928,8 +3927,8 @@ export interface RetryAttempt<E, Output> extends ScheduleStep<Output> {
  * await using run = createRun();
  * const result = await run(fetchWithRetry);
  * assertType<
- *   Result<string, RetryTaskError<ServiceUnavailableError>>,
- *   typeof result
+ *   typeof result,
+ *   Result<string, RetryTaskError<ServiceUnavailableError>>
  * >();
  * assertErr(result, {
  *   type: "RetryError",
@@ -4238,7 +4237,7 @@ export type InferTasksResult<TTasks extends NonEmptyReadonlyArray<AnyTask>> =
  * await using run = createRun();
  * const result = await run(any([unavailable, fallback]));
  *
- * assertType<Result<string, ServiceUnavailableError>, typeof result>();
+ * assertType<typeof result, Result<string, ServiceUnavailableError>>();
  * assertOk(result, "fallback");
  * assertTrue(fallbackStarted);
  * ```
@@ -4355,7 +4354,7 @@ export const any =
  * // Input order does not matter: the first settled Result wins, and the
  * // still-running loser is aborted.
  * const result = await run(race([slow, fast]));
- * assertType<Result<string>, typeof result>();
+ * assertType<typeof result, Result<string>>();
  * assertOk(result, "fast");
  * assertFalse(slowCompleted);
  * ```
@@ -4455,8 +4454,6 @@ export const firstN =
     InferTasksDeps<TTasks>
   > =>
   async (run) => {
-    assertType(PositiveInt, count);
-
     const values: Array<InferTaskOk<TTasks[number]>> = [];
     await run(
       each(
@@ -4534,8 +4531,6 @@ export const firstNSettled =
     InferTasksDeps<TTasks>
   > =>
   async (run) => {
-    assertType(PositiveInt, count);
-
     const results: Array<InferTasksResult<TTasks>> = [];
     await run(
       each(
@@ -4885,7 +4880,7 @@ export const yieldNow: Task<void> = async (run) => {
  *   return await run(waitForAbort);
  * };
  *
- * assertType<Task<never, never, ServerDep>, ReturnType<typeof serve>>();
+ * assertType<ReturnType<typeof serve>, Task<never, never, ServerDep>>();
  *
  * await using run = createRun();
  * const fiber = run.abortable(serve(), { port: 3000 });
@@ -5028,7 +5023,7 @@ export const waitForAbort: Task<never> = async (run) => {
  * const task: Task<ResultValue> = () => promise;
  *
  * assertTrue(promiseStarted);
- * assertType<Task<ResultValue>, typeof task>();
+ * assertType<typeof task, Task<ResultValue>>();
  * ```
  *
  * @group Lifetime
@@ -5358,7 +5353,7 @@ export interface Deferred<T, E = never> {
  * assertTrue(deferred.resolve(ok("ready")));
  *
  * const result = await fiber;
- * assertType<Result<string>, typeof result>();
+ * assertType<typeof result, Result<string>>();
  * assertOk(result, "ready");
  *
  * // A Deferred is one-shot: later resolutions are ignored, and future

package/src/Test.test.ts

@@ -0,0 +1,88 @@
+import { describe, it } from "node:test";
+import { assertEqual, assertFalse } from "./Assert.ts";
+
+import type { Brand } from "./Brand.ts";
+import { testCreateId, testStubGlobal } from "./Test.ts";
+import { assertType, type Id } from "./Type.ts";
+
+describe("testStubGlobal", () => {
+  it("deletes a previously absent property on disposal", () => {
+    const key = Symbol("absent global");
+    const stub = testStubGlobal(key, 42);
+
+    assertEqual(Reflect.get(globalThis, key), 42);
+
+    stub[Symbol.dispose]();
+    stub[Symbol.dispose]();
+
+    assertFalse(Reflect.has(globalThis, key));
+  });
+
+  it("restores the original property descriptor", () => {
+    const key = Symbol("existing global");
+    const original = {
+      configurable: true,
+      enumerable: true,
+      get: () => 1,
+    } satisfies PropertyDescriptor;
+    using cleanup = new DisposableStack();
+    cleanup.defer(() => {
+      Reflect.deleteProperty(globalThis, key);
+    });
+    Object.defineProperty(globalThis, key, original);
+
+    {
+      using _stub = testStubGlobal(key, 2);
+
+      assertEqual(Reflect.get(globalThis, key), 2);
+    }
+
+    const restored = Object.getOwnPropertyDescriptor(globalThis, key);
+    assertEqual(restored, {
+      configurable: true,
+      enumerable: true,
+      get: original.get,
+      set: undefined,
+    });
+  });
+
+  it("restores nested stubs in disposal order", () => {
+    const key = Symbol("nested global");
+
+    {
+      using _outer = testStubGlobal(key, "outer");
+      assertEqual(Reflect.get(globalThis, key), "outer");
+
+      {
+        using _inner = testStubGlobal(key, "inner");
+        assertEqual(Reflect.get(globalThis, key), "inner");
+      }
+
+      assertEqual(Reflect.get(globalThis, key), "outer");
+    }
+
+    assertFalse(Reflect.has(globalThis, key));
+  });
+});
+
+describe("testCreateId", () => {
+  it("creates file-local stable pseudo-random ids", () => {
+    const createTestId = testCreateId();
+    const first = createTestId();
+    const second = createTestId();
+
+    assertEqual(
+      [first, second],
+      ["ncqMQ1uwd5-zf5YKUbT3VA", "ofZXw_hAfJ8fIcpFxi6nag"],
+    );
+    assertFalse(Object.is(second, first));
+    assertType<typeof first, Id>();
+  });
+
+  it("preserves branded id typing", () => {
+    const createTestId = testCreateId();
+    const _todoId = createTestId<"Todo">();
+
+    assertType<typeof _todoId, Id & Brand<"Todo">>();
+  });
+});

package/src/Test.ts

@@ -1,8 +1,9 @@
 /**
  * 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.
+ * Test helpers are usually colocated with the code they test. General helpers
+ * shared across unrelated modules, or helpers whose colocation would create
+ * dependency cycles, belong here.
  *
  * @module
  */
@@ -12,6 +13,51 @@ import { testCreateRandomBytes } from "./Crypto.ts";
 import { testCreateRandomLib } from "./Random.ts";
 import { createId, type Id } from "./Type.ts";
 
+/**
+ * Temporarily replaces a global property for a test scope.
+ *
+ * Node.js can mock existing globals with `t.mock.property`, but it rejects a
+ * property that does not exist. That catches misspelled mock targets, but it
+ * cannot model optional platform globals whose presence varies. Use this helper
+ * to provide such a global, for example `scheduler`, or replace a global with
+ * `undefined` to exercise a fallback.
+ *
+ * The original property descriptor is restored on disposal. A property that did
+ * not exist is deleted. Prefer dependency injection when available because
+ * global properties are shared by concurrently running tests.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, assertFalse, testStubGlobal } from "@evolu/common";
+ *
+ * const key = Symbol("test global");
+ * {
+ *   using _stub = testStubGlobal(key, 42);
+ *   assertEqual(Reflect.get(globalThis, key), 42);
+ * }
+ * assertFalse(Reflect.has(globalThis, key));
+ * ```
+ */
+export const testStubGlobal = (
+  key: PropertyKey,
+  value: unknown,
+): Disposable => {
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, key);
+  Object.defineProperty(globalThis, key, {
+    configurable: true,
+    value,
+    writable: true,
+  });
+
+  const disposer = new DisposableStack();
+  disposer.defer(() => {
+    if (descriptor === undefined) Reflect.deleteProperty(globalThis, key);
+    else Object.defineProperty(globalThis, key, descriptor);
+  });
+  return disposer;
+};
+
 export type TestCreateId = <B extends string = never>() => [B] extends [never]
   ? Id
   : Id & Brand<B>;
@@ -48,7 +94,7 @@ export type TestCreateId = <B extends string = never>() => [B] extends [never]
  *
  * const replayCreateId = testCreateId();
  * assertEqual(replayCreateId(), callbackId);
- * assertType<Id & Brand<"Todo">, typeof todoId>();
+ * assertType<typeof todoId, Id & Brand<"Todo">>();
  * ```
  */
 export const testCreateId = (): TestCreateId => {