@yydb/light-db 0.0.17 → 0.1.0

package/dist/api/index.d.ts

@@ -1,14 +1,9 @@
 /**
  * api 层导出
  *
- * 主线是 {@link Database}（纯 TS，无 WASM 依赖，与 Node 侧 `@yydb/yydb` 同构）。
- * 需要 WASM 可选后端的宿主显式从 `./wasm-database` 引入 {@link WasmDatabase}。
+ * 唯一的生产路径：{@link Database}（WASM-backed，委托给
+ * `@yydb/yydb-unknown-wasm32` 的 Rust 语义核心）。
  */
-export { Database } from './database';
-export type { OpenOptions, ScanRow, ScanOptions, BatchChange, MigrateOptions, SchemaVersion } from './database';
-export { WasmDatabase, TransactionHandle, openLightDatabase } from './wasm-database';
-export { Transaction } from './transaction';
-export type { TransactionState } from './transaction';
-export { SCHEMA_KEY, RESERVED_KEY_PREFIX, documentVersion, parseSchemaDocument, encodeSchema, decodeSchema } from './schema';
-export type { LightDatabase, LightDatabaseOptions } from './types';
+export { Database, TransactionHandle, openLightDatabase } from './wasm-database';
+export type { BatchChange, LightDatabase, MigrateOptions, OpenOptions, ScanOptions, ScanRow, SchemaVersion, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7H,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEjF,YAAY,EACR,WAAW,EACX,aAAa,EACb,cAAc,EACd,WAAW,EACX,WAAW,EACX,OAAO,EACP,aAAa,GAChB,MAAM,SAAS,CAAC"}

package/dist/api/index.js

@@ -1,11 +1,8 @@
 /**
  * api 层导出
  *
- * 主线是 {@link Database}（纯 TS，无 WASM 依赖，与 Node 侧 `@yydb/yydb` 同构）。
- * 需要 WASM 可选后端的宿主显式从 `./wasm-database` 引入 {@link WasmDatabase}。
+ * 唯一的生产路径：{@link Database}（WASM-backed，委托给
+ * `@yydb/yydb-unknown-wasm32` 的 Rust 语义核心）。
  */
-export { Database } from './database';
-export { WasmDatabase, TransactionHandle, openLightDatabase } from './wasm-database';
-export { Transaction } from './transaction';
-export { SCHEMA_KEY, RESERVED_KEY_PREFIX, documentVersion, parseSchemaDocument, encodeSchema, decodeSchema } from './schema';
+export { Database, TransactionHandle, openLightDatabase } from './wasm-database';
 //# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAErF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/api/types.d.ts

@@ -1,61 +1,90 @@
 /**
- * 浏览器数据库作者面类型
+ * Browser database authoring-surface types.
  *
- * 这些类型是 `@yydb/light-db` 的稳定合同：二进制一律 `Uint8Array`，
- * 不出现本地路径、文件句柄或 Node 专属类型。
+ * These are the stable contract for `@yydb/light-db`:
+ * - Binary values are always `Uint8Array` — never `Buffer`.
+ * - No local file paths, file handles, or Node-exclusive types leak through.
+ * - Aligned with the Node-side `@yydb/yydb` method names and return semantics.
  */
-import type { LeaseMode } from '../core/lease';
-import type { CheckpointResult, StorageEngineStats } from '../core/engine';
-import type { StorageAdapterFactory } from '../storage/StorageAdapter';
-/** Schema 版本与文档，与 `@yydb/yydb` 同构 */
+/** Schema version and document (aligned with `@yydb/yydb`). */
 export interface SchemaVersion {
-    /** Schema 版本 */
     version: number;
-    /** Schema 文档全文 */
     document: string;
 }
-/** 打开数据库的选项 */
-export interface LightDatabaseOptions {
-    /** 页大小，默认 4KB */
-    pageSize?: number;
-    /** WAL 字节阈值，超过后自动检查点，默认 16MB */
-    walThreshold?: number;
-    /** 是否自动检查点，默认 true */
-    autoCheckpoint?: boolean;
-    /** 写租约模式，默认 `web-locks` */
-    lease?: LeaseMode;
-    /** 存储后端，默认 OPFS */
-    storage?: StorageAdapterFactory;
+/** One row from {@link Database.scan}. */
+export interface ScanRow {
+    key: string;
+    value: Uint8Array;
+}
+/** Options for {@link Database.scan}. */
+export interface ScanOptions {
+    /** Include this prefix in every returned key; default `""` returns everything. */
+    prefix?: string;
+    /** Exclusive continuation cursor from a previous scan's last row; default `null` starts fresh. */
+    after?: string | null;
+    /** Max rows returned per call; default `1000`. */
+    limit?: number;
+}
+/** One change in {@link Database.batch}. Use `null` to delete. */
+export interface BatchChange {
+    key: string;
+    value: Uint8Array | string | null;
+}
+/** Options for {@link Database.migrateSchema}. */
+export interface MigrateOptions {
+    /** Rename entries — `fromType`/`toType` updates a type name; `type`/`fromField`/`toField` updates one field. */
+    renames?: ReadonlyArray<{
+        fromType: string;
+        toType: string;
+    } | {
+        type: string;
+        fromField: string;
+        toField: string;
+    }>;
+}
+/** Options for opening the WASM-backed {@link Database}. */
+export interface OpenOptions {
+    /** Use an in-memory session (test only; default is OPFS persistent). */
+    memory?: boolean;
 }
 /**
- * 浏览器数据库
- *
- * 与 `@yydb/yydb` 的 TypeScript 作者面保持同一调用形态与返回语义。
+ * Light database contract — aligned with the Node-side `@yydb/yydb`.
+ * Only the WASM-backed {@link Database} implements this in production;
+ * the formerly pure-TS backend has been removed.
  */
 export interface LightDatabase {
-    /** 数据库名 */
+    /** Database name (OPFS path / namespace). */
     readonly name: string;
-    /** 读取已持久化的 schema */
-    schema(): Promise<SchemaVersion | null>;
-    /** 声明 schema 文档，文档是唯一真相 */
-    ensureSchema(document: string): Promise<void>;
-    /** 读取键 */
+    /** Engine version string. */
+    serverVersion(): string;
+    /** Basic diagnostics — session info from the engine. */
+    info(): string;
+    /** Published schema metadata, or `null` before the first schema. */
+    getSchema(): Promise<SchemaVersion | null>;
+    /**
+     * Validate and publish a VOS schema document. Accepts raw `.vos`
+     * source or `@voml/vos` descriptors (e.g. `v.table()`, `v.class()`).
+     */
+    ensureSchema(...input: [string] | object[]): Promise<void>;
+    /** Read one record, or `null`. */
     get(key: string): Promise<Uint8Array | null>;
-    /** 写入键 */
-    put(key: string, value: Uint8Array): Promise<void>;
-    /** 删除键，键存在时返回 true */
-    delete(key: string): Promise<boolean>;
-    /** 开启事务 */
+    /** Insert or replace one record. */
+    put(key: string, value: Uint8Array | string): Promise<void>;
+    /** Delete one record. Silently succeeds when absent. */
+    delete(key: string): Promise<void>;
+    /** Fold the WAL into the main storage. */
+    checkpoint(): Promise<void>;
+    /** Begin an explicit transaction. */
     begin(): Promise<void>;
-    /** 提交事务 */
+    /** Commit the current transaction. */
     commit(): Promise<void>;
-    /** 回滚事务 */
+    /** Roll back the current transaction. */
     rollback(): Promise<void>;
-    /** 执行检查点 */
-    checkpoint(): Promise<CheckpointResult>;
-    /** 数据库统计 */
-    stats(): StorageEngineStats;
-    /** 关闭数据库 */
+    /** Execute a VOS read pipeline. */
+    query<T = Record<string, unknown>>(source: string): Promise<T[]>;
+    /** Execute a VOS write program. */
+    execute(source: string): Promise<void>;
+    /** Close the session. Idempotent. */
     close(): Promise<void>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/api/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC1B,gBAAgB;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,eAAe;AACf,MAAM,WAAW,oBAAoB;IACjC,iBAAiB;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,mBAAmB;IACnB,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,WAAW;IACX,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,qBAAqB;IACrB,MAAM,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAExC,2BAA2B;IAC3B,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C,UAAU;IACV,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE7C,UAAU;IACV,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD,sBAAsB;IACtB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC,WAAW;IACX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,WAAW;IACX,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB,WAAW;IACX,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B,YAAY;IACZ,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAExC,YAAY;IACZ,KAAK,IAAI,kBAAkB,CAAC;IAE5B,YAAY;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,0CAA0C;AAC1C,MAAM,WAAW,OAAO;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,UAAU,CAAC;CACrB;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IACxB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC3B,gHAAgH;IAChH,OAAO,CAAC,EAAE,aAAa,CACjB;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACpC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CACzD,CAAC;CACL;AAED,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IACxB,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6BAA6B;IAC7B,aAAa,IAAI,MAAM,CAAC;IAExB,wDAAwD;IACxD,IAAI,IAAI,MAAM,CAAC;IAEf,oEAAoE;IACpE,SAAS,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAE3C;;;OAGG;IACH,YAAY,CAAC,GAAG,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D,kCAAkC;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE7C,oCAAoC;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D,wDAAwD;IACxD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,0CAA0C;IAC1C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,qCAAqC;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,sCAAsC;IACtC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB,yCAAyC;IACzC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B,mCAAmC;IACnC,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEjE,mCAAmC;IACnC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,qCAAqC;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/api/types.js

@@ -1,8 +1,10 @@
 /**
- * 浏览器数据库作者面类型
+ * Browser database authoring-surface types.
  *
- * 这些类型是 `@yydb/light-db` 的稳定合同：二进制一律 `Uint8Array`，
- * 不出现本地路径、文件句柄或 Node 专属类型。
+ * These are the stable contract for `@yydb/light-db`:
+ * - Binary values are always `Uint8Array` — never `Buffer`.
+ * - No local file paths, file handles, or Node-exclusive types leak through.
+ * - Aligned with the Node-side `@yydb/yydb` method names and return semantics.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/api/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/api/wasm-database.d.ts

@@ -1,10 +1,35 @@
+/**
+ * WASM-backed Database — the production path for `@yydb/light-db`.
+ *
+ * Delegates to `@yydb/yydb-unknown-wasm32`, which ships a Rust semantic
+ * core compiled to WebAssembly. This gives browser users the same VOS
+ * schema validation, transaction semantics, OPFS persistence and UDF
+ * execution as the Node-side `@yydb/yydb`.
+ *
+ * ```ts
+ * // Node
+ * import { Database } from '@yydb/yydb';
+ * const db = await Database.open('app.yydb');
+ *
+ * // Browser
+ * import { Database } from '@yydb/light-db';
+ * const db = await Database.open('app');
+ * ```
+ */
 import { type WasmSession } from '@yydb/yydb-unknown-wasm32';
 import { type EmittableItem } from '@voml/vos';
-import type { BatchChange, MigrateOptions, OpenOptions, ScanOptions, ScanRow, SchemaVersion } from './database.js';
-/** Transaction-local handle for callback-style transactions. */
+import { type DefinedMicro, type MicroHandle } from '../shared/micro.js';
+import type { BatchChange, LightDatabase, MigrateOptions, OpenOptions, ScanOptions, ScanRow, SchemaVersion } from './types.js';
+import type { InferUdfArgs, InferUdfReturn, UdfScalarDescriptor } from '../shared/udf-types.js';
+/**
+ * Transaction-local handle passed to {@link Database.transaction} callbacks.
+ * All methods forward to the underlying WASM session; commit/rollback are
+ * owned by {@link Database.transaction}.
+ */
 export declare class TransactionHandle {
     private readonly session;
     constructor(session: WasmSession);
+    /** Parse a WASM envelope, converting `{ ok: false, error }` to a thrown error. */
     private parseResult;
     get(key: string): Promise<Uint8Array | null>;
     put(key: string, value: Uint8Array | string): Promise<void>;
@@ -16,49 +41,131 @@ export declare class TransactionHandle {
     execute(source: string): Promise<void>;
 }
 /**
- * Browser/WASM 侧 YYDB 数据库句柄（可选后端）。
+ * Browser-local YYDB handle.
  *
- * 这是 `@yydb/light-db` 的 WASM 路径。默认可选——包主线是 {@link Database}
- * （`api/database.ts`，纯 TS，无 WASM 依赖），宿主按需显式 import 本文件以引入 WASM。
+ * This is the main {@link Database} export of `@yydb/light-db`. It owns a
+ * Rust-backed WASM session (memory or OPFS) and exposes the same user API
+ * as the Node-side `@yydb/yydb`.
  */
-export declare class WasmDatabase {
-    /** 数据库名（OPFS 路径）。 */
+export declare class Database implements LightDatabase {
+    /** Database name (OPFS path). */
     readonly name: string;
     private readonly session;
+    private readonly registry;
     private constructor();
-    /** 初始化 WASM 并打开一个 session（memory 或 OPFS persistent）。 */
-    static open(name: string, options?: OpenOptions): Promise<WasmDatabase>;
-    /** 解析 WASM JSON 结果，失败时转 LightDbError。 */
+    /**
+     * Initialize WASM and open a session (in-memory or OPFS persistent).
+     *
+     * @param name Database name. Persistent sessions use it as the OPFS path.
+     * @param options Open options — pass `{ memory: true }` for a transient session.
+     */
+    static open(name: string, options?: OpenOptions): Promise<Database>;
+    /** Parse a WASM envelope, converting `{ ok: false, error }` to a thrown error. */
     private parseResult;
-    /** 读取已持久化的 schema，或 `null`。 */
+    /** Engine version string (same as `@yydb/yydb` semver). */
+    serverVersion(): string;
+    /** Basic diagnostics: session info from the WASM core. */
+    info(): string;
+    /** Published schema metadata, or `null` before the first schema. */
     getSchema(): Promise<SchemaVersion | null>;
-    /** 声明 schema 文档。 */
+    /**
+     * Validate and publish a VOS schema document.
+     *
+     * Accepts either a raw `.vos` source string, or `@voml/vos` descriptors
+     * (`v.table()`, `v.class()`). When descriptors are supplied, they are
+     * rendered to source via `emitSource` before being handed to the Rust
+     * core for validation.
+     */
     ensureSchema(...input: [string] | EmittableItem[]): Promise<void>;
-    /** 读取键，或 `null`。 */
+    /** Read one record, or `null`. */
     get(key: string): Promise<Uint8Array | null>;
-    /** 写入键。 */
+    /** Insert or replace one record. */
     put(key: string, value: Uint8Array | string): Promise<void>;
-    /** 删除键。 */
+    /** Delete one record. Silently succeeds when the key is absent. */
     delete(key: string): Promise<void>;
-    /** 扫描键值对。 */
+    /** List key/value pairs in lexical order. */
     scan(options?: ScanOptions): Promise<ScanRow[]>;
-    /** 原子批量写入/删除。 */
+    /** Atomically write or delete many keys in one call. */
     batch(changes: readonly BatchChange[]): Promise<void>;
-    /** Compare-and-swap。 */
+    /**
+     * Compare-and-swap: replace or delete `key` only when its current value
+     * exactly equals `expected`. Both may be `null` (meaning absent / delete).
+     */
     compareExchange(key: string, expected: Uint8Array | string | null, replacement: Uint8Array | string | null): Promise<boolean>;
-    /** Callback-style 事务：自动 begin/commit，异常自动 rollback。 */
+    /** Fold the WAL into the main storage. */
+    checkpoint(): Promise<void>;
+    /** Begin an explicit transaction. Balanced with {@link commit} or {@link rollback}. */
+    begin(): Promise<void>;
+    /** Commit the current transaction. */
+    commit(): Promise<void>;
+    /** Roll back the current transaction. */
+    rollback(): Promise<void>;
+    /**
+     * Run `fn` inside an explicit transaction. Commits on normal return,
+     * rolls back on throw. Nested calls are not supported.
+     */
     transaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
-    /** 执行 VOS read pipeline，返回 typed rows。 */
+    /** Execute a VOS read pipeline and return typed rows. */
     query<T = Record<string, unknown>>(source: string): Promise<T[]>;
-    /** 执行 VOS write program。 */
+    /** Execute a VOS write program. */
     execute(source: string): Promise<void>;
-    /** 发布新 schema 版本。 */
+    /**
+     * Publish a new schema version, migrating existing records when their
+     * shape no longer matches. Accepts raw `.vos` source or descriptors.
+     */
     migrateSchema(documentOrSource: string | EmittableItem, ...rest: (EmittableItem | MigrateOptions)[]): Promise<void>;
-    /** 执行检查点（折叠 WAL）。 */
-    checkpoint(): Promise<void>;
-    /** 关闭 session。 */
+    /**
+     * Override the host micro invoker.
+     *
+     * The constructor wires this to the per-session {@link MicroSessionRegistry}
+     * so that high-level {@link registerMicro} + {@link callScalar} works out of
+     * the box. Call this only if you need to replace the default resolution
+     * logic (e.g. to inject a mock invoker in tests).
+     */
+    overrideMicroHostInvoker(invoker: (payload: {
+        hostId: number;
+        handleVersion: number;
+        functionId: string;
+        args: readonly unknown[];
+    }) => unknown): void;
+    /**
+     * Build a typed session-local micro definition without registering it.
+     *
+     * Same signature as the Node-side `@yydb/yydb`; this is a thin alias
+     * over the shared `defineMicro` helper so author code stays portable.
+     */
+    defineMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(input: {
+        readonly name: string;
+        readonly version: number;
+        readonly args: TArgs;
+        readonly returns: TReturn;
+        readonly effect: 'pure';
+        readonly deterministic: boolean;
+        readonly mode?: 'scalar';
+        readonly fn: (...args: InferUdfArgs<TArgs>) => InferUdfReturn<TReturn>;
+    }): DefinedMicro<TArgs, TReturn>;
+    /**
+     * Install a session-local host micro into both the JS registry and the
+     * WASM core. Host micros never persist across sessions.
+     *
+     * Uses the high-level JSON bridge (`registerMicroJson`) so we never
+     * encode wire bodies in TS; Rust owns the protocol.
+     */
+    registerMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: DefinedMicro<TArgs, TReturn>): Promise<MicroHandle>;
+    /**
+     * Invoke a registered scalar UDF via the WASM core.
+     *
+     * Uses the high-level JSON bridge (`callScalarJson`) — args are encoded
+     * as plain JSON scalars (`number`, `string`, `boolean`, `null`).
+     */
+    callScalar(name: string, version: number, args: readonly (string | number | boolean | null)[]): Promise<string | number | boolean | null>;
+    /**
+     * Close the session. Idempotent — further calls fail.
+     *
+     * On persistent (OPFS) sessions this triggers a final snapshot publish.
+     */
     close(): Promise<void>;
 }
-/** 打开浏览器 WASM 数据库的便捷函数（等价于 {@link WasmDatabase.open}）。 */
-export declare function openLightDatabase(name: string, options?: OpenOptions): Promise<WasmDatabase>;
+/** Open a browser database — convenience alias for {@link Database.open}. */
+export declare function openLightDatabase(name: string, options?: OpenOptions): Promise<Database>;
 //# sourceMappingURL=wasm-database.d.ts.map

package/dist/api/wasm-database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wasm-database.d.ts","sourceRoot":"","sources":["../../src/api/wasm-database.ts"],"names":[],"mappings":"AAAA,OAAO,EAIH,KAAK,WAAW,EACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAanH,gEAAgE;AAChE,qBAAa,iBAAiB;IACd,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,WAAW;IAEjD,OAAO,CAAC,WAAW;IASb,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAQ5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IASnD,KAAK,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD,eAAe,CACjB,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,EAAE,WAAW,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,GAC3F,OAAO,CAAC,OAAO,CAAC;IAQb,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAMhE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG/C;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IACrB,qBAAqB;IACrB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IAEtC,OAAO;IAKP,wDAAwD;WACpC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAcxF,yCAAyC;IACzC,OAAO,CAAC,WAAW;IASnB,+BAA+B;IAClB,SAAS,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAMvD,oBAAoB;IACP,YAAY,CAAC,GAAG,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9E,oBAAoB;IACP,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAQzD,WAAW;IACE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxE,WAAW;IACE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,aAAa;IACA,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAahE,iBAAiB;IACJ,KAAK,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlE,wBAAwB;IACX,eAAe,CACxB,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,EAAE,WAAW,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,GAC3F,OAAO,CAAC,OAAO,CAAC;IAQnB,uDAAuD;IAC1C,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiBlF,0CAA0C;IAC7B,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAM7E,4BAA4B;IACf,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,qBAAqB;IACR,aAAa,CACtB,gBAAgB,EAAE,MAAM,GAAG,aAAa,EACxC,GAAG,IAAI,EAAE,CAAC,aAAa,GAAG,cAAc,CAAC,EAAE,GAC5C,OAAO,CAAC,IAAI,CAAC;IAsBhB,qBAAqB;IACR,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxC,kBAAkB;IACL,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGtC;AAED,0DAA0D;AAC1D,wBAAsB,iBAAiB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAEvB"}
+{"version":3,"file":"wasm-database.d.ts","sourceRoot":"","sources":["../../src/api/wasm-database.ts"],"names":[],"mappings":"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"}