@evolu/common 5.4.8 → 6.0.0

package/dist/src/Result.js

@@ -0,0 +1,357 @@
+/**
+ * 🛡️ 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 };
+}
+/**
+ * Creates an {@link Err} result.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const failure = err("Something went wrong");
+ * console.log(failure); // { ok: false, error: "Something went wrong" }
+ * ```
+ */
+export const err = (error) => ({ ok: false, error });
+/**
+ * Extracts the value from a {@link Result} if it is an `Ok`, or throws an error
+ * if it is an `Err`.
+ *
+ * **Intended usage:**
+ *
+ * - For critical code paths (e.g., app startup, config values) where failure
+ *   should crash the app.
+ * - Not recommended for general error handling in application logic—prefer
+ *   explicit checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // At app startup, crash if config is invalid:
+ * const config = getOrThrow(loadConfig());
+ * // Safe to use config here
+ * ```
+ */
+export const getOrThrow = (result) => {
+    if (result.ok) {
+        return result.value;
+    }
+    else {
+        throw new Error(`Result error: ${JSON.stringify(result.error)}`);
+    }
+};
+/**
+ * Wraps synchronous functions that may throw exceptions, returning a
+ * {@link Result}.
+ *
+ * The `trySync` function is designed to handle synchronous code safely by
+ * wrapping the execution in a try-catch block. If the function succeeds, it
+ * returns an `Ok` result. If an exception is thrown, it maps the error to a
+ * custom type and returns an `Err` result.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface ParseJsonError {
+ *   readonly type: "ParseJsonError";
+ *   readonly message: string;
+ * }
+ *
+ * const parseJson = (value: string): Result<unknown, ParseJsonError> =>
+ *   trySync(
+ *     () => JSON.parse(value) as unknown,
+ *     (error) => ({ type: "ParseJsonError", message: String(error) }),
+ *   );
+ * ```
+ */
+export const trySync = (fn, mapError) => {
+    try {
+        return ok(fn());
+    }
+    catch (error) {
+        return err(mapError(error));
+    }
+};
+/**
+ * Wraps async functions or any operation returning a promise, returning a
+ * {@link Result}.
+ *
+ * The `tryAsync` function provides a way to handle asynchronous code safely by
+ * catching any rejected promises and mapping errors to a custom type. If the
+ * promise resolves, it returns an `Ok` result. If the promise rejects, it maps
+ * the error and returns an `Err` result.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface FetchError {
+ *   readonly type: "FetchError";
+ *   readonly message: string;
+ * }
+ *
+ * const tryFetch = async (
+ *   url: string,
+ * ): Promise<Result<unknown, FetchError>> =>
+ *   tryAsync(
+ *     async () => {
+ *       const response = await fetch(url);
+ *       if (!response.ok) {
+ *         throw new Error(`Request failed with status ${response.status}`);
+ *       }
+ *       return response.json();
+ *     },
+ *     (error) => ({
+ *       type: "FetchError",
+ *       message: String(error),
+ *     }),
+ *   );
+ *
+ * const result = await tryFetch(
+ *   "https://jsonplaceholder.typicode.com/posts/1",
+ * );
+ * if (result.ok) {
+ *   console.log("Data:", result.value);
+ * } else {
+ *   console.error("Error:", result.error);
+ * }
+ * ```
+ */
+export const tryAsync = async (promiseFn, mapError) => promiseFn().then((value) => ok(value), (error) => err(mapError(error)));

package/dist/src/Skiplist.d.ts

@@ -0,0 +1,23 @@
+import { RandomDep } from "./Random.js";
+import { PositiveInt } from "./Type.js";
+export interface SkiplistLevel {
+    readonly create: () => PositiveInt;
+}
+export interface SkiplistLevelDep {
+    readonly skiplistLevel: SkiplistLevel;
+}
+export interface SkiplistLevelConfig {
+    readonly probability?: number;
+    readonly maxLevel?: number;
+}
+export declare const createSkiplistLevel: (deps: RandomDep) => (config?: SkiplistLevelConfig) => SkiplistLevel;
+export interface Skiplist {
+    readonly insert: (key: number) => void;
+    readonly find: (key: number) => SkiplistNode | null;
+}
+export interface SkiplistNode {
+    readonly key: number;
+    readonly pointers: Array<SkiplistNode>;
+}
+export declare const createSkiplist: (deps: SkiplistLevelDep) => Skiplist;
+//# sourceMappingURL=Skiplist.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Skiplist.d.ts","sourceRoot":"","sources":["../../src/Skiplist.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,WAAW,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAGD,eAAO,MAAM,mBAAmB,GAC7B,MAAM,SAAS,MACf,SAAQ,mBAAwB,KAAG,aAWnC,CAAC;AAEJ,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,YAAY,GAAG,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;CACxC;AAED,eAAO,MAAM,cAAc,GAAI,MAAM,gBAAgB,KAAG,QA2DvD,CAAC"}

package/dist/src/Skiplist.js

