@evolu/common 6.0.1-preview.9 → 7.1.0

package/src/Result.ts

@@ -1,36 +1,17 @@
 /**
- * 🛡️ Type-safe errors
- *
- * ## Intro
- *
  * 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
  * be sure all errors have been handled because the TypeScript compiler can't
- * help us.
- *
- * Some other languages like Rust 🦀 or Haskell 📚 use a type-safe approach to
- * error handling, where errors are explicitly represented as part of the return
- * type, such as Result or Either, allowing the developer to handle all errors
- * safely. ✅
- *
- * ✨ Evolu uses {@link Result}, and it looks like this:
- *
- * ```ts
- * type Result<T, E> = Ok<T> | Err<E>;
+ * tell us.
  *
- * interface Ok<T> {
- *   readonly ok: true;
- *   readonly value: T;
- * }
- *
- * interface Err<E> {
- *   readonly ok: false;
- *   readonly error: E;
- * }
+ * Languages like Rust or Haskell use a type-safe approach to error handling,
+ * where errors are explicitly represented as part of the return type, such as
+ * Result or Either, allowing the developer to handle errors safely. TypeScript
+ * can have this too via the `Result` type.
  *
- * const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
- * const err = <E>(error: E): Err<E> => ({ ok: false, error });
- * ```
+ * The `Result` type can be either {@link Ok} (success) or {@link Err} (error).
+ * Use {@link ok} to create a successful result and {@link err} to create an error
+ * result.
  *
  * Now let's look at how `Result` can be used for safe JSON parsing:
  *
@@ -77,12 +58,10 @@
  *
  * Let's summarize it:
  *
- * - For synchronous safe code, use `ok` and `err`.
+ * - For safe code, use `ok` and `err`.
  * - For unsafe code, use `trySync` or `tryAsync`.
- * - For asynchronous safe code, use `Promise` with {@link Result}.
  *
- * Asynchronous safe (because of a Promise using Result) code is
- * straightforward:
+ * Safe asynchronous code (using Result with a Promise):
  *
  * ```ts
  * const fetchUser = async (
@@ -103,9 +82,40 @@
  * };
  * ```
  *
- * ## Examples
+ * ### Naming convention
  *
- * ### Sequential Operations with Short-Circuiting
+ * - For values: `const user = getUser()`
+ * - For a single void operation: `const result = foo()`
+ * - For multiple void operations: use descriptive names for all
+ *
+ * ```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;
+ *
+ *   return ok();
+ * };
+ *
+ * const setupDatabase = () => {
+ *   // multiple void operations - use descriptive names
+ *   const baseTables = createBaseTables();
+ *   if (!baseTables.ok) return baseTables;
+ *
+ *   const relayTables = createRelayTables();
+ *   if (!relayTables.ok) return relayTables;
+ *
+ *   return ok();
+ * };
+ * ```
+ *
+ * ### Examples
+ *
+ * #### Sequential operations with short-circuiting
  *
  * When performing a sequence of operations where any failure should stop
  * further processing, use the `Result` type with early returns.
@@ -155,37 +165,127 @@
  * This approach ensures type-safe error handling, avoids nested try/catch
  * blocks, and clearly communicates the control flow.
  *
- * ### A function with two different errors:
+ * #### A function with two different errors:
  *
  * ```ts
  * const example = (value: string): Result<number, FooError | BarError> => {
  *   const foo = getFoo(value);
  *   if (!foo.ok) return foo;
  *
- *   const bar = barize(foo.value);
+ *   const bar = getBar(foo.value);
  *   if (!bar.ok) return bar;
  *
  *   return ok(barToNumber(bar.value));
  * };
  * ```
  *
- * ## FAQ
+ * ### Handling unexpected errors
+ *
+ * Even with disciplined use of `trySync` and `tryAsync`, unexpected errors can
+ * still occur due to programming mistakes, third-party library bugs, or edge
+ * cases. These should be logged for debugging, but **unexpected errors are not
+ * recoverable** - they represent bugs that must be fixed.
+ *
+ * **Important**: "Graceful shutdown" and error recovery can only come from
+ * expected errors handled via the `Result` type. Unexpected errors should fail
+ * fast - the operation fails immediately and the error bubbles up.
+ *
+ * #### In browser environments
+ *
+ * ```ts
+ * // Global error handler for unexpected errors
+ * window.addEventListener("error", (event) => {
+ *   console.error("Uncaught error:", event.error);
+ *   // Send to error reporting service
+ *   errorReportingService.report(event.error);
+ * });
+ *
+ * // For unhandled promise rejections
+ * window.addEventListener("unhandledrejection", (event) => {
+ *   console.error("Unhandled promise rejection:", event.reason);
+ *   errorReportingService.report(event.reason);
+ * });
+ * ```
+ *
+ * #### In Node.js environments
+ *
+ * ```ts
+ * // Handle uncaught exceptions - log and fail fast
+ * process.on("uncaughtException", (error) => {
+ *   console.error("Uncaught exception:", error);
+ *   errorReportingService.report(error);
+ *   // Exit immediately - unexpected errors are not recoverable
+ *   process.exit(1);
+ * });
+ *
+ * // Handle unhandled promise rejections
+ * process.on("unhandledRejection", (reason) => {
+ *   console.error("Unhandled promise rejection:", reason);
+ *   errorReportingService.report(reason);
+ * });
+ * ```
+ *
+ * These global handlers serve as a safety net to log and report unexpected
+ * errors for debugging purposes. They do not attempt recovery - unexpected
+ * errors represent bugs that must be fixed. The discipline of explicit error
+ * handling through the `Result` pattern remains the primary approach for all
+ * recoverable scenarios.
+ *
+ * ### FAQ
+ *
+ * #### When should a function return a plain value instead of `Result<T, E>`?
  *
- * ### What if my function doesn't return a value on success?
+ * Use `Result<T, E>` only when a function can fail with **known, expected
+ * errors** that callers need to handle. If a function cannot fail with a known
+ * error, return the value directly.
+ *
+ * - ✅ Return `Result<User, UserNotFoundError>` - can fail with a known error
+ * - ✅ Return `User` - cannot fail with a known error
+ * - ❌ Don't return `Result<User, never>` - unnecessary wrapper
+ *
+ * This keeps the codebase clean and makes error handling intentional. The type
+ * system communicates which operations can fail and which cannot.
+ *
+ * Unsafe code from external libraries (not under our control) should be wrapped
+ * with `trySync` or `tryAsync` at the boundaries. Once wrapped, if the error is
+ * not important to callers, functions can safely return plain values. If the
+ * error matters, use `Result` with a typed error.
+ *
+ * ```ts
+ * // ✅ Safe to return void - unsafe code is wrapped and error is handled
+ * const processData = (data: string): void => {
+ *   const parseResult = trySync(
+ *     () => JSON.parse(data),
+ *     (error) => ({ type: "ParseError", message: String(error) }),
+ *   );
+ *
+ *   if (!parseResult.ok) {
+ *     logError(parseResult.error);
+ *     return;
+ *   }
+ *
+ *   // Continue with safe operations...
+ * };
+ *
+ * // ✅ Can call without try-catch since it returns void
+ * processData(jsonString);
+ * ```
+ *
+ * #### What if my function doesn't return a value on success?
  *
  * If your function performs an operation but doesn't need to return a value on
  * success, you can use `Result<void, E>`. Using `Result<void, E>` is clearer
  * than using `Result<true, E>` or `Result<null, E>` because it communicates
  * that the function doesn't produce a value but can produce errors.
  *
- * ### How do I short-circuit processing of an array on the first error?
+ * #### How do I short-circuit processing of an array on the first error?
  *
  * If you want to stop processing as soon as an error occurs (short-circuit),
  * you should produce and check each `Result` inside a loop:
  *
  * ```ts
  * for (const query of [
- *   sql`drop table evolu_owner;`,
+ *   sql`drop table evolu_config;`,
  *   sql`drop table evolu_message;`,
  * ]) {
  *   const result = deps.sqlite.exec(query);
@@ -194,12 +294,11 @@
  * // All queries succeeded
  * ```
  *
- * ### How do I handle an array of operations and short-circuit on the first error?
+ * #### How do I handle an array of operations and short-circuit on the first error?
  *
  * If you have an array of operations (not results), you should make them
- * _lazy_—that is, represent each operation as a function (see `LazyValue` in
- * `Function.ts`). This way, you only execute each operation as needed, and can
- * stop on the first error:
+ * _lazy_—that is, represent each operation as a function. This way, you only
+ * execute each operation as needed, and can stop on the first error:
  *
  * ```ts
  * import type { LazyValue } from "./Function";
@@ -232,17 +331,7 @@
  * above) over monadic helpers. Imperative code is generally more readable,
  * easier to debug, and more familiar to most JavaScript and TypeScript
  * developers. While monads and functional helpers can be powerful, they often
- * obscure control flow and make debugging harder. Evolu's approach keeps error
- * handling explicit and straightforward.
- *
- * @module
- */
-
-/**
- * A `Result` can be either {@link Ok} (success) or {@link Err} (error).
- *
- * Use {@link ok} to create a successful result and {@link err} to create an error
- * result.
+ * obscure control flow and make debugging harder.
  */
 export type Result<T, E> = Ok<T> | Err<E>;
 
