@evolu/common 8.4.0 → 8.5.0

package/src/Time.ts

@@ -6,6 +6,7 @@
 
 import { assert } from "./Assert.ts";
 import type { Brand } from "./Brand.ts";
+import { exhaustiveCheck } from "./Function.ts";
 import type { yieldNow } from "./Task.ts";
 import {
   brand,
@@ -239,6 +240,10 @@ export const testCreateTime = (options?: {
       case "microtask":
         queueMicrotask(incrementNow);
         break;
+      case undefined:
+        break;
+      default:
+        exhaustiveCheck(autoIncrement);
     }
     return result;
   };
@@ -564,8 +569,10 @@ const durationUnits = {
   m: 60000,
   h: 3600000,
   d: 86400000,
-  w: 604800000, // 7 days
-  y: 31536000000, // 365 days
+  // 7 days
+  w: 604800000,
+  // 365 days
+  y: 31536000000,
 } as const;
 
 /**

package/src/Type.ts

@@ -432,9 +432,10 @@ import { sha256 } from "@noble/hashes/sha2.js";
 import * as bip39 from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english.js";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type {
-  AtLeastTwoReadonlyArray,
-  NonEmptyReadonlyArray,
+import {
+  createMutableArray,
+  type AtLeastTwoReadonlyArray,
+  type NonEmptyReadonlyArray,
 } from "./Array.ts";
 import { assert, assertNonNullable } from "./Assert.ts";
 import type { Brand } from "./Brand.ts";
@@ -1349,9 +1350,8 @@ type ValidateFormatErrorByTypeByLocale<
     ? unknown
     : never;
 
-/* eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style --
-This mapped validation type is cheaper than the equivalent Record. Changes are
-measured by `pnpm bench:type`. */
+// This mapped validation type is cheaper than the equivalent Record. Changes
+// are measured by `pnpm bench:type`.
 type NoNonStringKeys<Value> = {
   readonly [Key in Exclude<keyof Value, string>]: never;
 };
@@ -1891,6 +1891,7 @@ export function createType<
   parent: ValidateParent<ParentType>,
   fromParent: (
     value: ParentType["Output"],
+    // oxlint-disable-next-line typescript/no-unnecessary-type-arguments -- Explicit defaults in recursive Type declarations are benchmarked to avoid extra compiler work.
   ) => Result<ParentType["Output"], never>,
 ): Type<
   Name,
@@ -2179,12 +2180,58 @@ export function transform<
   operations: {
     readonly from: (
       value: ParentType["Output"],
+      // oxlint-disable-next-line typescript/no-unnecessary-type-arguments -- Explicit defaults in recursive Type declarations are benchmarked to avoid extra compiler work.
     ) => Result<OutputType["Input"], never>;
     readonly to: (value: CanonicalInputOf<OutputType>) => ToOutput;
   },
 ): TransformType<ParentType, OutputType, Name, never, ToOutput>;
 
-/** Creates a fallible transformed Type with its own error formatter. */
+/**
+ * Creates a fallible transformed Type with its own error formatter.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   Boolean,
+ *   String,
+ *   err,
+ *   ok,
+ *   transform,
+ *   type Result,
+ *   type TypeError,
+ * } from "@evolu/common";
+ *
+ * interface BooleanFromStringError extends TypeError<"BooleanFromString"> {
+ *   readonly value: string;
+ * }
+ *
+ * const BooleanFromString = transform(
+ *   "BooleanFromString",
+ *   String,
+ *   Boolean,
+ *   {
+ *     from: (value): Result<boolean, BooleanFromStringError> =>
+ *       value === "true"
+ *         ? ok(true)
+ *         : value === "false"
+ *           ? ok(false)
+ *           : err({ type: "BooleanFromString", value }),
+ *     to: (value) => (value ? "true" : "false"),
+ *   },
+ *   () => 'Expected "true" or "false".',
+ * );
+ *
+ * expectOk(BooleanFromString.fromUnknown("true"), true);
+ * expect(BooleanFromString.to(false)).toBe("false");
+ *
+ * const invalid = BooleanFromString.fromUnknown("yes");
+ * expectErr(invalid, { type: "BooleanFromString", value: "yes" });
+ * expect(BooleanFromString.formatError(invalid.error)).toBe(
+ *   'Expected "true" or "false".',
+ * );
+ * ```
+ */
 export function transform<
   Name extends TypeName,
   ParentType extends ConcreteTypeNode,
