@evolu/common 6.0.1-preview.9 → 7.0.0

package/dist/src/Result.js

@@ -1,242 +1,3 @@
-/**
- * 🛡️ 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>;
- *
- * interface Ok<T> {
- *   readonly ok: true;
- *   readonly value: T;
- * }
- *
- * interface Err<E> {
- *   readonly ok: false;
- *   readonly error: E;
- * }
- *
- * const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
- * const err = <E>(error: E): Err<E> => ({ ok: false, error });
- * ```
- *
- * Now let's look at how `Result` can be used for safe JSON parsing:
- *
- * ```ts
- * interface ParseJsonError {
- *   readonly type: "ParseJsonError";
- *   readonly message: string;
- * }
- *
- * const parseJson = (value: string): Result<unknown, ParseJsonError> => {
- *   try {
- *     return ok(JSON.parse(value));
- *   } catch (error) {
- *     return err({ type: "ParseJsonError", message: String(error) });
- *   }
- * };
- *
- * // Result<unknown, ParseJsonError>
- * const json = parseJson('{"key": "value"}');
- *
- * // Fail fast to handle errors early.
- * if (!json.ok) return json; // Err<ParseJsonError>
- *
- * // Now, we have access to the json.value.
- * expectTypeOf(json.value).toBeUnknown();
- * ```
- *
- * Note how we didn't have to use the try/catch, just `if (!json.ok)`, and how
- * the error isn't unknown but has a type.
- *
- * But we had to use `try/catch` in the `parseJson` function. For such a case,
- * wrapping unsafe code, Evolu provides the {@link trySync} helper:
- *
- * ```ts
- * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
- *   trySync(
- *     () => JSON.parse(value) as unknown,
- *     (error) => ({ type: "ParseJsonError", message: String(error) }),
- *   );
- * ```
- *
- * ✨ {@link trySync} helper makes unsafe (can throw) synchronous code safe; for
- * unsafe asynchronous code, use {@link tryAsync}.
- *
- * Let's summarize it:
- *
- * - For synchronous 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:
- *
- * ```ts
- * const fetchUser = async (
- *   userId: string,
- * ): Promise<Result<User, FetchUserError>> => {
- *   // Simulate an API call
- *   return new Promise((resolve) => {
- *     setTimeout(() => {
- *       if (userId === "1") {
- *         resolve(ok({ id: "1", name: "Alice" }));
- *       } else {
- *         resolve(
- *           err({ type: "FetchUserError", reason: "user not found" }),
- *         );
- *       }
- *     }, 1000);
- *   });
- * };
- * ```
- *
- * ## 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.
- *
- * Here's an example of a database reset operation that drops tables, restores a
- * 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;
- *
- *   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;
- *   }
- *   return ok();
- * });
- *
- * if (!resetResult.ok) {
- *   deps.postMessage({ type: "onError", error: resetResult.error });
- *   return;
- * }
- * ```
- *
- * In this pattern:
- *
- * - Each operation returns a `Result` (e.g., `Result<void, E>` or `Result<T,
- *   E>`).
- * - After each operation, check `if (!result.ok)` and return the `Err` to
- *   short-circuit.
- * - If all operations succeed, return `ok()` (or another value if needed).
- * - Outside the transaction, handle the final `Result` to report success or
- *   failure.
- *
- * This approach ensures type-safe error handling, avoids nested try/catch
- * blocks, and clearly communicates the control flow.
- *
- * ### 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);
- *   if (!bar.ok) return bar;
- *
- *   return ok(barToNumber(bar.value));
- * };
- * ```
- *
- * ## FAQ
- *
- * ### 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?
- *
- * 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_message;`,
- * ]) {
- *   const result = deps.sqlite.exec(query);
- *   if (!result.ok) return result;
- * }
- * // All queries succeeded
- * ```
- *
- * ### 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:
- *
- * ```ts
- * import type { LazyValue } from "./Function";
- *
- * const operations: LazyValue<Result<void, MyError>>[] = [
- *   () => doSomething(),
- *   () => doSomethingElse(),
- * ];
- *
- * for (const op of operations) {
- *   const result = op();
- *   if (!result.ok) return result;
- * }
- * // All operations succeeded
- * ```
- *
- * If you already have an array of `Result`s, the processing has already
- * happened, so you can't short-circuit. In that case, you can check for the
- * first error:
- *
- * ```ts
- * const firstError = results.find((r) => !r.ok);
- * if (firstError) return firstError;
- * // All results are Ok
- * ```
- *
- * ### Why doesn't Evolu provide "handy helpers"?
- *
- * Evolu intentionally favors imperative patterns (like the `for...of` loop
- * 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
- */
 export function ok(value = undefined) {
     return { ok: true, value: value };
 }
