@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/Set.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Set helpers.
+ *
+ * All helpers return readonly sets for safety. Native Set methods like `add()`
+ * and `delete()` mutate the original — use {@link addToSet} and
+ * {@link deleteFromSet} instead for immutable operations that return new sets.
+ *
+ * Use {@link isNonEmptySet} to narrow to {@link NonEmptyReadonlySet} before
+ * calling functions like {@link firstInSet} that require a non-empty set.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Type guards
+ * const set: ReadonlySet<number> = new Set([1, 2, 3]);
+ * if (isNonEmptySet(set)) {
+ *   firstInSet(set);
+ * }
+ *
+ * // Immutable transformations
+ * const added = addToSet(new Set([1, 2]), 3); // Set {1, 2, 3}
+ * const removed = deleteFromSet(new Set([1, 2, 3]), 2); // Set {1, 3}
+ * const mapped = mapSet(new Set([1, 2, 3]), (x) => x * 2); // Set {2, 4, 6}
+ * const filtered = filterSet(new Set([1, 2, 3, 4]), (x) => x % 2 === 0); // Set {2, 4}
+ *
+ * // Set operations
+ * const union = unionSets(new Set([1, 2]), new Set([2, 3])); // Set {1, 2, 3}
+ * const intersection = intersectSets(new Set([1, 2]), new Set([2, 3])); // Set {2}
+ * const difference = differenceSets(new Set([1, 2, 3]), new Set([2])); // Set {1, 3}
+ * ```
+ *
+ * @module
+ */
+import type { NonEmptyReadonlyArray } from "./Array.js";
+import type { Brand } from "./Brand.js";
+import type { PredicateWithIndex, RefinementWithIndex } from "./Types.js";
+/**
+ * An empty readonly set.
+ *
+ * Use as a default or initial value to avoid allocating new empty sets.
+ *
+ * @group Constants
+ */
+export declare const emptySet: ReadonlySet<never>;
+/**
+ * Creates a readonly set from an array.
+ *
+ * Preserves non-empty type when the input array is non-empty.
+ *
+ * ### Example
+ *
+ * ```ts
+ * createSet([1, 2, 3]); // NonEmptyReadonlySet<number>
+ * createSet([] as ReadonlyArray<number>); // ReadonlySet<number>
+ * ```
+ *
+ * @group Constructors
+ */
+export declare function createSet<T>(items: NonEmptyReadonlyArray<T>): NonEmptyReadonlySet<T>;
+/** Possibly empty set. */
+export declare function createSet<T>(items: ReadonlyArray<T>): ReadonlySet<T>;
+/**
+ * A readonly set with at least one element (branded for type safety).
+ *
+ * Use {@link isNonEmptySet} to narrow from `ReadonlySet`, or use functions like
+ * {@link addToSet} that return branded non-empty sets.
+ *
+ * There is no mutable `NonEmptySet` type because mutable sets can be emptied
+ * after narrowing (via `clear()` or `delete()`), making compile-time guarantees
+ * impossible.
+ *
+ * @group Types
+ */
+export type NonEmptyReadonlySet<T> = ReadonlySet<T> & Brand<"NonEmpty">;
+/**
+ * Checks if a set is non-empty and narrows its type to
+ * {@link NonEmptyReadonlySet}.
+ *
+ * Both mutable and readonly sets narrow to the branded
+ * {@link NonEmptyReadonlySet} type, which can be used with functions like
+ * {@link firstInSet}.
+ *
+ * To check if a set is empty, use `if (!isNonEmptySet(set))` — using the
+ * negated guard is better than `.size === 0` for early returns because
+ * TypeScript narrows the type after the check.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const set: ReadonlySet<number> = new Set([1, 2, 3]);
+ * if (isNonEmptySet(set)) {
+ *   firstInSet(set); // set is NonEmptyReadonlySet<number>
+ * }
+ * ```
+ *
+ * @group Type guards
+ */
+export declare const isNonEmptySet: <T>(set: ReadonlySet<T>) => set is NonEmptyReadonlySet<T>;
+/**
+ * Returns a new readonly set with an item added.
+ *
+ * If the item already exists, returns a new set with the same elements (still a
+ * new reference for change detection).
+ *
+ * ### Example
+ *
+ * ```ts
+ * addToSet(new Set([1, 2]), 3); // Set {1, 2, 3}
+ * addToSet(new Set([1, 2]), 2); // Set {1, 2} (new reference)
+ * ```
+ *
+ * @group Transformations
+ */
+export declare const addToSet: <T>(set: ReadonlySet<T>, item: T) => NonEmptyReadonlySet<T>;
+/**
+ * Returns a new readonly set with an item removed.
+ *
+ * If the item doesn't exist, returns a new set with the same elements (still a
+ * new reference for change detection).
+ *
+ * ### Example
+ *
+ * ```ts
+ * deleteFromSet(new Set([1, 2, 3]), 2); // Set {1, 3}
+ * deleteFromSet(new Set([1, 2]), 5); // Set {1, 2} (new reference)
+ * ```
+ *
+ * @group Transformations
+ */
+export declare const deleteFromSet: <T>(set: ReadonlySet<T>, item: T) => ReadonlySet<T>;
+/**
+ * Maps a set using a mapper function, returning a new readonly set.
+ *
+ * Preserves non-empty type.
+ *
+ * Note: If the mapper produces duplicate values, the resulting set will have
+ * fewer elements.
+ *
+ * ### Example
+ *
+ * ```ts
+ * mapSet(new Set([1, 2, 3]), (x) => x * 2); // Set {2, 4, 6}
+ * mapSet(new Set([1, 2, 3]), (x) => x % 2); // Set {1, 0} (duplicates merged)
+ * ```
+ *
+ * @group Transformations
+ */
+export declare function mapSet<T, U>(set: NonEmptyReadonlySet<T>, mapper: (item: T) => U): NonEmptyReadonlySet<U>;
+/** Possibly empty set. */
+export declare function mapSet<T, U>(set: ReadonlySet<T>, mapper: (item: T) => U): ReadonlySet<U>;
+/**
+ * Filters a set using a predicate or refinement function, returning a new
+ * readonly set.
+ *
+ * When used with a refinement function (with `value is Type` syntax),
+ * TypeScript will narrow the result type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * filterSet(new Set([1, 2, 3, 4, 5]), (x) => x % 2 === 0); // Set {2, 4}
+ * ```
+ *
+ * @group Transformations
+ */
+export declare function filterSet<T, S extends T>(set: ReadonlySet<T>, refinement: RefinementWithIndex<T, S>): ReadonlySet<S>;
+/** With predicate. */
+export declare function filterSet<T>(set: ReadonlySet<T>, predicate: PredicateWithIndex<T>): ReadonlySet<T>;
+/**
+ * Returns the first element of a non-empty set (by insertion order).
+ *
+ * ### Example
+ *
+ * ```ts
+ * firstInSet(new Set(["a", "b", "c"])); // "a"
+ * ```
+ *
+ * @group Accessors
+ */
+export declare const firstInSet: <T>(set: NonEmptyReadonlySet<T>) => T;
+//# sourceMappingURL=Set.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Set.d.ts","sourceRoot":"","sources":["../../src/Set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,KAAK,CAA2B,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC9B,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAC1B,0BAA0B;AAC1B,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AAKtE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,KAAK,WAAW,CAAC,CAAC,CAAC,KAClB,GAAG,IAAI,mBAAmB,CAAC,CAAC,CAAiB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACxB,KAAK,WAAW,CAAC,CAAC,CAAC,EACnB,MAAM,CAAC,KACN,mBAAmB,CAAC,CAAC,CAIvB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,KAAK,WAAW,CAAC,CAAC,CAAC,EACnB,MAAM,CAAC,KACN,WAAW,CAAC,CAAC,CAIf,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EACzB,GAAG,EAAE,mBAAmB,CAAC,CAAC,CAAC,EAC3B,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GACrB,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAC1B,0BAA0B;AAC1B,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EACzB,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GACrB,WAAW,CAAC,CAAC,CAAC,CAAC;AAYlB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,EACtC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GACpC,WAAW,CAAC,CAAC,CAAC,CAAC;AAClB,sBAAsB;AACtB,wBAAgB,SAAS,CAAC,CAAC,EACzB,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,WAAW,CAAC,CAAC,CAAC,CAAC;AAelB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,KAAK,mBAAmB,CAAC,CAAC,CAAC,KAAG,CAC5B,CAAC"}