@@ -0,0 +1,58 @@
+// TODO: Use in Storage.
+export const createSkiplistLevel = (deps) => (config = {}) => {
+    const { probability = 0.5, maxLevel = 32 } = config;
+    return {
+        create: () => {
+            let level = 1;
+            while (deps.random.next() <= probability && level < maxLevel) {
+                level += 1;
+            }
+            return level;
+        },
+    };
+};
+export const createSkiplist = (deps) => {
+    const tail = {
+        key: Number.MAX_VALUE,
+        pointers: [],
+    };
+    const head = {
+        key: Number.MIN_VALUE,
+        pointers: [tail],
+    };
+    // Cached to reuse the array.
+    const path = [];
+    return {
+        insert: (key) => {
+            let cur = head;
+            for (let i = head.pointers.length - 1; i >= 0; i--) {
+                while (cur.pointers[i].key < key) {
+                    cur = cur.pointers[i];
+                }
+                path[i] = cur;
+            }
+            const level = deps.skiplistLevel.create();
+            if (level > head.pointers.length) {
+                const tails = Array(level - head.pointers.length).fill(tail);
+                const heads = Array(level - head.pointers.length).fill(head);
+                head.pointers.push(...tails);
+                path.push(...heads);
+            }
+            const newNode = { key, pointers: [] };
+            for (let i = 0; i < level; i++) {
+                newNode.pointers[i] = path[i].pointers[i];
+                path[i].pointers[i] = newNode;
+            }
+        },
+        find: (key) => {
+            let cur = head;
+            for (let i = head.pointers.length - 1; i >= 0; i--) {
+                while (cur.pointers[i] && cur.pointers[i].key < key) {
+                    cur = cur.pointers[i];
+                }
+            }
+            const candidate = cur.pointers[0];
+            return candidate.key === key ? candidate : null;
+        },
+    };
+};

package/dist/src/Sqlite.d.ts