@@ -269,15 +30,40 @@ export const err = (error) => ({ ok: false, error });
  * const config = getOrThrow(loadConfig());
  * // Safe to use config here
  * ```
+ *
+ * Throws: `Error` with the original error attached as `cause`.
  */
 export const getOrThrow = (result) => {
     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 = (result) => result.ok ? result.value : null;
 /**
  * Wraps synchronous functions that may throw exceptions, returning a
  * {@link Result}.
@@ -298,7 +84,10 @@ export const getOrThrow = (result) => {
  * 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/dist/src/Skiplist.js

@@ -1,3 +1,4 @@
+import { PositiveInt } from "./Type.js";
 // TODO: Use in Storage.
 export const createSkiplistLevel = (deps) => (config = {}) => {
     const { probability = 0.5, maxLevel = 32 } = config;
@@ -7,7 +8,7 @@ export const createSkiplistLevel = (deps) => (config = {}) => {
             while (deps.random.next() <= probability && level < maxLevel) {
                 level += 1;
             }
-            return level;
+            return PositiveInt.orThrow(level);
         },
     };
 };

package/dist/src/Sqlite.d.ts

@@ -1,8 +1,10 @@
+import { Brand } from "./Brand.js";
 import { ConsoleDep } from "./Console.js";
+import { EncryptionKey } from "./Crypto.js";
 import { TransferableError } from "./Error.js";
 import { Result } from "./Result.js";
 import { SimpleName } from "./Type.js";
-import { Brand, Predicate } from "./Types.js";
+import { Predicate } from "./Types.js";
 /**
  * SQLite driver interface. This is the minimal interface that platform-specific
  * drivers must implement.
@@ -17,6 +19,7 @@ export interface CreateSqliteDriverDep {
 }
 export interface SqliteDriverOptions {
     memory?: boolean;
+    encryptionKey?: EncryptionKey | undefined;
 }
 /**
  * Cross-platform SQLite abstraction.
@@ -108,13 +111,54 @@ export interface RawSql {
     sql: string;
 }
 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 declare const sql: {
     (strings: TemplateStringsArray, ...parameters: Array<SqlTemplateParam>): SqliteQuery;
     identifier(identifier: string): SqlIdentifier;
     raw(raw: string): RawSql;
     prepared(strings: TemplateStringsArray, ...parameters: Array<SqlTemplateParam>): SqliteQuery;
 };
+/**
+ * Checks if a SQL string contains mutation keywords (insert, update, delete,
+ * etc.). Results are cached for performance.
+ */
 export declare const isSqlMutation: Predicate<string>;
 export interface SqliteQueryPlanRow {
     id: number;
@@ -124,11 +168,51 @@ export interface SqliteQueryPlanRow {
 export declare const explainSqliteQueryPlan: (deps: SqliteDep) => (query: SqliteQuery) => Result<void, SqliteError>;
 /**
  * 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 declare const SqliteBoolean: import("./Type.js").TransformType<import("./Type.js").Type<"Boolean", boolean, boolean, import("./Type.js").BooleanError, boolean, import("./Type.js").BooleanError>, import("./Type.js").UnionType<[import("./Type.js").LiteralType<0>, import("./Type.js").LiteralType<1>]>, never>;
+export declare const SqliteBoolean: import("./Type.js").UnionType<[import("./Type.js").LiteralType<0>, import("./Type.js").LiteralType<1>]>;
 export type SqliteBoolean = typeof SqliteBoolean.Type;
+/**
+ * Represents the {@link SqliteBoolean} value for `true`.
+ *
+ * See {@link SqliteBoolean}.
+ */
+export declare const sqliteTrue = 1;
+/**
+ * Represents the {@link SqliteBoolean} value for `false`.
+ *
+ * See {@link SqliteBoolean}.
+ */
+export declare const sqliteFalse = 0;
+/**
+ * Converts a JavaScript boolean to a {@link SqliteBoolean}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isActive = true;
+ * const sqlValue = booleanToSqliteBoolean(isActive); // Returns 1
+ * ```
+ */
+export declare const booleanToSqliteBoolean: (value: boolean) => SqliteBoolean;
+/**
+ * Converts a {@link SqliteBoolean} to a JavaScript boolean.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const sqlValue: SqliteBoolean = 1;
+ * const bool = sqliteBooleanToBoolean(sqlValue); // Returns true
+ * ```
+ */
+export declare const sqliteBooleanToBoolean: (value: SqliteBoolean) => boolean;
 //# sourceMappingURL=Sqlite.d.ts.map