package/dist/src/Set.js

@@ -0,0 +1,137 @@
+/**
+ * Set helpers.
+ *
+ * All helpers return readonly sets for safety. Native Set methods like `add()`
+ * and `delete()` mutate the original — use {@link addToSet} and
+ * {@link deleteFromSet} instead for immutable operations that return new sets.
+ *
+ * Use {@link isNonEmptySet} to narrow to {@link NonEmptyReadonlySet} before
+ * calling functions like {@link firstInSet} that require a non-empty set.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Type guards
+ * const set: ReadonlySet<number> = new Set([1, 2, 3]);
+ * if (isNonEmptySet(set)) {
+ *   firstInSet(set);
+ * }
+ *
+ * // Immutable transformations
+ * const added = addToSet(new Set([1, 2]), 3); // Set {1, 2, 3}
+ * const removed = deleteFromSet(new Set([1, 2, 3]), 2); // Set {1, 3}
+ * const mapped = mapSet(new Set([1, 2, 3]), (x) => x * 2); // Set {2, 4, 6}
+ * const filtered = filterSet(new Set([1, 2, 3, 4]), (x) => x % 2 === 0); // Set {2, 4}
+ *
+ * // Set operations
+ * const union = unionSets(new Set([1, 2]), new Set([2, 3])); // Set {1, 2, 3}
+ * const intersection = intersectSets(new Set([1, 2]), new Set([2, 3])); // Set {2}
+ * const difference = differenceSets(new Set([1, 2, 3]), new Set([2])); // Set {1, 3}
+ * ```
+ *
+ * @module
+ */
+/**
+ * An empty readonly set.
+ *
+ * Use as a default or initial value to avoid allocating new empty sets.
+ *
+ * @group Constants
+ */
+export const emptySet = /*#__PURE__*/ new Set();
+export function createSet(items) {
+    return new Set(items);
+}
+/**
+ * Checks if a set is non-empty and narrows its type to
+ * {@link NonEmptyReadonlySet}.
+ *
+ * Both mutable and readonly sets narrow to the branded
+ * {@link NonEmptyReadonlySet} type, which can be used with functions like
+ * {@link firstInSet}.
+ *
+ * To check if a set is empty, use `if (!isNonEmptySet(set))` — using the
+ * negated guard is better than `.size === 0` for early returns because
+ * TypeScript narrows the type after the check.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const set: ReadonlySet<number> = new Set([1, 2, 3]);
+ * if (isNonEmptySet(set)) {
+ *   firstInSet(set); // set is NonEmptyReadonlySet<number>
+ * }
+ * ```
+ *
+ * @group Type guards
+ */
+export const isNonEmptySet = (set) => set.size > 0;
+/**
+ * Returns a new readonly set with an item added.
+ *
+ * If the item already exists, returns a new set with the same elements (still a
+ * new reference for change detection).
+ *
+ * ### Example
+ *
+ * ```ts
+ * addToSet(new Set([1, 2]), 3); // Set {1, 2, 3}
+ * addToSet(new Set([1, 2]), 2); // Set {1, 2} (new reference)
+ * ```
+ *
+ * @group Transformations
+ */
+export const addToSet = (set, item) => {
+    const next = new Set(set);
+    next.add(item);
+    return next;
+};
+/**
+ * Returns a new readonly set with an item removed.
+ *
+ * If the item doesn't exist, returns a new set with the same elements (still a
+ * new reference for change detection).
+ *
+ * ### Example
+ *
+ * ```ts
+ * deleteFromSet(new Set([1, 2, 3]), 2); // Set {1, 3}
+ * deleteFromSet(new Set([1, 2]), 5); // Set {1, 2} (new reference)
+ * ```
+ *
+ * @group Transformations
+ */
+export const deleteFromSet = (set, item) => {
+    const next = new Set(set);
+    next.delete(item);
+    return next;
+};
+export function mapSet(set, mapper) {
+    const next = new Set();
+    for (const item of set) {
+        next.add(mapper(item));
+    }
+    return next;
+}
+export function filterSet(set, predicate) {
+    const next = new Set();
+    let index = 0;
+    for (const item of set) {
+        if (predicate(item, index++)) {
+            next.add(item);
+        }
+    }
+    return next;
+}
+/**
+ * Returns the first element of a non-empty set (by insertion order).
+ *
+ * ### Example
+ *
+ * ```ts
+ * firstInSet(new Set(["a", "b", "c"])); // "a"
+ * ```
+ *
+ * @group Accessors
+ */
+export const firstInSet = (set) => set.values().next().value;