@@ -1,70 +1,134 @@
-import * as Context from "effect/Context";
-import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
-import * as Predicate from "effect/Predicate";
-import { Config } from "./Config.js";
-export interface Sqlite {
-    readonly exec: (query: SqliteQuery) => Effect.Effect<SqliteExecResult>;
-    readonly transaction: (
+import { ConsoleDep } from "./Console.js";
+import { TransferableError } from "./Error.js";
+import { Result } from "./Result.js";
+import { SimpleName } from "./Type.js";
+import { Brand, Predicate } from "./Types.js";
+/**
+ * SQLite driver interface. This is the minimal interface that platform-specific
+ * drivers must implement.
+ */
+export interface SqliteDriver extends Disposable {
+    readonly exec: (query: SqliteQuery, isMutation: boolean) => SqliteExecResult;
+    readonly export: () => Uint8Array;
+}
+export type CreateSqliteDriver = (name: SimpleName, options?: SqliteDriverOptions) => Promise<SqliteDriver>;
+export interface CreateSqliteDriverDep {
+    readonly createSqliteDriver: CreateSqliteDriver;
+}
+export interface SqliteDriverOptions {
+    memory?: boolean;
+}
+/**
+ * Cross-platform SQLite abstraction.
+ *
+ * This API is sync only because SQLite is an embedded, single-threaded engine.
+ * All operations are blocking and in-process, so async APIs add needless
+ * complexity without any real benefit and are also slower. Check better-sqlite3
+ * GitHub issues and docs for details.
+ */
+export interface Sqlite extends Disposable {
+    readonly exec: <R extends SqliteRow = SqliteRow>(query: SqliteQuery) => Result<SqliteExecResult<R>, SqliteError>;
     /**
-     * Use `exclusive` for mutations and `shared` for read-only queries. This
-     * shared/exclusive lock pattern allows multiple simultaneous readers but
-     * only one writer. In Evolu, this pattern also ensures that every write can
-     * be immediately read without waiting to complete. For example, we can add
-     * data on one page and then immediately redirect to another, and the data
-     * will be there.
-     *
-     * There is also a `last` mode that ensures no other transaction can run.
-     * It's for Db reset to ensure no data are accidentally saved after database
-     * wipe-out.
+     * Executes a transaction, running the provided callback within a begin/commit
+     * block. If the callback returns an error (E or {@link SqliteError}), the
+     * transaction is rolled back. If the rollback fails, a SqliteError is
+     * returned with both the original error and rollbackError.
      */
-    mode: SqliteTransactionMode) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Sqlite | R>;
-    readonly export: () => Effect.Effect<Uint8Array>;
+    readonly transaction: <T, E>(callback: () => Result<T, E | SqliteError>) => Result<T, E | SqliteError>;
+    readonly export: () => Result<Uint8Array, SqliteError>;
 }
-export declare const Sqlite: Context.Tag<Sqlite, Sqlite>;
-export type SqliteTransactionMode = "exclusive" | "shared" | "last";
-declare const SqliteFactory_base: Context.TagClass<SqliteFactory, "SqliteFactory", {
-    readonly createSqlite: Effect.Effect<Sqlite, never, Config>;
-}>;
-export declare class SqliteFactory extends SqliteFactory_base {
-    static Common: Layer.Layer<SqliteFactory, never, SqliteFactory>;
+export interface SqliteDep {
+    readonly sqlite: Sqlite;
 }
 export interface SqliteQuery {
-    readonly sql: string;
-    readonly parameters?: Value[];
+    readonly sql: SafeSql;
+    readonly parameters: Array<SqliteValue>;
     readonly options?: SqliteQueryOptions;
 }
+/** A type representing a sanitized SQL string. */
+export type SafeSql = string & Brand<"TimestampString">;
+/**
+ * A value that can be stored in Sqlite.
+ *
+ * Note that Evolu can't support Int64 because expo-sqlite (and some others) do
+ * not support it.
+ */
+export declare const SqliteValue: import("./Type.js").UnionType<[import("./Type.js").Type<"Null", null, null, import("./Type.js").NullError, null, import("./Type.js").NullError>, import("./Type.js").Type<"String", string, string, import("./Type.js").StringError, string, import("./Type.js").StringError>, import("./Type.js").Type<"Number", number, number, import("./Type.js").NumberError, number, import("./Type.js").NumberError>, import("./Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("./Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("./Type.js").Uint8ArrayError>]>;
+export type SqliteValue = typeof SqliteValue.Type;
 export interface SqliteQueryOptions {
+    /**
+     * If set to `true`, logs the time taken to execute the SQL query. Useful for
+     * performance monitoring and identifying slow queries.
+     */
     readonly logQueryExecutionTime?: boolean;
-    /** https://www.sqlite.org/eqp.html */
+    /**
+     * If set to `true`, logs the SQLite Explain Query Plan (EQP) for the query.
+     * This can help analyze how SQLite plans to execute the query and identify
+     * potential optimizations.
+     *
+     * See: {@link https://www.sqlite.org/eqp.html}.
+     */
     readonly logExplainQueryPlan?: boolean;
+    /**
+     * If set to `true`, explicitly prepares the query before execution. Prepared
+     * statements can improve performance for repeated queries by reusing the
+     * compiled query.
+     *
+     * See: {@link https://sqlite.org/wasm/doc/trunk/api-oo1.md#db-prepare}.
+     */
+    readonly prepare?: boolean;
 }
-export type Value = SqliteValue | JsonObjectOrArray;
-export type SqliteValue = null | string | number | Uint8Array;
-export type JsonObjectOrArray = JsonObject | JsonArray;
-type JsonObject = {
-    [key: string]: Json;
-};
-type JsonArray = ReadonlyArray<Json>;
-type JsonPrimitive = string | number | boolean | null;
-type Json = JsonPrimitive | JsonObject | JsonArray;
-export interface SqliteExecResult {
-    readonly rows: SqliteRow[];
+/** Result of executing a SQLite query. */
+export interface SqliteExecResult<R extends SqliteRow = SqliteRow> {
+    readonly rows: ReadonlyArray<R>;
     readonly changes: number;
 }
+/** Represents an error that occurred during a SQLite operation. */
+export interface SqliteError {
+    readonly type: "SqliteError";
+    readonly error: TransferableError;
+    readonly rollbackError?: TransferableError;
+}
 export type SqliteRow = Record<string, SqliteValue>;
-export declare const isJsonObjectOrArray: Predicate.Refinement<Value, JsonObjectOrArray>;
-export declare const valuesToSqliteValues: (values: ReadonlyArray<Value>) => SqliteValue[];
-/** This function mutates for better performance. */
-export declare const maybeParseJson: (rows: SqliteRow[]) => void;
-export declare const maybeJson: Predicate.Predicate<string>;
-export declare const isSqlMutation: (sql: string) => boolean;
-export declare const maybeLogSqliteQueryExecutionTime: (query: SqliteQuery) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
-export type SqliteQueryPlanRow = {
+/**
+ * Creates a fully featured {@link Sqlite} instance from a {@link SqliteDriver}
+ * implementation.
+ */
+export declare const createSqlite: (deps: CreateSqliteDriverDep & Partial<ConsoleDep>) => (name: SimpleName, options?: SqliteDriverOptions) => Promise<Result<Sqlite, SqliteError>>;
+export interface PreparedStatements<P> extends Disposable {
+    readonly get: <T extends boolean>(query: SqliteQuery, alwaysPrepare?: T) => T extends true ? P : P | null;
+}
+export declare const createPreparedStatementsCache: <P>(factory: (sql: SafeSql) => P, disposeFn: (statement: P) => void) => PreparedStatements<P>;
+export interface SqlIdentifier {
+    type: "SqlIdentifier";
+    sql: SafeSql;
+}
+export interface RawSql {
+    type: "RawSql";
+    sql: string;
+}
+export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
+/** TODO: Docs. */
+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;
+};
+export declare const isSqlMutation: Predicate<string>;
+export interface SqliteQueryPlanRow {
     id: number;
     parent: number;
     detail: string;
-};
-export declare const drawSqliteQueryPlan: (rows: SqliteQueryPlanRow[]) => string;
-export {};
+}
+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.
+ *
+ * See: https://www.sqlite.org/quirks.html#no_separate_boolean_datatype
+ */
+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 type SqliteBoolean = typeof SqliteBoolean.Type;
 //# 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":"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"}