package/dist/src/Sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sqlite.d.ts","sourceRoot":"","sources":["../../src/Sqlite.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Sqlite.d.ts","sourceRoot":"","sources":["../../src/Sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAA2B,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAW,MAAM,EAAqB,MAAM,aAAa,CAAC;AACjE,OAAO,EAIL,UAAU,EAIX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAoB,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,KAAK,gBAAgB,CAAC;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,UAAU,CAAC;CACnC;AAED,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,mBAAmB,KAC1B,OAAO,CAAC,YAAY,CAAC,CAAC;AAE3B,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;CACjD;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,MAAO,SAAQ,UAAU;IACxC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAC7C,KAAK,EAAE,WAAW,KACf,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EACzB,QAAQ,EAAE,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,KACvC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC;IAEhC,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACvC;AAED,kDAAkD;AAClD,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,iBAAiB,CAAC,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,wlBAA0C,CAAC;AACnE,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAC;AAElD,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEzC;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAEvC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC/D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,YAAY,GACtB,MAAM,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,MAEhD,MAAM,UAAU,EAChB,UAAU,mBAAmB,KAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CA+Ff,CAAC;AAyB1B,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,UAAU;IACvD,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,SAAS,OAAO,EAC9B,KAAK,EAAE,WAAW,EAClB,aAAa,CAAC,EAAE,CAAC,KACd,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;CACpC;AAED,eAAO,MAAM,6BAA6B,GAAI,CAAC,EAC7C,SAAS,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,EAC5B,WAAW,CAAC,SAAS,EAAE,CAAC,KAAK,IAAI,KAChC,kBAAkB,CAAC,CAAC,CAuBtB,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,GAAG;cACL,oBAAoB,iBACd,KAAK,CAAC,gBAAgB,CAAC,GACrC,WAAW;2BAoBgB,MAAM,GAAG,aAAa;aAcpC,MAAM,GAAG,MAAM;sBAGpB,oBAAoB,iBACd,KAAK,CAAC,gBAAgB,CAAC,GACrC,WAAW;CArBb,CAAC;AA0BF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,CAAC,MAAM,CAa3C,CAAC;AAyDF,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,sBAAsB,GAChC,MAAM,SAAS,MACf,OAAO,WAAW,KAAG,MAAM,CAAC,IAAI,EAAE,WAAW,CAiB7C,CAAC;AAoBJ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,yGAAc,CAAC;AACzC,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B;;;;GAIG;AACH,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,OAAO,KAAG,aACtB,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,aAAa,KAAG,OACxC,CAAC"}

package/dist/src/Sqlite.js

@@ -1,6 +1,7 @@
+import { createLruCache } from "./Cache.js";
 import { createTransferableError } from "./Error.js";
 import { err, ok, tryAsync, trySync } from "./Result.js";
-import { Boolean, Null, Number, String, transform, Uint8Array, union, } from "./Type.js";
+import { Null, Number, PositiveInt, String, Uint8Array, union, } from "./Type.js";
 /**
  * A value that can be stored in Sqlite.
  *
@@ -21,9 +22,9 @@ export const createSqlite = (deps) => async (name, options) => tryAsync(async ()
     }, createSqliteError);
     const sqlite = {
         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;
         }, (error) => ({
             type: "SqliteError",
@@ -121,7 +122,44 @@ export const createPreparedStatementsCache = (factory, disposeFn) => {
         },
     };
 };
-/** 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, ...parameters) => {
     let sql = "";
     const values = [];
@@ -158,6 +196,25 @@ sql.prepared = (strings, ...parameters) => {
     const query = sql(strings, ...parameters);
     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 = (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(PositiveInt.orThrow(10_000));
 const isSqlMutationRegEx = new RegExp(`\\b(${[
     "alter",
     "create",
@@ -172,7 +229,37 @@ const isSqlMutationRegEx = new RegExp(`\\b(${[
     "pragma",
     "vacuum",
 ].join("|")})\\b`, "i");
-export const isSqlMutation = (sql) => isSqlMutationRegEx.test(sql.replace(/--.*$/gm, ""));
+/**
+ * Removes SQL line comments (--) from a SQL string without using regex to avoid
+ * ReDoS vulnerabilities.
+ */
+const removeSqlComments = (sql) => {
+    // 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 const explainSqliteQueryPlan = (deps) => (query) => {
     const result = deps.sqlite.exec({
         ...query,
@@ -181,7 +268,7 @@ export const explainSqliteQueryPlan = (deps) => (query) => {
     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));
     return ok();
@@ -203,9 +290,49 @@ const drawSqliteQueryPlan = (rows) => rows
     .join("\n");
 /**
  * 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 = union(0, 1);
+/**
+ * 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) => 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 SqliteBoolean = transform(Boolean, union(0, 1), (value) => ok(value ? 1 : 0), (value) => value === 1);
+export const sqliteBooleanToBoolean = (value) => value === sqliteTrue;