@evolu/common 8.9.0 → 8.11.0

package/src/Task.ts

@@ -686,6 +686,7 @@ import {
   type RandomBytesDep,
 } from "./Crypto.ts";
 import { eqArraySameValue } from "./Eq.ts";
+import type { defectToError } from "./Error.ts";
 import { constTrue, constVoid, identity } from "./Function.ts";
 import type { fetch, NativeFetch, NativeFetchDep } from "./Http.ts";
 import {
@@ -1462,10 +1463,20 @@ export interface Run<D = unknown> {
     callback: (abortError: AbortError) => void,
   ) => Disposable | null;
 
-  /** Returns the current {@link RunState} of this {@link Run}. */
+  /**
+   * Returns the current {@link RunState} of this {@link Run}.
+   *
+   * Abort requests are recorded before propagating to descendants. Observed
+   * aborts are recorded before this Run's abort callbacks execute.
+   */
   readonly getState: () => RunState;
 
-  /** Creates a memoized recursive {@link RunSnapshot} of the current Run tree. */
+  /**
+   * Creates a memoized recursive {@link RunSnapshot} of the current Run tree.
+   *
+   * Reflects abort requests and observations with the same timing as
+   * {@link Run.getState}.
+   */
   readonly snapshot: () => RunSnapshot;
 
   /**
@@ -2085,8 +2096,9 @@ export interface ReportDefectDep {
  * platforms without native global error reporting. Browser adapters use the
  * native
  * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/reportError | reportError}
- * API; other platform adapters can use platform-specific reporting and preserve
- * nested panic defects as cause or detail data.
+ * API, and other platform adapters can use platform-specific reporting.
+ * Adapters report an `Error` from {@link defectToError}, which such reporting
+ * shows readably.
  *
  * @group Run
  */
@@ -2481,6 +2493,7 @@ const createRunInternal = <D extends object>(
         : abortBehavior.abortMask;
 
   let state: RunState = runningRunState;
+  let publishedState: RunState = state;
   let exit: RunExit | undefined;
   let snapshot: RunSnapshot | undefined;
 
@@ -2533,6 +2546,13 @@ const createRunInternal = <D extends object>(
     }
   };
 
+  const publishState = (): void => {
+    // A nested disposal may have published this state before the outer abort.
+    if (publishedState === state) return;
+    publishedState = state;
+    emitEvent({ type: "StateChanged", state });
+  };
+
   // Reads abort reasons from the Run-owned controllers, which are only
   // aborted with AbortError.
   const currentAbort = (): RunAbortState["abort"] => ({
@@ -2542,17 +2562,10 @@ const createRunInternal = <D extends object>(
       : null,
   });
 
-  const commitState = (nextState: RunState): void => {
-    state = nextState;
-    emitEvent({ type: "StateChanged", state });
-  };
-
   const requestAbort = (reason: AbortReason = explicitAbortReason): void => {
     if (requestController.signal.aborted) return;
-    const abortError = createAbortError(reason);
-    requestController.abort(abortError);
-    if (abortMask === abortableMask) signalController.abort(abortError);
-    commitState({ type: "Aborted", abort: currentAbort() });
+    abortControllers(createAbortError(reason), abortMask === abortableMask);
+    publishState();
   };
 
   // The first provided exit claims the Run exit; later exits are ignored. A
@@ -2569,7 +2582,8 @@ const createRunInternal = <D extends object>(
 
     const settle = (): RunExit => {
       exit ??= ok(ok());
-      commitState({ type: "Settled", abort: currentAbort(), exit });
+      state = { type: "Settled", abort: currentAbort(), exit };
+      publishState();
       return exit;
     };
 
@@ -2590,14 +2604,39 @@ const createRunInternal = <D extends object>(
 
     const abortError = exit?.ok === false ? exit.error : runDisposedAbortError;
 
+    // If called from a local abort callback, let its abort operation finish
+    // dispatching callbacks before publishing the state.
     const { aborted } = signalController.signal;
-    requestController.abort(abortError);
-    signalController.abort(abortError);
-    if (!aborted) commitState({ type: "Aborted", abort: currentAbort() });
+    abortControllers(abortError, true);
+    if (!aborted) publishState();
 
     return disposePromise;
   };
 
+  const abortControllers = (abortError: AbortError, observe: boolean): void => {
+    // Record the request before propagation invokes descendant callbacks.
+    if (!requestController.signal.aborted) {
+      state = {
+        type: "Aborted",
+        abort: { request: abortError.reason, observed: null },
+      };
+      requestController.abort(abortError);
+    }
+
+    // A descendant callback may have disposed this Run reentrantly. Preserve
+    // the first observed reason; otherwise record it before local callbacks.
+    if (observe && !signalController.signal.aborted) {
+      state = {
+        type: "Aborted",
+        abort: {
+          request: (requestController.signal.reason as AbortError).reason,
+          observed: abortError.reason,
+        },
+      };
+      signalController.abort(abortError);
+    }
+  };
+
   // Custom deps replace parent custom deps, so defaults must be picked from
   // the merged deps by key. `satisfies RunDefaultDeps` fails to compile when
   // a newly added required default dep is missing here; optional ones like

package/src/Test.ts

@@ -38,6 +38,8 @@ import { createId, type Id } from "./Type.ts";
  * }
  * assertFalse(Reflect.has(globalThis, key));
  * ```
+ *
+ * @group Testing
  */
 export const testStubGlobal = (
   key: PropertyKey,
@@ -58,6 +60,11 @@ export const testStubGlobal = (
   return disposer;
 };
 
+/**
+ * Deterministic id factory returned by {@link testCreateId}.
+ *
+ * @group Testing
+ */
 export type TestCreateId = <B extends string = never>() => [B] extends [never]
   ? Id
   : Id & Brand<B>;
@@ -96,6 +103,8 @@ export type TestCreateId = <B extends string = never>() => [B] extends [never]
  * assertEqual(replayCreateId(), callbackId);
  * assertType<typeof todoId, Id & Brand<"Todo">>();
  * ```
+ *
+ * @group Testing
  */
 export const testCreateId = (): TestCreateId => {
   const randomBytes = testCreateRandomBytes({

package/src/Time.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, describe, it, mock } from "node:test";
 import {
   assertEqual,
+  assertErr,
+  assertOk,
   assertFalse,
   assertLength,
   assertSame,
@@ -37,19 +39,21 @@ import {
   saturateMillis,
   testCreateTime,
 } from "./Time.ts";
-import { assertType, type DateIso, NonNaNNumber } from "./Type.ts";
+import {
+  localizeTypes,
+  object,
+  typeErrorToIssues,
+  type InferErrors,
+  assertType,
+  type DateIso,
+  NonNaNNumber,
+} from "./Type.ts";
 
 const negativeMillisCause = {
   type: "NonNegative",
   value: -1,
 };
 
-const assertThrowsWithCause = (run: () => unknown, cause: unknown): void => {
-  const error = assertThrowsInstanceOf(run, Error);
-  assertEqual(error.message, "getOrThrow");
-  assertEqual(error.cause, cause);
-};
-
 describe("Time", () => {
   afterEach(() => {
     mock.restoreAll();
@@ -218,14 +222,17 @@ describe("Time", () => {
         );
         mock.method(Date, "now", () => -1);
 
-        assertThrowsWithCause(
+        const error = assertThrowsInstanceOf(
           () =>
             createTime().setTimeout(
               () => undefined,
               PositiveMillis.orThrow(2 ** 31),
             ),
-          negativeMillisCause,
+          Error,
         );
+
+        assertEqual(error.message, "The value -1 must be non-negative (>= 0).");
+        assertEqual(error.cause, negativeMillisCause);
         assertEqual(setTimeout.mock.callCount(), 0);
       });
 
@@ -247,7 +254,10 @@ describe("Time", () => {
         );
         now = -1;
 
-        assertThrowsWithCause(() => callbacks[0](), negativeMillisCause);
+        const error = assertThrowsInstanceOf(() => callbacks[0](), Error);
+
+        assertEqual(error.message, "The value -1 must be non-negative (>= 0).");
+        assertEqual(error.cause, negativeMillisCause);
         assertLength(callbacks, 1);
       });
 
@@ -445,7 +455,16 @@ describe("Time", () => {
     it("setTimeout rejects a deadline after maxMillis", () => {
       const time = testCreateTime({ startAt: maxMillis });
 
-      assertThrowsWithCause(() => time.setTimeout(() => undefined, "1ms"), {
+      const error = assertThrowsInstanceOf(
+        () => time.setTimeout(() => undefined, "1ms"),
+        Error,
+      );
+
+      assertEqual(
+        error.message,
+        "The value 281474976710655 must be less than 281474976710655.",
+      );
+      assertEqual(error.cause, {
         type: "LessThan281474976710655",
         value: maxMillis + 1,
         max: maxMillis + 1,
@@ -727,6 +746,58 @@ describe("Time", () => {
   });
 
   describe("DurationLiteral", () => {
+    it("reports a dedicated error with the original validation failure", () => {
+      for (const value of ["60s", "", 1, null, undefined]) {
+        const result = DurationLiteral.fromUnknown(value);
+        assertErr(result);
+        assertType<typeof result.error.type, "DurationLiteral">();
+        assertSame(result.error.value, value);
+        assertEqual(result.error.cause.type, "Union");
+        assertEqual(result.error.cause.errors.length, 1);
+      }
+      const result = DurationLiteral.fromUnknown("60s", { errors: "all" });
+      assertErr(result);
+      assertEqual(result.error.cause.errors.length, 7);
+      assertEqual(
+        DurationLiteral.formatError(result.error),
+        'The value "60s" is not a duration literal. Use a value such as "500ms" or "1.5s".',
+      );
+      assertType<
+        InferErrors<typeof DurationLiteral>["type"],
+        "DurationLiteral"
+      >();
+      assertOk(DurationLiteral.from("1.5s"), "1.5s");
+      assertEqual(DurationLiteral.to("1.5s"), "1.5s");
+      // @ts-expect-error DurationLiteral Input rejects "60s".
+      const _invalidInput: typeof DurationLiteral.Input = "60s";
+    });
+
+    it("localizes the named error after composition and preserves its path", async () => {
+      const { first } = localizeTypes(
+        { Value: DurationLiteral },
+        { first: { DurationLiteral: () => "First message." } },
+      );
+      const { second } = localizeTypes(
+        { Settings: object({ value: first.Value }) },
+        {
+          second: {
+            Object: () => "Object.",
+            DurationLiteral: () => "Second message.",
+          },
+        },
+      );
+      const result = second.Settings.fromUnknown({ value: "60s" });
+      assertErr(result);
+      assertEqual(second.Settings.formatError(result.error), "Second message.");
+      assertEqual(typeErrorToIssues(second.Settings, result.error), [
+        { path: ["value"], message: "Second message." },
+      ]);
+      assertEqual(
+        await second.Settings["~standard"].validate({ value: "60s" }),
+        { issues: [{ path: ["value"], message: "Second message." }] },
+      );
+    });
+
     it("valid durations", () => {
       // Milliseconds
       assertType<"1ms" extends DurationLiteral ? true : false, true>();