@@ -256,16 +345,16 @@ export interface Ok<T> {
  * An error {@link Result}.
  *
  * The `error` property can be any type that describes the error. For normal
- * business logic, use a plain object. This allows us to structure errors with
+ * domain logic, use a plain object. This allows us to structure errors with
  * custom fields (e.g., `{ type: "MyError", code: 123 }`). Messages for users
  * belong to translations, not to error objects.
  *
- * If you need a stacktrace for debugging, use an `Error` instance or a custom
+ * If you need a stack trace for debugging, use an `Error` instance or a custom
  * error class to include additional metadata.
  *
  * ### Examples
  *
- * #### Business Logic Error (Plain Object, Recommended)
+ * #### Domain logic error (plain object, recommended)
  *
  * ```ts
  * const failure = err({
@@ -275,13 +364,13 @@ export interface Ok<T> {
  * });
  * ```
  *
- * #### Debugging with Stack Trace (Error Instance)
+ * #### Debugging with stack trace (error instance)
  *
  * ```ts
  * const failure = err(new Error("Something went wrong"));
  * ```
  *
- * #### Custom Error Class
+ * #### Custom error class
  *
  * ```ts
  * class MyCustomError extends Error {
@@ -301,6 +390,22 @@ export interface Err<E> {
   readonly error: E;
 }
 
+/**
+ * Extracts the value type from a {@link Result}.
+ *
+ * @category Utilities
+ */
+export type InferOk<R extends Result<any, any>> =
+  R extends Ok<infer T> ? T : never;
+
+/**
+ * Extracts the error type from a {@link Result}.
+ *
+ * @category Utilities
+ */
+export type InferErr<R extends Result<any, any>> =
+  R extends Err<infer E> ? E : never;
+
 /**
  * Creates an {@link Ok} result.
  *
@@ -355,15 +460,42 @@ export const err = <E>(error: E): Err<E> => ({ ok: false, error });
  * const config = getOrThrow(loadConfig());
  * // Safe to use config here
  * ```
+ *
+ * Throws: `Error` with the original error attached as `cause`.
  */
 export const getOrThrow = <T, E>(result: Result<T, E>): T => {
   if (result.ok) {
     return result.value;
   } else {
-    throw new Error(`Result error: ${JSON.stringify(result.error)}`);
+    throw new Error("getOrThrow", { cause: result.error });
   }
 };
 
+/**
+ * Extracts the value from a {@link Result} if it is an `Ok`, or returns `null`
+ * if it is an `Err`.
+ *
+ * **Intended usage:**
+ *
+ * - When you need to convert a `Result` to a nullable value for APIs that expect
+ *   `T | null`.
+ * - When the error is not important and you just want the value or nothing.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const parseResult = parseJson('{"key": "value"}');
+ * const value = getOrNull(parseResult);
+ * // value is unknown | null
+ *
+ * if (value != null) {
+ *   console.log("Parsed value:", value);
+ * }
+ * ```
+ */
+export const getOrNull = <T, E>(result: Result<T, E>): T | null =>
+  result.ok ? result.value : null;
+
 /**
  * Wraps synchronous functions that may throw exceptions, returning a
  * {@link Result}.
@@ -384,7 +516,10 @@ export const getOrThrow = <T, E>(result: Result<T, E>): T => {
  * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
  *   trySync(
  *     () => JSON.parse(value) as unknown,
- *     (error) => ({ type: "ParseJsonError", message: String(error) }),
+ *     (error): ParseJsonError => ({
+ *       type: "ParseJsonError",
+ *       message: String(error),
+ *     }),
  *   );
  * ```
  */

package/src/Skiplist.ts

@@ -25,7 +25,7 @@ export const createSkiplistLevel =
         while (deps.random.next() <= probability && level < maxLevel) {
           level += 1;
         }
-        return level as PositiveInt;
+        return PositiveInt.orThrow(level);
       },
     };
   };

