@evolu/common 8.14.0 → 8.15.1

package/src/Redacted.ts

@@ -6,7 +6,6 @@
 
 import { assert } from "./Assert.ts";
 import type { Brand } from "./Brand.ts";
-import type { Eq } from "./Eq.ts";
 
 /**
  * A wrapper type that prevents sensitive values from being accidentally exposed
@@ -18,13 +17,17 @@ import type { Eq } from "./Eq.ts";
  *
  * For type-level distinction between different secrets, use branded types.
  *
- * The actual value lives in a `WeakMap`, so it never appears as a property and
- * is automatically garbage collected when the wrapper is dropped. This is
- * better than a class with a private field because private fields are still
- * visible in devtools. Symbols can't be used because they don't support custom
- * `toString`.
+ * Redacted guards against accidental exposure, such as logs, error reports, and
+ * serialized payloads. It does not hide the value from a debugger: DevTools and
+ * heap snapshots can still reach it.
  *
- * Implements `Disposable` for automatic cleanup via the `using` syntax.
+ * A structured clone, such as a `postMessage` to a worker, does not copy the
+ * hidden value and arrives as an empty object. Reveal the value before posting
+ * it, and wrap it again on arrival if the receiver passes it to app code.
+ *
+ * Implements `Disposable`, so the `using` syntax detaches the value when the
+ * scope ends. Disposal does not overwrite the value or release other references
+ * to it.
  *
  * ### Example
  *
@@ -48,7 +51,6 @@ import type { Eq } from "./Eq.ts";
  * using redactedKey: RedactedApiKey = createRedacted(apiKey);
  * const fetchUser = (key: RedactedApiKey): ApiKey => revealRedacted(key);
  *
- * // oxlint-disable-next-line typescript/no-base-to-string -- Redacted intentionally implements a safe custom toString.
  * assertEqual(redactedKey.toString(), "<redacted>");
  * assertEqual(
  *   JSON.stringify({ apiKey: redactedKey }),
@@ -64,18 +66,32 @@ import type { Eq } from "./Eq.ts";
  *   using key = createRedacted(apiKey);
  *   return key;
  * })();
- * // Leaving the `using` scope removes the value from memory.
+ * // Leaving the `using` scope detaches the value, so revealing it throws.
  * assertErr(trySync(() => revealRedacted(disposedKey)));
  * ```
  */
 export interface Redacted<A> extends Brand<"Redacted">, Disposable {
-  /** The inner type. Useful for inference via `typeof redacted.Type`. */
+  /**
+   * The inner type. This is a type-only phantom property. Use it through
+   * `typeof redacted.Type`; it does not exist at runtime.
+   */
   readonly Type: A;
+  readonly toString: () => "<redacted>";
+  readonly toJSON: () => "<redacted>";
 }
 
 /** Creates a {@link Redacted} wrapper for a sensitive value. */
 export const createRedacted = <A>(value: A): Redacted<A> => {
-  const redacted = Object.create(proto) as Redacted<A>;
+  // Symbol.dispose is read here rather than in proto because installPolyfills
+  // runs after imported modules are evaluated. An arrow function also keeps a
+  // detached dispose method working.
+  const redacted = Object.create(proto, {
+    [Symbol.dispose]: {
+      value: () => {
+        registry.delete(redacted);
+      },
+    },
+  }) as Redacted<A>;
   registry.set(redacted, value);
   return redacted;
 };
@@ -84,11 +100,15 @@ const proto = {
   toString: () => redactedString,
   toJSON: () => redactedString,
   [Symbol.for("nodejs.util.inspect.custom")]: () => redactedString,
-  [Symbol.dispose](this: Redacted<unknown>) {
-    registry.delete(this);
-  },
 };
 const redactedString = "<redacted>";