package/dist/src/Skiplist.d.ts

@@ -1,4 +1,9 @@
-import { RandomDep } from "./Random.js";
+/**
+ * Skiplist data structure with probabilistic level generation.
+ *
+ * @module
+ */
+import type { RandomDep } from "./Random.js";
 import { PositiveInt } from "./Type.js";
 export interface SkiplistLevel {
     readonly create: () => PositiveInt;

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

@@ -1 +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"}
+{"version":3,"file":"Skiplist.d.ts","sourceRoot":"","sources":["../../src/Skiplist.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,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

@@ -1,3 +1,8 @@
+/**
+ * Skiplist data structure with probabilistic level generation.
+ *
+ * @module
+ */
 import { PositiveInt } from "./Type.js";
 // TODO: Use in Storage.
 export const createSkiplistLevel = (deps) => (config = {}) => {

package/dist/src/Sqlite.d.ts

@@ -1,65 +1,71 @@
-import { Brand } from "./Brand.js";
-import { ConsoleDep } from "./Console.js";
-import { EncryptionKey } from "./Crypto.js";
-import { Eq } from "./Eq.js";
-import { TransferableError } from "./Error.js";
-import { Result } from "./Result.js";
-import { SimpleName } from "./Type.js";
-import { Predicate } from "./Types.js";
-/**
- * SQLite driver interface. This is the minimal interface that platform-specific
- * drivers must implement.
+/**
+ * SQLite database abstraction and query execution.
+ *
+ * @module
  */
-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 {
-    readonly memory?: boolean;
-    readonly encryptionKey?: EncryptionKey | undefined;
-}
+import type { Brand } from "./Brand.js";
+import type { EncryptionKey } from "./Crypto.js";
+import type { Eq } from "./Eq.js";
+import type { Result } from "./Result.js";
+import type { Run, Task } from "./Task.js";
+import { type TestDeps } from "./Test.js";
+import type { InferType, Name, Typed } from "./Type.js";
 /**
- * Cross-platform SQLite abstraction.
+ * Platform-agnostic SQLite wrapping a {@link SqliteDriver}.
  *
- * 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.
+ * API is synchronous because it provides
+ * {@link https://github.com/WiseLibs/better-sqlite3/issues/262 | better concurrency}
+ * for SQLite.
  */
-export interface Sqlite extends Disposable {
-    readonly exec: <R extends SqliteRow = SqliteRow>(query: SqliteQuery) => Result<SqliteExecResult<R>, SqliteError>;
+export interface Sqlite extends AsyncDisposable {
+    readonly exec: <R extends SqliteRow = SqliteRow>(query: SqliteQuery) => SqliteExecResult<R>;
     /**
      * 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.
+     * block.
+     *
+     * If the callback returns a {@link Result} error, the transaction is rolled
+     * back and the error result is returned.
+     *
+     * If the callback returns `void`, the transaction is committed unless the
+     * callback throws.
+     */
+    readonly transaction: SqliteTransaction;
+    /**
+     * Returns bytes backed by {@link ArrayBuffer}.
+     *
+     * Exported databases are forwarded through worker `postMessage` transfer
+     * lists, which require transferable `ArrayBuffer` backing.
      */
-    readonly transaction: <T, E>(callback: () => Result<T, E | SqliteError>) => Result<T, E | SqliteError>;
-    readonly export: () => Result<Uint8Array, SqliteError>;
+    readonly export: () => Uint8Array<ArrayBuffer>;
 }
 export interface SqliteDep {
     readonly sqlite: Sqlite;
 }
+export interface SqliteTransaction {
+    <T, E>(callback: () => Result<T, E>): Result<T, E>;
+    (callback: () => void): void;
+}
+/** Represents a SQL query to be executed on a {@link Sqlite} database. */
 export interface SqliteQuery {
     readonly sql: SafeSql;
     readonly parameters: Array<SqliteValue>;
     readonly options?: SqliteQueryOptions;
 }
-/** A type representing a sanitized SQL string. */
+/** Serialized {@link SqliteQuery} used as a stable string key. */
+export type SqliteQueryString = string & Brand<"SqliteQueryString">;
+/** A sanitized SQL string for {@link SqliteQuery}. */
 export type SafeSql = string & Brand<"SafeSql">;
 /**
- * A value that can be stored in Sqlite.
+ * A value that can be stored in {@link 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;
+/** Equality comparison for {@link SqliteValue}. */
 export declare const eqSqliteValue: Eq<SqliteValue>;
+/** Options for configuring {@link SqliteQuery} execution behavior. */
 export interface SqliteQueryOptions {
     /**
      * If set to `true`, logs the time taken to execute the SQL query. Useful for
@@ -83,35 +89,91 @@ export interface SqliteQueryOptions {
      */
     readonly prepare?: boolean;
 }
+/** Converts a {@link SqliteQuery} into a stable {@link SqliteQueryString}. */
+export declare const sqliteQueryToSqliteQueryString: (query: SqliteQuery) => SqliteQueryString;
+/** Converts a {@link SqliteQueryString} back into a {@link SqliteQuery}. */
+export declare const sqliteQueryStringToSqliteQuery: (query: SqliteQueryString) => SqliteQuery;
 /** 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;
-}
+/**
+ * A row returned from a {@link Sqlite} query, mapping column names to
+ * {@link SqliteValue}.
+ */
 export type SqliteRow = Record<string, SqliteValue>;
 /**
- * Creates a fully featured {@link Sqlite} instance from a {@link SqliteDriver}
- * implementation.
+ * SQLite driver interface.
+ *
+ * Platform-specific drivers must implement this interface.
+ */
+export interface SqliteDriver extends Disposable {
+    readonly exec: (query: SqliteQuery) => SqliteExecResult;
+    /**
+     * Returns bytes backed by {@link ArrayBuffer}.
+     *
+     * Exported databases are forwarded through worker `postMessage` transfer
+     * lists, which require transferable `ArrayBuffer` backing.
+     */
+    readonly export: () => Uint8Array<ArrayBuffer>;
+}
+/** Creates a {@link SqliteDriver}. */
+export type CreateSqliteDriver = (name: Name, options?: SqliteDriverOptions) => Task<SqliteDriver>;
+export interface CreateSqliteDriverDep {
+    createSqliteDriver: CreateSqliteDriver;
+}
+/**
+ * Options for creating a {@link CreateSqliteDriver}.
+ *
+ * Three mutually exclusive modes: in-memory (for testing), encrypted persistent
+ * (OPFS/file with encryption key), or persistent (default when omitted).
+ */
+export type SqliteDriverOptions = {
+    readonly mode: "memory";
+} | {
+    readonly mode: "encrypted";
+    readonly encryptionKey: EncryptionKey;
+};
+/**
+ * Creates a {@link Sqlite} instance backed by a platform-specific driver.
+ *
+ * The driver is created via {@link CreateSqliteDriver} and wrapped with logging,
+ * error handling, and transaction helpers.
+ */
+export declare const createSqlite: (name: Name, options?: SqliteDriverOptions) => Task<Sqlite, never, CreateSqliteDriverDep>;
+/** Creates a test setup with a in-memory {@link Sqlite}. */
+export declare const testSetupSqlite: (deps: CreateSqliteDriverDep) => Promise<AsyncDisposable & SqliteDep & {
+    readonly run: Run<TestDeps & CreateSqliteDriverDep & SqliteDep>;
+    readonly sqlite: Sqlite;
+}>;
+/**
+ * Cache for compiled prepared statements.
+ *
+ * Statements are created on first access and reused for subsequent calls with
+ * the same SQL. Disposing the cache finalizes all cached statements.
  */
-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;
 }
+/**
+ * Creates a {@link PreparedStatements} cache backed by the given factory and
+ * dispose function.
+ */
 export declare const createPreparedStatementsCache: <P>(factory: (sql: SafeSql) => P, disposeFn: (statement: P) => void) => PreparedStatements<P>;
-export interface SqlIdentifier {
-    readonly type: "SqlIdentifier";
+/** A double-quoted SQL identifier for safe column or table name interpolation. */
+export interface SqlIdentifier extends Typed<"SqlIdentifier"> {
     readonly sql: SafeSql;
 }
-export interface RawSql {
-    readonly type: "RawSql";
+/**
+ * An unescaped SQL fragment inserted verbatim into a query.
+ *
+ * **Warning**: Use only with trusted, constant strings to avoid SQL injection.
+ */
+export interface RawSql extends Typed<"RawSql"> {
     readonly sql: string;
 }
+/** A parameter accepted by the {@link sql} tagged template. */
 export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
 /**
  * Creates a safe SQL query using a tagged template literal.
@@ -145,7 +207,7 @@ export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
  * sqlite.exec(sql`select * from users order by ${sql.raw(orderBy)};`);
  * ```
  *
- * ### TIP
+ * ## TIP
  *
  * Use `prettier-plugin-sql-cst` for SQL formatting. Like Prettier for
  * JavaScript, this plugin formats SQL expressions differently depending on
@@ -157,24 +219,62 @@ export declare const sql: {
     raw(raw: string): RawSql;
     prepared(strings: TemplateStringsArray, ...parameters: Array<SqlTemplateParam>): SqliteQuery;
 };
+/** Index metadata stored in `sqlite_master` for a {@link Sqlite} database. */
+export declare const SqliteIndex: import("./Type.js").ObjectType<{
+    name: import("./Type.js").Type<"String", string, string, import("./Type.js").StringError, string, import("./Type.js").StringError>;
+    sql: import("./Type.js").Type<"String", string, string, import("./Type.js").StringError, string, import("./Type.js").StringError>;
+}>;
+export interface SqliteIndex extends InferType<typeof SqliteIndex> {
+}
+/** {@link Eq} instance for {@link SqliteIndex}. */
+export declare const eqSqliteIndex: Eq<SqliteIndex>;
+/**
+ * Full schema metadata for a {@link Sqlite} database.
+ *
+ * Includes table-column mappings and user-visible indexes.
+ */
+export declare const SqliteSchema: import("./Type.js").ObjectType<{
+    tables: import("./Type.js").RecordType<"String", string, string, import("./Type.js").StringError, string, import("./Type.js").StringError, import("./Type.js").SetType<import("./Type.js").Type<"String", string, string, import("./Type.js").StringError, string, import("./Type.js").StringError>>>;
+    indexes: import("./Type.js").ArrayType<import("./Type.js").ObjectType<{
+        name: import("./Type.js").Type<"String", string, string, import("./Type.js").StringError, string, import("./Type.js").StringError>;
+        sql: import("./Type.js").Type<"String", string, string, import("./Type.js").StringError, string, import("./Type.js").StringError>;
+    }>>;
+}>;
+export interface SqliteSchema extends InferType<typeof SqliteSchema> {
+}
+/** Get the current SQLite schema by reading SQLite metadata. */
+export declare const getSqliteSchema: (deps: SqliteDep) => ({ excludeIndexNamePrefix, }?: {
+    /**
+     * If provided, indexes with names starting with this prefix are excluded in
+     * SQLite query.
+     */
+    excludeIndexNamePrefix?: string;
+}) => SqliteSchema;
 /**
- * Checks if a SQL string contains mutation keywords (insert, update, delete,
- * etc.). Results are cached for performance.
+ * Returns {@link SqliteSchema} and full {@link SqliteRow} table contents for
+ * inspection and testing.
  */
-export declare const isSqlMutation: Predicate<string>;
-export interface SqliteQueryPlanRow {
-    id: number;
-    parent: number;
-    detail: string;
+export interface SqliteSnapshot {
+    readonly schema: SqliteSchema;
+    readonly tables: Array<{
+        readonly name: string;
+        readonly rows: ReadonlyArray<SqliteRow>;
+    }>;
 }
-export declare const explainSqliteQueryPlan: (deps: SqliteDep) => (query: SqliteQuery) => Result<void, SqliteError>;
+/**
+ * Captures a full {@link SqliteSnapshot} for testing and diagnostics.
+ *
+ * The snapshot includes current {@link SqliteSchema} and all rows from every
+ * discovered table. Table order follows `schema.tables` iteration order.
+ */
+export declare const getSqliteSnapshot: (deps: SqliteDep) => SqliteSnapshot;
 /**
  * SQLite represents boolean values using `0` (false) and `1` (true) instead of
  * a dedicated boolean type.
  *
  * See: https://www.sqlite.org/quirks.html#no_separate_boolean_datatype
  *
- * ### Tips
+ * ## Tips
  *
  * - Use {@link sqliteTrue} and {@link sqliteFalse} constants for better
  *   readability.