@evolu/sqlite-wasm 2.2.4 → 3.53.4-build1

package/dist/src/Wasm.d.ts

@@ -0,0 +1,315 @@
+/**
+ * SQLite's Emscripten wasm, loaded without Emscripten's or SQLite's JavaScript.
+ *
+ * The package ships SQLite's own wasm, built with SQLite's own makefile, and
+ * replaces the generated JavaScript with a small loader and the standalone
+ * functions of `@evolu/sqlite-wasm/c-api`.
+ *
+ * ## Loading
+ *
+ * {@link createSqliteWasm} runs these steps and fails with a
+ * {@link SqliteWasmError} when one fails. Steps 1 to 3 fail before any wasm code
+ * runs, and steps 4 and 5 run only the stack setup, static constructors and
+ * `sqlite3__wasm_enum_json()`, before any SQLite API call:
+ *
+ * 1. Compile, while downloading a `Response` of type `application/wasm`.
+ * 2. Import guard: every import the binary declares must be one the loader
+ *    implements, or instantiation never happens. A new Emscripten or SQLite
+ *    release that adds an import is caught here, not at the first call that
+ *    reaches it. The list matches the release recipe exactly.
+ * 3. A fresh `WebAssembly.Memory` of at least the size the binary declares, which
+ *    the JavaScript API does not expose (256 pages covers every build so far),
+ *    and a maximum of 32768 pages, so pointers stay positive i32 values. An
+ *    engine that cannot allocate it, as on a device low on memory, fails
+ *    loading with {@link SqliteWasmCompileError}.
+ * 4. Instantiate, then set up the C stack for Emscripten's stack check: call
+ *    `emscripten_stack_init`, then `__set_stack_limits` with what
+ *    `emscripten_stack_get_base` and `emscripten_stack_get_end` return. The
+ *    check compares each new stack pointer with limits that start at 0, so they
+ *    are set before any code moves it. Then call `__wasm_call_ctors` exactly
+ *    once. A binary without one of these functions fails the build guard.
+ * 5. Build guard: the hash {@link sqliteWasmBuildHash} defines, computed from the
+ *    string `sqlite3__wasm_enum_json()` returns and the names
+ *    `WebAssembly.Module.exports` lists, must equal it. A match means the
+ *    binary has the pinned build's export names, so it exports every function
+ *    in {@link SqliteCExports}, and the generated constants, struct layouts and
+ *    {@link SQLITE_WASM_DEALLOC} describe it. The hash does not cover wasm
+ *    types: the generator checked the bindings against the pinned types, and
+ *    `scripts/generate.mts --verify-build` checks a new binary's. A binary
+ *    without `sqlite3__wasm_enum_json`, or whose call returns NULL, hashes the
+ *    string as empty and fails. No JSON is parsed at runtime.
+ * 6. `sqlite3_initialize()`, whose result code is checked.
+ * 7. Register the default VFS, then run {@link initializeSqliteWasm}, which makes
+ *    it the default and calls `sqlite3_randomness(0, 0)`. SQLite's random
+ *    number generator seeds itself from the default VFS at its first use, and
+ *    again at the first use after that call resets it. Without Emscripten's
+ *    file system, SQLite's unix VFS seeds it from the time and a constant pid,
+ *    so two instances seeded in the same second would share `randomblob()`
+ *    values and journal nonces. Nothing uses the generator while loading, so
+ *    the reset is defensive here; it matters after `sqlite3_shutdown()`. It
+ *    also unregisters SQLite's kvvfs, which `sqlite3_initialize()` registers
+ *    but whose storage only SQLite's JavaScript provides, so opening it, as the
+ *    names `:localStorage:` and `:sessionStorage:` do on any VFS, fails with
+ *    SQLITE_ERROR instead of trapping. Allocating, finding or registering the
+ *    VFS fails with {@link SqliteWasmInitializeError}, and compiling the
+ *    generated module that installs its methods, which a Content Security
+ *    Policy without 'wasm-unsafe-eval' forbids, fails with
+ *    {@link SqliteWasmCompileError}. `sqlite3_initialize()` after
+ *    `sqlite3_shutdown()` makes the unix VFS the default again, so
+ *    {@link initializeSqliteWasm} must run instead.
+ *
+ * ## The default VFS
+ *
+ * `evolu-memory`, of version 2, has no files, so only `:memory:` databases use
+ * it:
+ *
+ * - `xFullPathname` fails with SQLITE_CANTOPEN, so opening a file path fails
+ *   before SQLite would open a file. `xOpen` is NULL: SQLite opens a file
+ *   without a path only for a temporary file, which this build keeps in memory.
+ *   `xAccess` finds no file, and `xDelete` returns SQLITE_IOERR_DELETE_NOENT.
+ * - `xRandomness` fills memory from {@link RandomBytes}, in chunks of at most
+ *   65536 bytes, as `crypto.getRandomValues` requires.
+ * - `xCurrentTime` and `xCurrentTimeInt64` read `Time.now` of {@link Time}.
+ * - `xSleep` returns at once, having slept 0 microseconds. Contention can only
+ *   come from connections in the same thread, which sleeping cannot resolve.
+ * - `xGetLastError` reports no system error.
+ *
+ * ## Imports
+ *
+ * About ten imports do real work:
+ *
+ * - `memory`, see step 3.
+ * - `__handle_stack_overflow`, which the build's stack check
+ *   (`-sSTACK_OVERFLOW_CHECK=2`) calls instead of moving the stack pointer
+ *   outside the C stack, throws a `WebAssembly.RuntimeError`, as a trap does.
+ *   The C stack has 512 KiB directly above SQLite's static data, and SQL that
+ *   is legal but nests deeply enough, such as a chain of 600 triggers, would
+ *   otherwise overwrite that data silently.
+ * - `emscripten_resize_heap` grows memory to the requested size, read as
+ *   unsigned, and returns 1, or 0 when it cannot, never throwing.
+ * - The clocks read {@link Time}: `emscripten_date_now` returns `Time.now`,
+ *   `emscripten_get_now` returns `Time.performance.now`, and WASI
+ *   `clock_time_get` writes BigInt nanoseconds of the first for the realtime
+ *   clock and of the second for the monotonic and CPU-time clocks, and returns
+ *   EINVAL for any other.
+ * - `_localtime_js`, for SQL `localtime`, reads `Date` in the local time zone and
+ *   fails for a time `Date` cannot represent. It fills only the `struct tm`
+ *   fields SQLite reads, from `tm_sec` to `tm_year`, and zeroes the others.
+ *   `_tzset_js` writes nothing: only `localtime_r` reads what it would write,
+ *   to set `tm_zone`, which nothing reads.
+ * - `environ_sizes_get` and `environ_get` describe an empty environment.
+ * - `fd_write`, for C-side diagnostics, writes complete lines of stdout with
+ *   {@link Console.log} and of stderr with {@link Console.error}, and fails any
+ *   other descriptor with EBADF.
+ *
+ * The `__syscall_*` imports return -ENOSYS (-52), and the remaining WASI `fd_*`
+ * imports return ENOSYS (52), as WASI errors are positive: only `openat` of
+ * `/dev/urandom` is ever reached, and step 7 covers it.
+ *
+ * Every import's wasm type and the memory limits are pinned in
+ * `scripts/upstream/sqlite3-wasm-imports.json`, and `scripts/generate.mts
+ * --verify-build` checks a binary against them.
+ *
+ * ## Rules for everything that uses the instance
+ *
+ * - Synchronous only. The build has neither Asyncify nor JSPI, and nothing in the
+ *   SQLite call path returns a promise.
+ * - Any call that can allocate, including a VFS callback running inside
+ *   `sqlite3_step`, can grow memory, which detaches the previous `ArrayBuffer`.
+ *   Take heap views with {@link SqliteWasm.getHeapU8} after such calls and never
+ *   keep one across them.
+ * - No JavaScript exception may cross into wasm. Every function installed with
+ *   {@link installWasmFunctions} catches what it throws, reports it as a defect
+ *   and returns SQLITE_ERROR.
+ * - A trap or a C stack overflow throws a `WebAssembly.RuntimeError`, which
+ *   installed functions let through. When the static constructors trap, loading
+ *   fails with {@link SqliteWasmCompileError}.
+ * - Any exception or trap that escapes a wasm call is a defect. It unwound C
+ *   frames without cleanup, so the C stack and SQLite's state are left
+ *   inconsistent: it is rethrown, the instance refuses every later call, and
+ *   its worker should end. {@link SqliteWasm.call} enforces this. The CApi
+ *   functions return the exports themselves, so code that calls them directly
+ *   must call through it. An installed function that returns once the instance
+ *   is broken, as one that caught what a nested call rethrew, or whose
+ *   {@link ReportDefect} broke it, throws that refusal instead, so SQLite never
+ *   resumes on that state.
+ *
+ * @module
+ */
+import { type ConsoleDep, type NonEmptyReadonlyArray, type RandomBytesDep, type ReportDefectDep, type Result, type Task, type TimeDep, type Typed } from "@evolu/common";
+import type { SqliteCExports } from "./CApi.ts";
+import { type SqliteResultCode } from "./Constants.ts";
+import type { SqliteFunctionPtr } from "./Pointer.ts";
+/**
+ * A loaded SQLite wasm instance.
+ *
+ * One instance serves every database of a worker. It cannot be disposed; it
+ * lives until the worker ends.
+ */
+export interface SqliteWasm {
+    /**
+     * The C functions, and the build's shims of the variadic ones, as the wasm
+     * exports them.
+     *
+     * Prefer the standalone functions of `@evolu/sqlite-wasm/c-api`, which read
+     * these once per database.
+     */
+    readonly exports: SqliteCExports;
+    /** The wasm function table, where C function pointers point. */
+    readonly functionTable: WebAssembly.Table;
+    /**
+     * Returns a view of the whole heap, created again when memory has grown since
+     * the previous call.
+     */
+    readonly getHeapU8: () => Uint8Array<ArrayBuffer>;
+    /** Returns a `DataView` of the whole heap, like {@link SqliteWasm.getHeapU8}. */
+    readonly getHeapDataView: () => DataView<ArrayBuffer>;
+    /**
+     * Calls a function that calls into wasm, and returns its result.
+     *
+     * Anything the function throws breaks the instance, as the module
+     * documentation explains: it is rethrown, and this and every later call throw
+     * without calling the function. Databases call wasm through it, and so should
+     * code that calls the CApi functions directly.
+     */
+    readonly call: <T>(fn: () => T) => T;
+    /**
+     * Whether an error escaped {@link SqliteWasm.call}, so the instance refuses
+     * calls.
+     */
+    readonly isBroken: () => boolean;
+}
+/** Dependency wrapper for {@link SqliteWasm}. */
+export interface SqliteWasmDep {
+    readonly sqliteWasm: SqliteWasm;
+}
+/**
+ * The wasm binary, compiled or not.
+ *
+ * A `Response` or a promise of one, such as `fetch` returns, compiles while it
+ * downloads when its `Content-Type` is exactly `application/wasm`, which keeps
+ * Chromium's code cache too. That is the only type every engine's
+ * `WebAssembly.compileStreaming` accepts, so any other compiles from its bytes
+ * once it has downloaded. A failed fetch fails with
+ * {@link SqliteWasmCompileError}, and so does a response whose status is not ok,
+ * such as a 404 for a wrong URL, with a `TypeError` naming the status as its
+ * cause. A `WebAssembly.Module` suits a module compiled elsewhere. Loading
+ * compiles a small generated module, so a Content Security Policy must allow
+ * 'wasm-unsafe-eval' even for a precompiled Module.
+ */
+export type SqliteWasmSource = WebAssembly.Module | BufferSource | Response | PromiseLike<Response>;
+/**
+ * Loads the wasm, following the steps in the module documentation.
+ *
+ * Start it as early as possible, in the worker's composition root, and pass the
+ * instance to everything else through {@link SqliteWasmDep}.
+ */
+export declare const createSqliteWasm: (source: SqliteWasmSource) => Task<SqliteWasm, SqliteWasmError, ConsoleDep & RandomBytesDep & ReportDefectDep & TimeDep>;
+/**
+ * Initializes the library as loading steps 6 and 7 do, for use after
+ * `sqlite3_shutdown` and `sqlite3_config`.
+ *
+ * `sqlite3_initialize` alone, or any call that initializes the library itself,
+ * such as an open, makes SQLite's `unix-none` VFS the default again and
+ * registers kvvfs again, so opening `:localStorage:` or `:sessionStorage:`
+ * traps and breaks the instance. Initializing leaves SQLite's random number
+ * generator as it is, but while `unix-none` is the default, a generator reset
+ * with `sqlite3_randomness(0, 0)`, or not used since loading, seeds itself at
+ * its next use from the time and a constant pid instead of {@link RandomBytes},
+ * so instances seeded in the same second share `randomblob()` values and
+ * journal nonces. This function resets the generator once `evolu-memory` is the
+ * default.
+ *
+ * Fails with {@link SqliteWasmInitializeError}, with SQLITE_MISUSE when
+ * `sqlite3_vfs_unregister` removed `evolu-memory`.
+ */
+export declare const initializeSqliteWasm: (deps: SqliteWasmDep) => () => Result<void, SqliteWasmInitializeError>;
+/** Why {@link createSqliteWasm} failed. */
+export type SqliteWasmError = SqliteWasmCompileError | SqliteWasmUnknownImportError | SqliteWasmBuildMismatchError | SqliteWasmInitializeError;
+/**
+ * The source could not be fetched, compiled or instantiated, its memory could
+ * not be allocated, its static constructors failed, or the module that installs
+ * the default VFS's methods could not be compiled.
+ */
+export interface SqliteWasmCompileError extends Typed<"SqliteWasmCompileError"> {
+    readonly cause: unknown;
+}
+/** The binary declares imports the loader does not implement. */
+export interface SqliteWasmUnknownImportError extends Typed<"SqliteWasmUnknownImport"> {
+    /** Each as `module.name`. */
+    readonly imports: NonEmptyReadonlyArray<string>;
+}
+/**
+ * The binary's {@link sqliteWasmBuildHash} differs, so it is not the build the
+ * generated code describes.
+ *
+ * To use this binary, pin it with `node scripts/generate.mts --pin-build
+ * <wasm>` and regenerate.
+ */
+export interface SqliteWasmBuildMismatchError extends Typed<"SqliteWasmBuildMismatch"> {
+    readonly expectedHash: number;
+    readonly actualHash: number;
+}
+/**
+ * `sqlite3_initialize` failed, or allocating, finding or registering the
+ * default VFS did, for example when out of memory.
+ */
+export interface SqliteWasmInitializeError extends Typed<"SqliteWasmInitializeError"> {
+    readonly code: SqliteResultCode;
+}
+/**
+ * A JavaScript function to install into the function table.
+ *
+ * The signature uses the notation of {@link sqlite3_vfs_layout}, such as
+ * `i(ppij)`: the result, then the parameters in parentheses. `i`, `p` and `s`
+ * are i32, `j` is i64 (a bigint), `d` is f64, and a `v` result is no result.
+ * The result is `i` or `v`, because every callback SQLite calls in this build
+ * returns an int or nothing.
+ */
+export interface SqliteWasmFunction {
+    readonly signature: string;
+    readonly fn: (...args: never) => number | void;
+}
+/** Functions installed by {@link installWasmFunctions}. */
+export interface SqliteWasmFunctions extends Disposable {
+    /** The functions' pointers, in the order they were given. */
+    readonly pointers: NonEmptyReadonlyArray<SqliteFunctionPtr>;
+}
+/**
+ * Installs functions into the function table.
+ *
+ * No engine exposes `WebAssembly.Function`, so a JavaScript function becomes a
+ * wasm function by being imported into a generated module that re-exports it.
+ * All functions of one call share one generated module. A call through one
+ * costs a few nanoseconds more than a call to a plain import, for the wrapper
+ * that catches exceptions: 12 ns against 9 ns in Node.js 24. A signature the
+ * notation does not cover throws. Compiling the generated module needs
+ * 'wasm-unsafe-eval' under a Content Security Policy; without it, this throws a
+ * `WebAssembly.CompileError`.
+ *
+ * No exception crosses into wasm. What a function throws is reported with
+ * {@link ReportDefect}, and the call returns SQLITE_ERROR, or nothing for a `v`
+ * result. So a commit hook rolls back, an `sqlite3_exec` callback aborts, and a
+ * VFS method fails, but a busy handler retries, forever if it always throws,
+ * and a SQL function's `xFunc` returns NULL. A function whose failure must mean
+ * something else catches its own errors, such as an `xFunc` calling
+ * `sqlite3_result_error`. An `i` function that returns something other than a
+ * number, or undefined for 0, is also reported as a defect and returns
+ * SQLITE_ERROR. Two kinds pass through, because they unwound C frames without
+ * cleanup: a `WebAssembly.RuntimeError`, which comes from a trap or a C stack
+ * overflow in wasm the function called, and anything thrown once the instance
+ * is broken, such as a JavaScript stack overflow that escaped a nested
+ * {@link SqliteWasm.call}. A function that returns once the instance is broken,
+ * as one that caught what a nested call rethrew, or whose ReportDefect broke
+ * it, throws the refusal of a broken instance instead, so SQLite never resumes
+ * on that state.
+ *
+ * Disposing the result empties its slots and keeps them for later installs, so
+ * per-database callbacks, such as an update hook, do not grow the table with
+ * each open. Dispose only once SQLite can no longer call the functions, for
+ * example after closing the database that holds them or replacing a hook: a
+ * call through an emptied slot traps, and a reused slot calls another function.
+ * A VFS's methods stay installed for the lifetime of the instance.
+ */
+export declare const installWasmFunctions: (deps: ReportDefectDep & SqliteWasmDep) => (functions: NonEmptyReadonlyArray<SqliteWasmFunction>) => SqliteWasmFunctions;
+//# sourceMappingURL=Wasm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Wasm.d.ts","sourceRoot":"","sources":["../../src/Wasm.ts"],"names":[],"mappings":"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"}