package/src/Sqlite.ts

@@ -1,17 +1,19 @@
+import { Brand } from "./Brand.js";
+import { createLruCache } from "./Cache.js";
 import { ConsoleDep } from "./Console.js";
+import { EncryptionKey } from "./Crypto.js";
 import { createTransferableError, TransferableError } from "./Error.js";
 import { err, ok, Result, tryAsync, trySync } from "./Result.js";
 import {
-  Boolean,
   Null,
   Number,
+  PositiveInt,
   SimpleName,
   String,
-  transform,
   Uint8Array,
   union,
 } from "./Type.js";
-import { Brand, Predicate, IntentionalNever } from "./Types.js";
+import { IntentionalNever, Predicate } from "./Types.js";
 
 /**
  * SQLite driver interface. This is the minimal interface that platform-specific
@@ -33,6 +35,7 @@ export interface CreateSqliteDriverDep {
 
 export interface SqliteDriverOptions {
   memory?: boolean;
+  encryptionKey?: EncryptionKey | undefined;
 }
 
 /**
@@ -148,13 +151,13 @@ export const createSqlite =
         exec: (query) =>
           trySync(
             () => {
-              deps.console?.log("[sql]", query);
+              deps.console?.log("[sql]", { query });
 
               const result = maybeLogSqliteQueryExecutionTime(query, () =>
                 driver.exec(query, isSqlMutation(query.sql)),
               );
 
-              deps.console?.log("[sql]", result);
+              deps.console?.log("[sql]", { result });
 
               return result as IntentionalNever;
             },
@@ -300,7 +303,44 @@ export interface RawSql {
 
 export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
 
-/** TODO: Docs. */
+/**
+ * Creates a safe SQL query using a tagged template literal.
+ *
+ * Parameters are automatically escaped and bound as SQLite values. Use
+ * `sql.identifier` for column/table names and `sql.raw` for unescaped SQL.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const id = 42;
+ * const name = "Alice";
+ *
+ * const result = sqlite.exec(sql`
+ *   select *
+ *   from users
+ *   where id = ${id} and name = ${name};
+ * `);
+ *
+ * // For identifiers
+ * const tableName = "users";
+ * sqlite.exec(sql`
+ *   create table ${sql.identifier(tableName)} (
+ *     "id" text primary key,
+ *     "name" text not null
+ *   );
+ * `);
+ *
+ * // For raw SQL (use with caution)
+ * const orderBy = "created_at desc";
+ * sqlite.exec(sql`select * from users order by ${sql.raw(orderBy)};`);
+ * ```
+ *
+ * ### TIP
+ *
+ * Use `prettier-plugin-sql-cst` for SQL formatting. Like Prettier for
+ * JavaScript, this plugin formats SQL expressions differently depending on
+ * their length.
+ */
 export const sql = (
   strings: TemplateStringsArray,
   ...parameters: Array<SqlTemplateParam>
@@ -348,6 +388,29 @@ sql.prepared = (
   return { ...query, options: { prepare: true } };
 };
 
+/**
+ * Checks if a SQL string contains mutation keywords (insert, update, delete,
+ * etc.). Results are cached for performance.
+ */
+export const isSqlMutation: Predicate<string> = (sql) => {
+  /**
+   * Without cache, "insert 1_000_000" Storage test dropped from 57742
+   * inserts/sec to 34k. Regex we used was fast, but CodeQL flagged it as a
+   * potential ReDoS vulnerability, so manual comment removal was the only
+   * option. LRU cache restores performance.
+   */
+  const cached = isSqlMutationCache.get(sql);
+  if (cached !== undefined) return cached;
+
+  const result = isSqlMutationRegEx.test(removeSqlComments(sql));
+  isSqlMutationCache.set(sql, result);
+  return result;
+};
+
+const isSqlMutationCache = createLruCache<string, boolean>(
+  PositiveInt.orThrow(10_000),
+);
+
 const isSqlMutationRegEx = new RegExp(
   `\\b(${[
     "alter",
@@ -366,8 +429,38 @@ const isSqlMutationRegEx = new RegExp(
   "i",
 );
 
-export const isSqlMutation: Predicate<string> = (sql) =>
-  isSqlMutationRegEx.test(sql.replace(/--.*$/gm, ""));
+/**
+ * Removes SQL line comments (--) from a SQL string without using regex to avoid
+ * ReDoS vulnerabilities.
+ */
+const removeSqlComments = (sql: string): string => {
+  // Fast path: if there are no comments, return the original string
+  if (!sql.includes("--")) return sql;
+
+  let result = "";
+  let i = 0;
+
+  while (i < sql.length) {
+    // Check for comment start
+    if (i < sql.length - 1 && sql[i] === "-" && sql[i + 1] === "-") {
+      // Skip until end of line or end of string
+      i += 2;
+      while (i < sql.length && sql[i] !== "\n") {
+        i++;
+      }
+      // Keep the newline if present
+      if (i < sql.length && sql[i] === "\n") {
+        result += "\n";
+        i++;
+      }
+    } else {
+      result += sql[i];
+      i++;
+    }
+  }
+
+  return result;
+};
 
 export interface SqliteQueryPlanRow {
   id: number;
@@ -385,13 +478,14 @@ export const explainSqliteQueryPlan =
     if (!result.ok) return result;
 
     // eslint-disable-next-line no-console
-    console.log("ExplainQueryPlan", query);
+    console.log("[explainSqliteQueryPlan]", query);
     // eslint-disable-next-line no-console
     console.log(
       drawSqliteQueryPlan(
         result.value.rows as unknown as Array<SqliteQueryPlanRow>,
       ),
     );
+
     return ok();
   };
 
@@ -415,15 +509,56 @@ const drawSqliteQueryPlan = (rows: Array<SqliteQueryPlanRow>): string =>
 
 /**
  * SQLite represents boolean values using `0` (false) and `1` (true) instead of
- * a dedicated boolean type. This transform Type ensures that values conform to
- * SQLite's boolean representation.
+ * a dedicated boolean type.
  *
  * See: https://www.sqlite.org/quirks.html#no_separate_boolean_datatype
+ *
+ * ### Tips
+ *
+ * - Use {@link sqliteTrue} and {@link sqliteFalse} constants for better
+ *   readability.
+ * - Use {@link booleanToSqliteBoolean} and {@link sqliteBooleanToBoolean} for
+ *   converting between JavaScript booleans and SQLite boolean values.
  */
-export const SqliteBoolean = transform(
-  Boolean,
-  union(0, 1),
-  (value) => ok(value ? (1 as const) : (0 as const)),
-  (value) => value === 1,
-);
+export const SqliteBoolean = union(0, 1);
 export type SqliteBoolean = typeof SqliteBoolean.Type;
+
+/**
+ * Represents the {@link SqliteBoolean} value for `true`.
+ *
+ * See {@link SqliteBoolean}.
+ */
+export const sqliteTrue = 1;
+
+/**
+ * Represents the {@link SqliteBoolean} value for `false`.
+ *
+ * See {@link SqliteBoolean}.
+ */
+export const sqliteFalse = 0;
+
+/**
+ * Converts a JavaScript boolean to a {@link SqliteBoolean}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isActive = true;
+ * const sqlValue = booleanToSqliteBoolean(isActive); // Returns 1
+ * ```
+ */
+export const booleanToSqliteBoolean = (value: boolean): SqliteBoolean =>
+  value ? sqliteTrue : sqliteFalse;
+
+/**
+ * Converts a {@link SqliteBoolean} to a JavaScript boolean.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const sqlValue: SqliteBoolean = 1;
+ * const bool = sqliteBooleanToBoolean(sqlValue); // Returns true
+ * ```
+ */
+export const sqliteBooleanToBoolean = (value: SqliteBoolean): boolean =>
+  value === sqliteTrue;

package/src/Store.ts

@@ -1,8 +1,3 @@
-/**
- * A mutable reference for managing state with change notifications
- *
- * @module
- */
 import { Eq, eqStrict } from "./Eq.js";
 import { Ref } from "./Ref.js";