@@ -2473,7 +2520,7 @@ function getTerminalRuntimeNode<Value>(
 ): RuntimeOperation<Value>;
 function getTerminalRuntimeNode(node: RuntimeTypeNode): RuntimeTypeNode;
 function getTerminalRuntimeNode(node: { readonly parent?: unknown }): unknown {
-  while (node.parent) node = node.parent;
+  while (node.parent != null) node = node.parent;
 
   return node;
 }
@@ -2949,7 +2996,30 @@ export function objectTag<Name extends keyof ObjectTagOutputByName>(
   ObjectTagOutputByName[Name]
 >;
 
-/** Creates an object-tag Type by refining an existing object Type. */
+/**
+ * Creates an object-tag Type by refining an existing object Type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { instanceOf, objectTag } from "@evolu/common";
+ *
+ * class TaggedValue {
+ *   readonly [globalThis.Symbol.toStringTag] = "TaggedValue";
+ * }
+ *
+ * const TaggedValueType = objectTag(
+ *   "TaggedValue",
+ *   instanceOf(TaggedValue),
+ * );
+ * const value = new TaggedValue();
+ * const result = TaggedValueType.fromUnknown(value);
+ *
+ * expectOk(result, value);
+ * expectTypeOf(result.value).toExtend<TaggedValue>();
+ * expect(TaggedValueType.expected).toBe("TaggedValue");
+ * ```
+ */
 export function objectTag<
   Name extends TypeName,
   OutputType extends ConcreteTypeNode & { readonly Output: object },
@@ -4145,6 +4215,7 @@ export interface TemplateLiteralType<
   TypeOfError<"String"> | TemplateLiteralParseError<Parts>,
   never,
   TemplateLiteralStringOutput<Parts>,
+  // oxlint-disable-next-line typescript/no-unnecessary-type-arguments -- TemplateLiteralType explicitly documents every Type invariant, including identity encoding.
   true
 > {
   readonly [templateLiteralSyntaxSymbol]: true;
@@ -4650,6 +4721,7 @@ export function brand<
 >(
   name: ValidateConcreteTypeName<Name>,
   parent: ValidateParent<ParentType>,
+  // oxlint-disable-next-line typescript/no-unnecessary-type-arguments -- Explicit defaults in recursive Type declarations are benchmarked to avoid extra compiler work.
   validate?: (value: ParentType["Output"]) => Result<void, never>,
 ): BrandType<ParentType, Name, never>;
 
@@ -5378,7 +5450,7 @@ export interface RegexError<
  */
 export const UrlSafeString = /*#__PURE__*/ regex(
   "UrlSafeString",
-  /^[A-Za-z0-9_-]+$/,
+  /^[A-Za-z0-9_-]+$/u,
 )(String);
 export type UrlSafeString = typeof UrlSafeString.Output;
 
@@ -5401,7 +5473,7 @@ const uint8ArrayToBase64UrlString = (bytes: Uint8Array): string => {
   ).join("");
   const base64 = globalThis.btoa(binaryString);
 
-  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  return base64.replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
 };
 
 const base64UrlStringToUint8Array = (value: string): Uint8Array => {
@@ -5414,7 +5486,7 @@ const base64UrlStringToUint8Array = (value: string): Uint8Array => {
     return globalThis.Uint8Array.fromBase64(value, base64UrlOptions);
   }
 
-  let base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+  let base64 = value.replaceAll("-", "+").replaceAll("_", "/");
   while (base64.length % 4 !== 0) base64 += "=";
 
   const binaryString = globalThis.atob(base64);
@@ -5756,6 +5828,7 @@ export interface TableId<Table extends TypeName> extends Type<
   TableIdError<Table> | InferErrors<typeof String>,
   ChildCustomFrom<typeof String, Id & Brand<Table>, TableIdError<Table>>,
   CanonicalInputForChild<typeof String, Id & Brand<Table>>,
+  // oxlint-disable-next-line typescript/no-unnecessary-type-arguments -- TableId must track its parent Type's identity encoding instead of hard-coding Type's default.
   IdentityEncodingOf<typeof String>
 > {
   readonly table: Table;
@@ -5877,7 +5950,7 @@ export const Int64String = /*#__PURE__*/ brand(
 
     if (
       value.length > (negative ? 20 : 19) ||
-      !/^(?:0|-?[1-9]\d*)$/.test(value)
+      !/^(?:0|-?[1-9]\d*)$/u.test(value)
     ) {
       return err<Int64StringError>({ type: "Int64String", value });
     }
@@ -6607,7 +6680,7 @@ export const DecimalString = /*#__PURE__*/ brand(
   "DecimalString",
   String,
   (value) =>
-    /^(?:0|-?(?:[1-9]\d*|(?:0|[1-9]\d*)\.\d*[1-9]))$/.test(value)
+    /^(?:0|-?(?:[1-9]\d*|(?:0|[1-9]\d*)\.\d*[1-9]))$/u.test(value)
       ? ok()
       : err<DecimalStringError>({ type: "DecimalString", value }),
   (error) =>
@@ -7494,7 +7567,7 @@ const copyArrayPrefix = (
   value: ReadonlyArray<unknown>,
   endIndex: number,
 ): Array<unknown> => {
-  const output = new Array<unknown>(value.length);
+  const output = createMutableArray<unknown>(value.length);
 
   for (let index = 0; index < endIndex; index++) {
     output[index] = value[index];
@@ -8911,7 +8984,7 @@ export const record = <
     encodeKey === identity && encodeValue === identity
       ? identity
       : (input: Readonly<Record<string, unknown>>) => {
-          const output = createMutableRecord<string, unknown>();
+          const output = createMutableRecord();
           let changed = false;
 
           for (const inputKey of globalThis.Object.keys(input)) {
@@ -9269,7 +9342,7 @@ const validateRecordEntries = (
 > => {
   let issues:
     Array<RecordIssue<TypeError, TypeError, RecordStructuralIssue>> | undefined;
-  const output = createMutableRecord<string, unknown>();
+  const output = createMutableRecord();
   const inputKeyByOutputKey = createMutableRecord<string, string | symbol>();
   let changed = false;
 
@@ -9543,7 +9616,32 @@ export function object<const Props extends ObjectProps>(
     : [ValidationFailure<ObjectValidationError<Props>>]
 ): StrictObjectType<Props>;
 
-/** Creates an Object Type with additional record properties. */
+/**
+ * Creates an Object Type with additional record properties.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { String, object, record } from "@evolu/common";
+ *
+ * const RequestHeaders = object(
+ *   { authorization: String },
+ *   record(String, String),
+ * );
+ * const result = RequestHeaders.fromUnknown({
+ *   authorization: "Bearer token",
+ *   "x-request-id": "request-1",
+ * });
+ *
+ * expectOk(result, {
+ *   authorization: "Bearer token",
+ *   "x-request-id": "request-1",
+ * });
+ * expectTypeOf(result.value["x-request-id"]).toEqualTypeOf<
+ *   string | undefined
+ * >();
+ * ```
+ */
 export function object<
   const Props extends ObjectProps,
   const Rest extends RecordTypeNode & ConcreteTypeNode,
@@ -10831,6 +10929,35 @@ export type UnknownResult = typeof UnknownResult.Output;
  * ### Example
  *
  * ```ts
+ * import { String, discriminatedUnion, typed } from "@evolu/common";
+ *
+ * const Loading = typed("Loading");
+ * const Loaded = typed("Loaded", { value: String });
+ * const State = discriminatedUnion(Loading, Loaded);
+ *
+ * expectOk(State.fromUnknown({ type: "Loading" }), { type: "Loading" });
+ * expectOk(State.fromUnknown({ type: "Loaded", value: "Evolu" }), {
+ *   type: "Loaded",
+ *   value: "Evolu",
+ * });
+ * expect(Loading.is({ type: "Loading", progress: 1 })).toBe(false);
+ * expectTypeOf<typeof Loading.Output>().toExtend<{
+ *   readonly type: "Loading";
+ * }>();
+ * ```
+ *
+ * @group Discriminated unions
+ */
+export function typed<const Tag extends TypeName>(
+  tag: ValidateTypedTag<Tag>,
+): TypedType<Tag>;
+
+/**
+ * Creates a Tagged Object Type with declared properties.
+ *
+ * ### Example
+ *
+ * ```ts
  * import { String, typed } from "@evolu/common";
  *
  * const Pending = typed("Pending", {
@@ -10842,14 +10969,7 @@ export type UnknownResult = typeof UnknownResult.Output;
  *   label: "Waiting",
  * });
  * ```
- *
- * @group Discriminated unions
  */
-export function typed<const Tag extends TypeName>(
-  tag: ValidateTypedTag<Tag>,
-): TypedType<Tag>;
-
-/** Creates a Tagged Object Type with declared properties. */
 export function typed<
   const Tag extends TypeName,
   const Props extends ObjectProps,
@@ -10861,7 +10981,29 @@ export function typed<
     : [ValidationFailure<TypedValidationError<Props>>]
 ): TypedType<Tag, Props>;
 
-/** Creates a Tagged Object Type with additional record properties. */
+/**
+ * Creates a Tagged Object Type with additional record properties.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { String, record, typed } from "@evolu/common";
+ *
+ * const Open = typed("Open", { label: String }, record(String, String));
+ * const result = Open.fromUnknown({
+ *   type: "Open",
+ *   label: "Ready",
+ *   note: "Connected",
+ * });
+ *
+ * expectOk(result, {
+ *   type: "Open",
+ *   label: "Ready",
+ *   note: "Connected",
+ * });
+ * expectTypeOf(result.value.note).toEqualTypeOf<string | undefined>();
+ * ```
+ */
 export function typed<
   const Tag extends TypeName,
   const Props extends ObjectProps,
@@ -11242,19 +11384,19 @@ export function discriminatedUnion(
         return err({
           type: "DiscriminatedUnion",
           reason: { kind: "PropertyAccess", key, reason: "Inherited" },
-        } satisfies DiscriminatedUnionPropertyAccessError<string>);
+        } satisfies DiscriminatedUnionPropertyAccessError);
       }
       discriminator = undefined;
     } else if (!("value" in descriptor)) {
       return err({
         type: "DiscriminatedUnion",
         reason: { kind: "PropertyAccess", key, reason: "Accessor" },
-      } satisfies DiscriminatedUnionPropertyAccessError<string>);
+      } satisfies DiscriminatedUnionPropertyAccessError);
     } else if (!descriptor.enumerable) {
       return err({
         type: "DiscriminatedUnion",
         reason: { kind: "PropertyAccess", key, reason: "NonEnumerable" },
-      } satisfies DiscriminatedUnionPropertyAccessError<string>);
+      } satisfies DiscriminatedUnionPropertyAccessError);
     } else {
       discriminator = descriptor.value;
     }
@@ -12260,6 +12402,7 @@ const validateJsonValue = (
     }
     if (typeof value === "number") {
       if (!globalThis.Number.isFinite(value)) {
+        // oxlint-disable-next-line unicorn/no-lonely-if -- Keep issue construction separate from the finite-number guard.
         if (
           addIssue({
             kind: "NonFiniteNumber",
@@ -12521,6 +12664,7 @@ const stringifyJsonValue = (value: JsonValue): Json => {
       continue;
     }
 
+    // oxlint-disable-next-line typescript/switch-exhaustiveness-check -- JsonValue excludes the additional runtime types reported by tsgolint.
     switch (typeof value) {
       case "string":
         chunks.push(globalThis.JSON.stringify(value));

package/src/WebSocket.ts

@@ -235,9 +235,13 @@ export const createWebSocket: CreateWebSocket =
     const closeSocket = () => {
       if (!socket) return;
 
+      // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
       socket.onopen = null;
+      // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
       socket.onclose = null;
+      // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
       socket.onmessage = null;
+      // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
       socket.onerror = null;
 
       if (
@@ -266,11 +270,13 @@ export const createWebSocket: CreateWebSocket =
 
       let isOpen = false;
 
+      // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
       socket.onopen = () => {
         isOpen = true;
         onOpen?.();
       };
 
+      // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
       socket.onclose = (event) => {
         onClose?.(event);
         if (shouldRetryOnClose(event)) {
@@ -280,10 +286,12 @@ export const createWebSocket: CreateWebSocket =
         }
       };
 
+      // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
       socket.onmessage = (event: MessageEvent<string | ArrayBuffer | Blob>) => {
         onMessage?.(event.data);
       };
 
+      // oxlint-disable-next-line unicorn/prefer-add-event-listener -- This adapter owns and clears one handler.
       socket.onerror = (event) => {
         const error: WebSocketConnectionError | WebSocketConnectError = isOpen
           ? { type: "WebSocketConnectionError", event }

package/src/Worker.ts

@@ -432,7 +432,7 @@ export const createBroadcastChannel: CreateBroadcastChannel = <
         const dispatches = broadcastChannelDispatchesByName.get(name);
         assert(dispatches, "Expected broadcast channel dispatches");
 
-        for (const otherDispatch of [...dispatches]) {
+        for (const otherDispatch of dispatches) {
           if (otherDispatch === dispatch) continue;
 
           scheduleWorkerTask(() => {

package/src/local-first/Db.ts

@@ -924,7 +924,8 @@ const applyMessages =
      */
     updateOwnerUsage(deps)(
       ownerIdBytes,
-      onePositiveInt, // Placeholder until proper tracking implemented
+      // Placeholder until proper tracking implemented
+      onePositiveInt,
       firstTimestamp,
       lastTimestamp,
     );

package/src/local-first/Evolu.ts

@@ -1248,6 +1248,7 @@ export const createEvolu =
       console.info("disposeEvolu");
     });
 
+    // oxlint-disable-next-line react/rules-of-hooks -- useOwner manages sync ownership and is not a React Hook.
     if (isNonEmptyArray(transports)) useOwner(appOwner);
 
     run.signal.throwIfAborted();

package/src/local-first/Owner.ts

@@ -11,15 +11,15 @@
  *
  * Individual changes in an append-only local-first history can only be marked
  * as deleted. An entire owner, however, can be removed from devices and relays
- * together with all of its data. The AppOwner must remain because it coordinates
- * the deletion of other owners across devices.
+ * together with all of its data. The AppOwner must remain because it
+ * coordinates the deletion of other owners across devices.
  *
  * Choose an owner by how its data should live and be shared:
  *
  * - {@link AppOwner} coordinates sync and persists for the lifetime of the app
  *   identity.
- * - {@link ShardOwner} partitions application data so it can be synced and
- *   deleted independently.
+ * - {@link ShardOwner} partitions application data so it can be synced and deleted
+ *   independently.
  * - {@link SharedOwner} grants collaborative read and write access.
  * - {@link SharedReadonlyOwner} grants read-only access to shared data.
  *
@@ -62,8 +62,8 @@ import { TimestampBytes } from "./Timestamp.ts";
 /**
  * {@link Owner} without a {@link OwnerWriteKey}.
  *
- * @see {@link createSharedReadonlyOwner}
  * @group Core
+ * @see {@link createSharedReadonlyOwner}
  */
 export interface ReadonlyOwner {
   readonly id: OwnerId;
@@ -427,9 +427,9 @@ export type OwnerTransport = OwnerWebSocketTransport;
  * Legitimate clients will be properly configured with valid credentials, so
  * automatic retry is OK.
  *
+ * @group Transport
  * @see {@link createOwnerWebSocketTransport}
  * @see {@link parseOwnerIdFromOwnerWebSocketTransportUrl}
- * @group Transport
  */
 export interface OwnerWebSocketTransport extends Typed<"WebSocket"> {
   readonly url: string;
@@ -553,7 +553,8 @@ export interface OwnerUsage {
    *
    * Measures only {@link EncryptedDbChange} data and excludes {@link Storage}
    * implementation overhead such as indexes and skip-list columns. This makes
-   * the measurement consistent across storage implementations and suitable for:
+   * the measurement consistent across storage implementations and suitable
+   * for:
    *
    * - **Predictable measurement** - same data = same byte count across all
    *   instances