@evolu/common 7.2.2 → 7.3.0

package/src/Function.ts

@@ -1,3 +1,6 @@
+import { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.js";
+import { ReadonlyRecord } from "./Object.js";
+
 /**
  * Helper function to ensure exhaustive matching in a switch statement. Throws
  * an error if an unhandled case is encountered.
@@ -31,8 +34,79 @@ export const exhaustiveCheck = (value: never): never => {
   throw new Error(`exhaustiveCheck unhandled case: ${JSON.stringify(value)}`);
 };
 
+/**
+ * Returns the input value unchanged.
+ *
+ * Useful as a default transformation, placeholder callback, or when a function
+ * is required but no transformation is needed.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const values = [1, 2, 3];
+ * const same = values.map(identity); // [1, 2, 3]
+ *
+ * const getTransform = (shouldDouble: boolean) =>
+ *   shouldDouble ? (x: number) => x * 2 : identity;
+ * ```
+ */
 export const identity = <A>(a: A): A => a;
 
+/**
+ * Casts an array, set, record, or map to its readonly counterpart.
+ *
+ * Zero runtime cost — returns the same value with a readonly type. Use this to
+ * enforce immutability at the type level. Preserves {@link NonEmptyArray} as
+ * {@link NonEmptyReadonlyArray}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Array literals become NonEmptyReadonlyArray
+ * const items = readonly([1, 2, 3]);
+ * // Type: NonEmptyReadonlyArray<number>
+ *
+ * // NonEmptyArray is preserved as NonEmptyReadonlyArray
+ * const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
+ * const readonlyNonEmpty = readonly(nonEmpty);
+ * // Type: NonEmptyReadonlyArray<number>
+ *
+ * // Regular arrays become ReadonlyArray
+ * const arr: Array<number> = getNumbers();
+ * const readonlyArr = readonly(arr);
+ * // Type: ReadonlyArray<number>
+ *
+ * // Sets, Records, and Maps
+ * const ids = readonly(new Set(["a", "b"]));
+ * // Type: ReadonlySet<string>
+ *
+ * const users: Record<UserId, string> = { ... };
+ * const readonlyUsers = readonly(users);
+ * // Type: ReadonlyRecord<UserId, string>
+ *
+ * const lookup = readonly(new Map([["key", "value"]]));
+ * // Type: ReadonlyMap<string, string>
+ * ```
+ *
+ * @experimental
+ */
+export function readonly<T>(array: NonEmptyArray<T>): NonEmptyReadonlyArray<T>;
+export function readonly<T>(array: Array<T>): ReadonlyArray<T>;
+export function readonly<T>(set: Set<T>): ReadonlySet<T>;
+export function readonly<K, V>(map: Map<K, V>): ReadonlyMap<K, V>;
+export function readonly<K extends keyof any, V>(
+  record: Record<K, V>,
+): ReadonlyRecord<K, V>;
+export function readonly<T, K extends keyof any, V>(
+  value: Array<T> | Set<T> | Map<K, V> | Record<K, V>,
+):
+  | ReadonlyArray<T>
+  | ReadonlySet<T>
+  | ReadonlyMap<K, V>
+  | ReadonlyRecord<K, V> {
+  return value;
+}
+
 /**
  * A function that delays computation and returns a value of type T.
  *

package/src/Object.ts

@@ -31,7 +31,7 @@ type StringKeyOf<T> = Extract<keyof T, string>;
  *
  * ```ts
  * type UserId = string & { readonly __brand: "UserId" };
- * const users: Record<UserId, string> = {};
+ * const users = createRecord<UserId, string>();
  * const entries = objectToEntries(users); // [UserId, string][]
  * ```
  */
@@ -70,3 +70,42 @@ export const excludeProp = <T extends object, K extends keyof T>(
   const { [prop]: _, ...rest } = obj;
   return rest;
 };
+
+/**
+ * Creates a prototype-less object typed as `Record<K, V>`.
+ *
+ * Use this function when you need a plain record without a prototype chain
+ * (e.g. when keys are controlled by external sources) to avoid prototype
+ * pollution and accidental collisions with properties like `__proto__`.
+ *
+ * Example:
+ *
+ * ```ts
+ * const values = createRecord<string, SqliteValue>();
+ * values["__proto__"] = someValue; // safe, no prototype pollution
+ * ```
+ */
+export const createRecord = <K extends string = string, V = unknown>(): Record<
+  K,
+  V
+> => Object.create(null) as Record<K, V>;
+
+/**
+ * Safely gets a property from a record, returning `undefined` if the key
+ * doesn't exist.
+ *
+ * TypeScript's `Record<K, V>` type assumes all keys exist, but at runtime
+ * accessing a non-existent key returns `undefined`. This helper provides proper
+ * typing for that case without needing a type assertion.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const users: Record<string, User> = { alice: { name: "Alice" } };
+ * const user = getProperty(users, "bob"); // User | undefined
+ * ```
+ */
+export const getProperty = <K extends string, V>(
+  record: ReadonlyRecord<K, V>,
+  key: string,
+): V | undefined => (key in record ? record[key as K] : undefined);

package/src/Order.ts

@@ -94,7 +94,8 @@ export const orderNumber = createOrder<number>((a, b) => a < b);
  */
 export const orderBigInt = createOrder<bigint>((a, b) => a < b);
 
-export const orderUint8Array: Order<globalThis.Uint8Array> = (a, b) => {
+/** An {@link Order} for Uint8Array. */
+export const orderUint8Array: Order<Uint8Array> = (a, b) => {
   if (a.byteLength > b.byteLength) return 1;
   if (a.byteLength < b.byteLength) return -1;
 

package/src/Result.ts

@@ -1,3 +1,5 @@
+import type { Task } from "./Task.js";
+
 /**
  * The problem with throwing an exception in JavaScript is that the caught error
  * is always of an unknown type. The unknown type is a problem because we can't
@@ -82,19 +84,22 @@
  * };
  * ```
  *
+ * For lazy, cancellable async operations, see {@link Task}.
+ *
  * ### Naming convention
  *
- * - For values: `const user = getUser()`
- * - For a single void operation: `const result = foo()`
- * - For multiple void operations: use descriptive names for all
+ * - **For values you need:** use a name without Result suffix (`user`, `config`)
+ * - **For void operations:** use `result` (no value to name)
+ *
+ * For multiple void operations, use block scopes to avoid potentially long
+ * names like `createBaseTablesResult`, `createRelayTablesResult`, or counters
+ * like `result1`, `result2`:
  *
  * ```ts
  * const processUser = () => {
- *   // we have a value
  *   const user = getUser();
  *   if (!user.ok) return user;
  *
- *   // single void operation
  *   const result = saveToDatabase(user.value);
  *   if (!result.ok) return result;
  *
@@ -102,12 +107,15 @@
  * };
  *
  * const setupDatabase = () => {
- *   // multiple void operations - use descriptive names
- *   const baseTables = createBaseTables();
- *   if (!baseTables.ok) return baseTables;
- *
- *   const relayTables = createRelayTables();
- *   if (!relayTables.ok) return relayTables;
+ *   // Multiple void operations - use block scopes to avoid name clash
+ *   {
+ *     const result = createBaseTables();
+ *     if (!result.ok) return result;
+ *   }
+ *   {
+ *     const result = createRelayTables();
+ *     if (!result.ok) return result;
+ *   }
  *
  *   return ok();
  * };
@@ -124,30 +132,31 @@
  * schema, and initializes the database, stopping on the first error:
  *
  * ```ts
- * const resetResult = deps.sqlite.transaction(() => {
- *   const dropAllTablesResult = dropAllTables(deps);
- *   if (!dropAllTablesResult.ok) return dropAllTablesResult;
+ * const result = deps.sqlite.transaction(() => {
+ *   const result = dropAllTables(deps);
+ *   if (!result.ok) return result;
  *
  *   if (message.restore) {
  *     const dbSchema = getDbSchema(deps)();
  *     if (!dbSchema.ok) return dbSchema;
  *
- *     const ensureDbSchemaResult = ensureDbSchema(deps)(
- *       message.restore.dbSchema,
- *       dbSchema.value,
- *     );
- *     if (!ensureDbSchemaResult.ok) return ensureDbSchemaResult;
- *
- *     const initializeDbResult = initializeDb(deps)(
- *       message.restore.mnemonic,
- *     );
- *     if (!initializeDbResult.ok) return initializeDbResult;
+ *     {
+ *       const result = ensureDbSchema(deps)(
+ *         message.restore.dbSchema,
+ *         dbSchema.value,
+ *       );
+ *       if (!result.ok) return result;
+ *     }
+ *     {
+ *       const result = initializeDb(deps)(message.restore.mnemonic);
+ *       if (!result.ok) return result;
+ *     }
  *   }
  *   return ok();
  * });
  *
- * if (!resetResult.ok) {
- *   deps.postMessage({ type: "onError", error: resetResult.error });
+ * if (!result.ok) {
+ *   deps.postMessage({ type: "onError", error: result.error });
  *   return;
  * }
  * ```
@@ -254,13 +263,13 @@
  * ```ts
  * // ✅ Safe to return void - unsafe code is wrapped and error is handled
  * const processData = (data: string): void => {
- *   const parseResult = trySync(
+ *   const result = trySync(
  *     () => JSON.parse(data),
  *     (error) => ({ type: "ParseError", message: String(error) }),
  *   );
  *
- *   if (!parseResult.ok) {
- *     logError(parseResult.error);
+ *   if (!result.ok) {
+ *     logError(result.error);
  *     return;
  *   }
  *

package/src/Sqlite.ts

@@ -2,6 +2,7 @@ import { Brand } from "./Brand.js";
 import { createLruCache } from "./Cache.js";
 import { ConsoleDep } from "./Console.js";
 import { EncryptionKey } from "./Crypto.js";
+import { Eq, eqArrayNumber } from "./Eq.js";
 import { createTransferableError, TransferableError } from "./Error.js";
 import { err, ok, Result, tryAsync, trySync } from "./Result.js";
 import {
@@ -34,8 +35,8 @@ export interface CreateSqliteDriverDep {
 }
 
 export interface SqliteDriverOptions {
-  memory?: boolean;
-  encryptionKey?: EncryptionKey | undefined;
+  readonly memory?: boolean;
+  readonly encryptionKey?: EncryptionKey | undefined;
 }
 
 /**
@@ -75,7 +76,7 @@ export interface SqliteQuery {
 }
 
 /** A type representing a sanitized SQL string. */
-export type SafeSql = string & Brand<"TimestampString">;
+export type SafeSql = string & Brand<"SafeSql">;
 
 /**
  * A value that can be stored in Sqlite.
@@ -86,6 +87,16 @@ export type SafeSql = string & Brand<"TimestampString">;
 export const SqliteValue = union(Null, String, Number, Uint8Array);
 export type SqliteValue = typeof SqliteValue.Type;
 
+export const eqSqliteValue: Eq<SqliteValue> = (x, y) => {
+  if (
+    x instanceof globalThis.Uint8Array &&
+    y instanceof globalThis.Uint8Array
+  ) {
+    return eqArrayNumber(x, y);
+  }
+  return x === y;
+};
+
 export interface SqliteQueryOptions {
   /**
    * If set to `true`, logs the time taken to execute the SQL query. Useful for
@@ -292,13 +303,13 @@ export const createPreparedStatementsCache = <P>(
 };
 
 export interface SqlIdentifier {
-  type: "SqlIdentifier";
-  sql: SafeSql;
+  readonly type: "SqlIdentifier";
+  readonly sql: SafeSql;
 }
 
 export interface RawSql {
-  type: "RawSql";
-  sql: string;
+  readonly type: "RawSql";
+  readonly sql: string;
 }
 
 export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;

package/src/Task.ts

@@ -570,10 +570,12 @@ export const retry = <T, E>(
       }
 
       // Wait before retry
-      const delayResult = await wait(NonNegativeInt.orThrow(delay))(context);
-      if (!delayResult.ok) {
-        // If delay was aborted, return AbortError (will be handled by toTask)
-        return delayResult;
+      {
+        const result = await wait(NonNegativeInt.orThrow(delay))(context);
+        if (!result.ok) {
+          // If delay was aborted, return AbortError (will be handled by toTask)
+          return result;
+        }
       }
     }
   });

package/src/Type.ts

@@ -207,7 +207,7 @@ import * as bip39 from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english.js";
 import { pack } from "msgpackr";
 import type { Brand } from "./Brand.js";
-import { type RandomBytesDep } from "./Crypto.js";
+import type { RandomBytesDep } from "./Crypto.js";
 import { isPlainObject } from "./Object.js";
 import { hasNodeBuffer } from "./Platform.js";
 import { err, getOrNull, getOrThrow, ok, Result, trySync } from "./Result.js";
@@ -2391,6 +2391,124 @@ export const formatArrayError = <Error extends TypeError>(
     }
   });
 
+/**
+ * Set of a specific {@link Type}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const NumberSet = set(Number);
+ *
+ * const result1 = NumberSet.from(new Set([1, 2, 3])); // ok(Set { 1, 2, 3 })
+ * const result2 = NumberSet.from(new Set(["a", "b"])); // err(...)
+ * ```
+ *
+ * @category Base Factories
+ */
+export const set = <ElementType extends AnyType>(
+  element: ElementType,
+): SetType<ElementType> => {
+  const fromUnknown = (
+    value: unknown,
+  ): Result<
+    ReadonlySet<InferType<ElementType>>,
+    SetError<InferErrors<ElementType>>
+  > => {
+    if (!(value instanceof globalThis.Set)) {
+      return err<SetError<InferErrors<ElementType>>>({
+        type: "Set",
+        value,
+        reason: { kind: "NotSet" },
+      });
+    }
+
+    let index = 0;
+    for (const item of value) {
+      const elementResult = element.fromUnknown(item);
+      if (!elementResult.ok) {
+        return err<SetError<InferErrors<ElementType>>>({
+          type: "Set",
+          value,
+          reason: {
+            kind: "Element",
+            index,
+            error: elementResult.error as InferErrors<ElementType>,
+          },
+        });
+      }
+      index++;
+    }
+
+    return ok(value as ReadonlySet<InferType<ElementType>>);
+  };
+
+  const fromParent = (
+    value: ReadonlySet<InferParent<ElementType>>,
+  ): Result<
+    ReadonlySet<InferType<ElementType>>,
+    SetError<InferError<ElementType>>
+  > => {
+    let index = 0;
+    for (const item of value) {
+      const elementResult = element.fromParent(item);
+      if (!elementResult.ok) {
+        return err({
+          type: "Set",
+          value,
+          reason: {
+            kind: "Element",
+            index,
+            error: elementResult.error as InferError<ElementType>,
+          },
+        });
+      }
+      index++;
+    }
+    return ok(value as ReadonlySet<InferType<ElementType>>);
+  };
+
+  return {
+    ...createType("Set", { fromUnknown, fromParent }),
+    element,
+  };
+};
+
+/** SetType extends Type with an additional `element` property for reflection. */
+export interface SetType<ElementType extends AnyType>
+  extends Type<
+    "Set",
+    ReadonlySet<InferType<ElementType>>,
+    ReadonlySet<InferInput<ElementType>>,
+    SetError<InferError<ElementType>>,
+    ReadonlySet<InferParent<ElementType>>,
+    SetError<InferParentError<ElementType>>
+  > {
+  readonly element: ElementType;
+}
+
+export interface SetError<Error extends TypeError = TypeError>
+  extends TypeErrorWithReason<
+    "Set",
+    | { readonly kind: "NotSet" }
+    | {
+        readonly kind: "Element";
+        readonly index: number;
+        readonly error: Error;
+      }
+  > {}
+
+export const formatSetError = <Error extends TypeError>(
+  formatTypeError: TypeErrorFormatter<Error>,
+): TypeErrorFormatter<SetError<Error>> =>
+  createTypeErrorFormatter((error) => {
+    switch (error.reason.kind) {
+      case "NotSet":
+        return `Expected a Set but received ${error.value}.`;
+      case "Element":
+        return `Invalid element at index ${error.reason.index}: ${formatTypeError(error.reason.error)}`;
+    }
+  });
+
 /**
  * Record of a key {@link Type} and value {@link Type}.
  *
@@ -3970,6 +4088,7 @@ export type TypeErrors<ExtraErrors extends TypeError = never> =
   | ExtraErrors
   // Composite errors
   | ArrayError<TypeErrors<ExtraErrors>>
+  | SetError<TypeErrors<ExtraErrors>>
   | RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>>
   | ObjectError<Record<string, TypeErrors<ExtraErrors>>>
   | ObjectWithRecordError<
@@ -4154,6 +4273,8 @@ export const createFormatTypeError = <ExtraErrors extends TypeError = never>(
         return formatSimplePasswordError(formatTypeError)(error);
       case "Array":
         return formatArrayError(formatTypeError)(error);
+      case "Set":
+        return formatSetError(formatTypeError)(error);
       case "Record":
         return formatRecordError(formatTypeError)(error);
       case "Object":
@@ -4202,6 +4323,18 @@ export const typeErrorToStandardSchemaIssues = <
     );
   }
 
+  if (error.type === "Set") {
+    const setError = error as SetError;
+    if (setError.reason.kind === "NotSet") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    return typeErrorToStandardSchemaIssues(
+      setError.reason.error as TypeErrors<ExtraErrors>,
+      formatTypeError,
+      [...path, setError.reason.index],
+    );
+  }
+
   if (error.type === "Object") {
     const objectError = error as ObjectError;
     if (