+
+// The value lives in a WeakMap, so it is never a property: previews,
+// enumeration, and serialization cannot show it, and it is garbage collected
+// with the wrapper. A private field would show when DevTools expands the
+// object. The wrapper is an object, not a symbol, because a symbol cannot
+// customize toString or toJSON. DevTools can still reach the registry through
+// the scopes of the wrapper's functions.
 const registry = new WeakMap<Redacted<unknown>, unknown>();
 
 /**
@@ -97,6 +117,8 @@ const registry = new WeakMap<Redacted<unknown>, unknown>();
  * This is a separate function rather than a method on {@link Redacted} to make
  * access visually explicit and easy to grep in code reviews. Accessing
  * sensitive values should feel intentional, not convenient.
+ *
+ * Throws when the wrapper was disposed or is a structured clone.
  */
 export const revealRedacted = <A>(redacted: Redacted<A>): A => {
   assert(registry.has(redacted), "Redacted value was not in registry");
@@ -108,36 +130,3 @@ export const isRedacted = (value: unknown): value is Redacted<unknown> =>
   typeof value === "object" &&
   value !== null &&
   Object.getPrototypeOf(value) === proto;
-
-/**
- * Creates an {@link Eq} for {@link Redacted} values based on an equality function
- * for the underlying type.
- *
- * ### Example
- *
- * ```ts
- * import {
- *   assertFalse,
- *   assertTrue,
- *   createEqRedacted,
- *   createRedacted,
- *   eqString,
- *   type Brand,
- * } from "@evolu/common";
- *
- * type ApiKey = string & Brand<"ApiKey">;
- * const eqRedactedApiKey = createEqRedacted<ApiKey>(eqString);
- *
- * // Apply brands only after validation or at another trusted boundary.
- * using a = createRedacted("x" as ApiKey);
- * using b = createRedacted("x" as ApiKey);
- * using c = createRedacted("y" as ApiKey);
- *
- * assertTrue(eqRedactedApiKey(a, b));
- * assertFalse(eqRedactedApiKey(a, c));
- * ```
- */
-export const createEqRedacted =
-  <A>(eq: Eq<A>): Eq<Redacted<A>> =>
-  (x, y) =>
-    eq(revealRedacted(x), revealRedacted(y));

package/src/Type.test.ts

@@ -103,6 +103,7 @@ import {
   Digit1To59,
   Digit1To99,
   discriminatedUnion,
+  Email,
   EvoluType,
   finite,
   FiniteNumber,
@@ -121,6 +122,7 @@ import {
   idBytesTypeValueLength,
   id,
   idToIdBytes,
+  idToUuid,
   json,
   Json,
   JsonArray,
@@ -216,6 +218,8 @@ import {
   UnknownResult,
   uint8ArrayToBase64Url,
   UrlSafeString,
+  Uuid,
+  uuidToId,
   zeroNonNegativeInt,
   type AnyType,
   type ArrayElementIssue,
@@ -239,6 +243,7 @@ import {
   type DiscriminatedUnionMemberError,
   type DiscriminatedUnionMemberIssue,
   type DiscriminatedUnionType,
+  type EmailError,
   type EvoluTypeError,
   type ExtractTyped,
   type FiniteError,
@@ -354,6 +359,7 @@ import {
   type UnionInputType,
   type UnionMemberError,
   type UnionType,
+  type UuidError,
   type ValidationOptions,
   type ValidateLiteral,
   type ValidateOutput,
@@ -545,6 +551,7 @@ describe("Type", () => {
       Digit1To51,
       Digit1To59,
       Digit1To99,
+      Email,
       EvoluType,
       FiniteNumber,
       Function,
@@ -601,6 +608,7 @@ describe("Type", () => {
       UnknownNextResult,
       UnknownResult,
       UrlSafeString,
+      Uuid,
     } as const satisfies Readonly<Record<ExportedTypeKey, TypeNode>>;
 
     const IntrospectionRoot = createType(
@@ -679,6 +687,7 @@ describe("Type", () => {
       "DateIsoFromDate",
       "DecimalString",
       "DiscriminatedUnion",
+      "Email",
       "EvoluType",
       "Finite",
       "Function",
@@ -753,6 +762,7 @@ describe("Type", () => {
       "Unknown",
       "Uppercased",
       "UrlSafeString",
+      "Uuid",
     ] as const;
 
     assertType<
@@ -10013,6 +10023,122 @@ describe("BrandFactory", () => {
         });
       });
 
+      describe("Email", () => {
+        // Single-address cases from the WebKit and Chromium
+        // ValidityState-typeMismatch-email.js tests, without the cases that
+        // test the browser's whitespace sanitization.
+        it("accepts valid email addresses as defined by the HTML Standard", () => {
+          for (const value of [
+            "something@something.com",
+            "someone@localhost.localdomain",
+            "someone@127.0.0.1",
+            "a@b.b",
+            "a/b@domain.com",
+            "{}@domain.com",
+            "m*'!%@something.sa",
+            "tu!!7n7.ad##0!!!@company.ca",
+            "%@com.com",
+            "!#$%&'*+/=?^_`{|}~.-@com.com",
+            ".wooly@example.com",
+            "wo..oly@example.com",
+            "someone@do-ma-in.com",
+            "somebody@example",
+            "Ada@Example.COM",
+            "a@xn--maana-pta.com",
+            `${"a".repeat(64)}@p.com`,
+            `a@${"p".repeat(63)}.${"c".repeat(63)}`,
+          ]) {
+            assertEqual(Email.fromUnknown(value), ok(value));
+          }
+          assertType<typeof Email.Output, string & Brand<"Email">>();
+        });
+
+        it("rejects invalid email addresses", () => {
+          for (const value of [
+            "invalid:email@example.com",
+            "@somewhere.com",
+            "example.com",
+            "@@example.com",
+            "a space@example.com",
+            "something@ex..ample.com",
+            "a\b@c",
+            "someone@somewhere.com.",
+            '""test\blah""@example.com',
+            '"testblah"@example.com',
+            "someone@somewhere.com@",
+            "someone@somewhere_com",
+            "someone@some:where.com",
+            ".",
+            "F/s/f/a@feo+re.com",
+            "some+long+email+address@some+host-weird-/looking.com",
+            "a @p.com",
+            "a\t@p.com",
+            "a\u000B@p.com",
+            "a\u000C@p.com",
+            "a @p.com",
+            "a　@p.com",
+            "ddjk-s-jk@asl-.com",
+            "someone@do-.com",
+            "somebody@-.com",
+            `a@${"p".repeat(64)}.com`,
+            `a@p.${"c".repeat(64)}`,
+            " a@p.com",
+            "a@p.com\n",
+            "a@[127.0.0.1]",
+            "mañana@example.com",
+            "a@mañana.com",
+            "",
+          ]) {
+            assertEqual(
+              Email.fromUnknown(value),
+              err({ type: "Email", value }),
+            );
+          }
+          assertEqual(
+            Email.formatError({ type: "Email", value: "example.com" }),
+            'The value "example.com" is not a valid email address.',
+          );
+          assertType<typeof Email.Error, EmailError>();
+        });
+      });
+
+      describe("Uuid", () => {
+        it("accepts canonical lowercase UUIDs of every version and variant", () => {
+          for (const value of [
+            "20354d7a-e4fe-47af-8ff6-187bca92f3f9",
+            "0190a6f4-8c3e-7b2a-9d41-5e6f7a8b9c0d",
+            "00000000-0000-0000-0000-000000000000",
+            "ffffffff-ffff-ffff-ffff-ffffffffffff",
+            "01234567-89ab-0def-0123-456789abcdef",
+          ]) {
+            assertEqual(Uuid.fromUnknown(value), ok(value));
+          }
+          assertType<typeof Uuid.Output, string & Brand<"Uuid">>();
+        });
+
+        it("rejects non-canonical text", () => {
+          for (const value of [
+            "20354D7A-E4FE-47AF-8FF6-187BCA92F3F9",
+            "20354d7a-e4fe-47af-8ff6-187bca92f3F9",
+            "{20354d7a-e4fe-47af-8ff6-187bca92f3f9}",
+            "urn:uuid:20354d7a-e4fe-47af-8ff6-187bca92f3f9",
+            "20354d7ae4fe47af8ff6187bca92f3f9",
+            "20354d7a-e4fe-47af-8ff6-187bca92f3f",
+            "20354d7a-e4fe-47af-8ff6-187bca92f3f9 ",
+            "g0354d7a-e4fe-47af-8ff6-187bca92f3f9",
+            "invalid",
+            "",
+          ]) {
+            assertEqual(Uuid.fromUnknown(value), err({ type: "Uuid", value }));
+          }
+          assertEqual(
+            Uuid.formatError({ type: "Uuid", value: "invalid" }),
+            'The value "invalid" is not a canonical lowercase UUID.',
+          );
+          assertType<typeof Uuid.Error, UuidError>();
+        });
+      });
+
       describe("SimplePassword", () => {
         it("requires trimmed text containing between 8 and 64 characters", () => {
           assertEqual(
@@ -10195,6 +10321,46 @@ describe("BrandFactory", () => {
           assertEqual(idBytesTypeValueLength, 16);
           assertSame(idBytesToId(bytes), value);
         });
+
+        it("converts to and from a Uuid with the same bytes", () => {
+          const deps = testCreateDeps();
+          const uuid = Uuid.orThrow("0190a6f4-8c3e-7b2a-9d41-5e6f7a8b9c0d");
+          const value = uuidToId(uuid);
+
+          assertEqual(value, "AZCm9Iw-eyqdQV5veoucDQ");
+          assertEqualBytes(
+            idToIdBytes(value),
+            new globalThis.Uint8Array([
+              0x01, 0x90, 0xa6, 0xf4, 0x8c, 0x3e, 0x7b, 0x2a, 0x9d, 0x41, 0x5e,
+              0x6f, 0x7a, 0x8b, 0x9c, 0x0d,
+            ]),
+          );
+          assertSame(idToUuid(value), uuid);
+
+          for (const id of [
+            createId(deps),
+            createIdAsUuidv7(deps),
+            createIdFromString("uuid"),
+            uuidToId(Uuid.orThrow("00000000-0000-0000-0000-000000000000")),
+            uuidToId(Uuid.orThrow("ffffffff-ffff-ffff-ffff-ffffffffffff")),
+          ]) {
+            const converted = idToUuid(id);
+            assertTrue(Uuid.is(converted));
+            assertSame(uuidToId(converted), id);
+          }
+          assertEqual(idToUuid(createIdAsUuidv7(deps))[14], "7");
+
+          const todoId = uuidToId<"Todo">(uuid);
+          assertType<typeof value, Id>();
+          assertType<typeof todoId, Id & Brand<"Todo">>();
+          assertType<ReturnType<typeof idToUuid>, Uuid>();
+          void (() => {
+            // @ts-expect-error A union would assign multiple brands to one Id.
+            uuidToId<"Todo" | "User">(uuid);
+            // @ts-expect-error uuidToId accepts only a validated Uuid.
+            uuidToId("0190a6f4-8c3e-7b2a-9d41-5e6f7a8b9c0d");
+          });
+        });
       });
 
       describe("Int64String", () => {

package/src/Type.ts

@@ -194,7 +194,7 @@
  * ```
  *
  * Evolu includes dozens of predefined Types and Type factories. Use Types such
- * as {@link Age}, {@link PositiveInt}, {@link DateIso},
+ * as {@link Age}, {@link PositiveInt}, {@link DateIso}, {@link Email}, {@link Uuid},
  * {@link NonEmptyTrimmedString100}, {@link Base64Url}, and {@link Json} directly.
  * Build domain Types with factories such as {@link brand}, {@link typed},
  * {@link minLength}, {@link maxLength}, {@link array}, {@link object},
@@ -448,7 +448,7 @@
  *
  * @module
  */
-import { utf8ToBytes } from "@noble/ciphers/utils.js";
+import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/ciphers/utils.js";
 import { sha256 } from "@noble/hashes/sha2.js";
 import * as bip39 from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english.js";
@@ -7598,6 +7598,74 @@ export const Name = /*#__PURE__*/ brand(
 );
 export type Name = typeof Name.Output;
 
+/**
+ * Error returned when a string is not a valid {@link Email}.
+ *
+ * @group String
+ */
+export interface EmailError extends TypeError<"Email"> {
+  readonly value: string;
+}
+
+/**
+ * Email address as defined by the WHATWG HTML Standard.
+ *
+ * Email accepts a [valid email
+ * address](https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address),
+ * the syntax browsers enforce for `<input type="email">`. The HTML Standard
+ * deliberately departs from RFC 5322: it rejects quoted local parts, comments,
+ * IP address literals, and whitespace, and it accepts only ASCII. Use the ASCII
+ * (`xn--`) form of internationalized domains.
+ *
+ * Email does not normalize. The local part is case-sensitive, so different
+ * Email strings can still reach the same mailbox, and only a delivered message
+ * proves that an address exists.
+ *
+ * The HTML Standard limits each domain label to 63 characters but sets no total
+ * length. SMTP limits an address to 254 characters; compose
+ * `maxLength(254)(Email)` when that limit matters.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertErr,
+ *   assertOk,
+ *   Email,
+ *   maxLength,
+ * } from "@evolu/common";
+ *
+ * assertOk(Email.fromUnknown("ada@example.com"), "ada@example.com");
+ * assertOk(Email.fromUnknown("Ada@Example.com"), "Ada@Example.com");
+ *
+ * const invalid = Email.fromUnknown("Ada <ada@example.com>");
+ * assertErr(invalid);
+ * assertEqual(invalid.error, {
+ *   type: "Email",
+ *   value: "Ada <ada@example.com>",
+ * });
+ *
+ * const SmtpEmail = maxLength(254)(Email);
+ * assertErr(SmtpEmail.fromUnknown(`${"a".repeat(251)}@b.c`));
+ * ```
+ *
+ * @group String
+ */
+export const Email = /*#__PURE__*/ brand(
+  "Email",
+  String,
+  (value) =>
+    /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/u.test(
+      value,
+    )
+      ? ok()
+      : err<EmailError>({ type: "Email", value }),
+  (error) =>
+    `The value ${safelyStringifyUnknownValue(error.value)} is not a valid email address.`,
+);
+export type Email = typeof Email.Output;
+
 /**
  * Stable valid {@link Name} for tests and internal fixtures.
  *
@@ -7967,6 +8035,134 @@ export const idToIdBytes = (value: Id): IdBytes =>
 export const idBytesToId = (value: IdBytes): Id =>
   uint8ArrayToBase64Url(value) as unknown as Id;
 
+/**
+ * Error returned when a string is not a canonical {@link Uuid}.
+ *
+ * @group String
+ */
+export interface UuidError extends TypeError<"Uuid"> {
+  readonly value: string;
+}
+
+/**
+ * UUID in its canonical lowercase text form, as defined by [RFC
+ * 9562](https://www.rfc-editor.org/rfc/rfc9562).
+ *
+ * Uuid accepts 32 lowercase hexadecimal digits in the 8-4-4-4-12 layout, as
+ * produced by `crypto.randomUUID()`. It accepts every version and variant,
+ * including the Nil and Max UUIDs, so every 128-bit value has exactly one
+ * Uuid.
+ *
+ * RFC 9562 reads UUIDs in any case. Uuid requires lowercase so that equal UUIDs
+ * are equal strings; lowercase text from other sources before validating it.
+ *
+ * Convert a Uuid to an {@link Id} with {@link uuidToId} and back with
+ * {@link idToUuid}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, assertErr, assertOk, Uuid } from "@evolu/common";
+ *
+ * const value = "0190a6f4-8c3e-7b2a-9d41-5e6f7a8b9c0d";
+ * assertOk(Uuid.fromUnknown(value), value);
+ *
+ * const uppercase = value.toUpperCase();
+ * const invalid = Uuid.fromUnknown(uppercase);
+ * assertErr(invalid);
+ * assertEqual(invalid.error, { type: "Uuid", value: uppercase });
+ * assertOk(Uuid.fromUnknown(uppercase.toLowerCase()), value);
+ * ```
+ *
+ * @group String
+ */
+export const Uuid = /*#__PURE__*/ brand(
+  "Uuid",
+  String,
+  (value) =>
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(
+      value,
+    )
+      ? ok()
+      : err<UuidError>({ type: "Uuid", value }),
+  (error) =>
+    `The value ${safelyStringifyUnknownValue(error.value)} is not a canonical lowercase UUID.`,
+);
+export type Uuid = typeof Uuid.Output;
+
+/**
+ * Converts a {@link Uuid} to the {@link Id} with the same 16 bytes.
+ *
+ * Use this to store records whose external keys are UUIDs. Unlike
+ * {@link createIdFromString}, the mapping is reversible with {@link idToUuid}, so
+ * the original UUID does not need its own column. A time-based UUID, such as
+ * version 1, 6, or 7, keeps its creation time in the Id.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   idToUuid,
+ *   Uuid,
+ *   uuidToId,
+ *   type Brand,
+ *   type Id,
+ * } from "@evolu/common";
+ *
+ * const uuid = Uuid.orThrow("0190a6f4-8c3e-7b2a-9d41-5e6f7a8b9c0d");
+ * const todoId = uuidToId<"Todo">(uuid);
+ *
+ * assertEqual(todoId, "AZCm9Iw-eyqdQV5veoucDQ");
+ * assertType<typeof todoId, Id & Brand<"Todo">>();
+ * assertEqual(idToUuid(todoId), uuid);
+ * ```
+ *
+ * @group String
+ */
+export const uuidToId = <B extends string = never>(
+  value: Uuid,
+  ..._validation: IdBrandValidation<B>
+): CreatedId<B> =>
+  idBytesToId(hexToBytes(value.replaceAll("-", "")) as IdBytes) as CreatedId<B>;
+
+/**
+ * Converts an {@link Id} to the {@link Uuid} with the same 16 bytes.
+ *
+ * The result is a Uuid of any version or variant, because Ids created by
+ * {@link createId} are random 128-bit values. Ids created by
+ * {@link createIdAsUuidv7} convert to version 7 UUIDs.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   createIdAsUuidv7,
+ *   createRandomBytes,
+ *   createTime,
+ *   idToUuid,
+ *   uuidToId,
+ * } from "@evolu/common";
+ *
+ * const id = createIdAsUuidv7({
+ *   randomBytes: createRandomBytes(),
+ *   time: createTime(),
+ * });
+ * const uuid = idToUuid(id);
+ *
+ * assertEqual(uuid[14], "7");
+ * assertEqual(uuidToId(uuid), id);
+ * ```
+ *
+ * @group String
+ */
+export const idToUuid = (value: Id): Uuid => {
+  const hex = bytesToHex(idToIdBytes(value));
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}` as Uuid;
+};
+
 /**
  * Error returned when a string is not a canonical {@link Int64String}.
  *

package/src/WebSocket.ts

@@ -7,7 +7,7 @@
 import { assert } from "./Assert.ts";
 import { constTrue } from "./Function.ts";
 import type { Result } from "./Result.ts";
-import { err, ok } from "./Result.ts";
+import { err, ok, trySync } from "./Result.ts";
 import type { Schedule } from "./Schedule.ts";
 import { exponential, jitter, maxDelay } from "./Schedule.ts";
 import type { RetryError, Task } from "./Task.ts";
@@ -266,10 +266,24 @@ export interface WebSocketOptions {
  * @group Errors
  */
 export type WebSocketError =
+  | WebSocketCreateError
   | WebSocketConnectError
   | WebSocketConnectionError
   | RetryError<WebSocketRetryError>;
 
+/**
+ * An error that occurs when the platform's WebSocket constructor throws, for
+ * example for a URL it rejects, a `ws:` URL on an `https:` page, or a Content
+ * Security Policy that blocks the URL. These fail the same way on every
+ * attempt, so the {@link WebSocket} stops connecting. The thrown value is not
+ * always an `Error`.
+ *
+ * @group Errors
+ */
+export interface WebSocketCreateError extends Typed<"WebSocketCreateError"> {
+  readonly error: unknown;
+}
+
 /**
  * An error that occurs when a connection cannot be established due to a network
  * error. Fires before `onclose`.
@@ -344,6 +358,9 @@ const defaultHealthyConnectionDuration = /*#__PURE__*/ durationToMillis("30s");
 /**
  * Create a new {@link WebSocket}.
  *
+ * When the platform's WebSocket constructor throws, `onError` receives a
+ * {@link WebSocketCreateError} and the WebSocket stops connecting.
+ *
  * @group Core
  */
 export const createWebSocket: CreateWebSocket =
@@ -403,10 +420,22 @@ export const createWebSocket: CreateWebSocket =
       closeSocket();
       resolveConnect = resolve;
 
-      socket = new WebSocketConstructor(
-        url,
-        String.is(protocols) ? protocols : protocols && [...protocols],
+      const created = trySync(
+        () =>
+          new WebSocketConstructor(
+            url,
+            String.is(protocols) ? protocols : protocols && [...protocols],
+          ),
       );
+      // A throw that escaped this Task would panic the Run, which in Evolu's
+      // SharedWorker stops sync for every tab.
+      if (!created.ok) {
+        resolveConnect = null;
+        onError?.({ type: "WebSocketCreateError", error: created.error });
+        resolve(ok());
+        return;
+      }
+      socket = created.value;
 
       if (binaryType) socket.binaryType = binaryType;