@yydb/yydb 0.1.1 → 0.1.2

package/README.md

@@ -17,10 +17,15 @@ For a wire client only (renderer or an app that already runs `yydb serve`), use
 | Import | Runtime | Role |
 |--------|---------|------|
 | `@yydb/yydb` | Node | `Database.open`, micro helpers, VOS re-exports |
-| `@yydb/yydb/cli` | Node | CLI (`version`, `init`, `info`, `serve`) |
+| `@yydb/yydb/cli` | Node | CLI (`version`, `init`, `info`, `verify`, `serve`) |
 
 Node.js 18+.
 
+```bash
+npm install @yydb/yydb
+npx yydb version
+```
+
 Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents.
 
 ## Example
@@ -65,6 +70,21 @@ await db.close();
 `OpenOptions`: `cli` (explicit CLI script path), `port` (preferred loopback port), `serveArgs` (extra `yydb serve`
 arguments). `binary` is a deprecated alias for `cli`.
 
+### Prepared statements
+
+`db.prepare` parses and lowers a VOS query once; the plan stays in a native thread-local registry and re-executes
+with different bindings.
+
+```ts
+const stmt = await db.prepare('User.all().take($limit).collect()');
+const rows = await stmt.execute({ limit: 100 });
+const more = await stmt.execute({ limit: 50 });
+stmt.close();
+```
+
+`stmt.parameters` lists the expected bindings, and `stmt.info` exposes the read/write sets and source fingerprint.
+Missing, extra, or mistyped parameters raise `YydbError` with code `yydb.query.bind`.
+
 The native binding exposes additive operations (`schemaVersion`, `schemaDocument`, `recordCount`, `journalMode`,
 `checkpoint`, `walFrameCount`, `get`, `put`); the CLI composes commands from them.
 
@@ -73,7 +93,7 @@ The native binding exposes additive operations (`schemaVersion`, `schemaDocument
 | Need | Package |
 |------|---------|
 | Node embedded engine and CLI (this package) | **`@yydb/yydb`** |
-| Browser, pure TypeScript | **`@yydb/light-db`** |
+| Browser engine (pure TS and WASM sessions) | **`@yydb/light-db`** |
 | Wire client only | [`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client) |
 | In-process Rust embed | [`yydb`](https://crates.io/crates/yydb) |
 | Agent skills (wire protocol) | [`@yydb/yydb-skills`](https://www.npmjs.com/package/@yydb/yydb-skills) |
@@ -83,4 +103,4 @@ endpoint.
 
 The managed engine listens on `127.0.0.1` with no authentication — keep the endpoint private.
 
-[YYDB overview](https://github.com/yy-database/yydb.rs) · [User guides](https://github.com/yy-database/yydb.rs/tree/dev/projects/packages/homepage/documentation/zh-hans)
+[YYDB overview](https://github.com/yy-database/yydb) · [User guides](https://github.com/yy-database/yydb/tree/dev/projects/packages/homepage/documentation/zh-hans)

package/dist/api/database.d.ts

@@ -1,50 +1,276 @@
+import { type EmittableItem } from '@voml/vos';
 import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from '../shared/micro.js';
+import { loadNative, type NativeStatement as NativeStatementHandle } from '../native/binding.js';
 import type { UdfScalarDescriptor } from '../shared/udf-types.js';
-export type { SchemaVersion } from '@yydb/yydb-client';
+/** Published schema metadata. */
+export interface SchemaVersion {
+    version: number;
+    document: string;
+}
+/** Options for opening a local YYDB file. */
 export interface OpenOptions {
-    /** Override CLI script path (tests / special installs). */
-    cli?: string;
-    /** @deprecated Use `cli`. */
-    binary?: string;
-    /** Prefer a specific loopback port; default = ephemeral free port. */
-    port?: number;
-    /** Extra args after `serve <path> --bind …`. */
-    serveArgs?: string[];
+    /** Create parent directories when missing (default: true). */
+    mkdir?: boolean;
+}
+/** One row from a {@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 a {@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;
+    }>;
+}
+/** One consistency finding from {@link Database.doctor}. */
+export interface DoctorIssue {
+    severity: 'warn' | 'error';
+    code: string;
+    message: string;
+    key_hint?: string | null;
+}
+/** Per-namespace usage snapshot from {@link Database.doctor}. */
+export interface DoctorNamespaceStats {
+    prefix: string;
+    record_count: number;
+    bytes_used: number;
+    object_bytes: number;
+    quota_max_bytes?: number | null;
+    ttl_expired_pending: number;
+}
+/** Read-only consistency report. */
+export interface DoctorReport {
+    file_path?: string | null;
+    last_commit_sequence: number;
+    last_checkpoint_sequence: number;
+    checkpoint_lag_records: number;
+    wal_bytes_uncheckpointed: number;
+    orphan_object_count: number;
+    namespaces: DoctorNamespaceStats[];
+    issues: DoctorIssue[];
+}
+/** Summary of a v0 `.yydx` compaction pass. */
+export interface CompactReport {
+    checkpointed: boolean;
+    orphans_reclaimed: number;
+}
+/** Declared type for a prepared statement parameter slot. */
+export type SlotType = 'any' | 'bool' | 'i64' | 'text' | 'null';
+/** One named parameter descriptor on a {@link Statement}. */
+export interface ParameterDescriptor {
+    /** Canonical parameter name (no leading `$`). */
+    name: string;
+    /** Positional slot index within the bound-value slice (0-based). */
+    index: number;
+    /** Declared slot type; narrowed from surrounding context when possible. */
+    slotTy: SlotType;
+    /** Number of times this parameter appears in the source. */
+    usageCount: number;
+}
+/** Whether a prepared statement is a read pipeline or a write program. */
+export type QueryKind = 'Read' | 'Write';
+/** Metadata about a prepared statement — useful for logging and cache keys. */
+export interface StatementInfo {
+    statementId: string;
+    queryKind: QueryKind;
+    parameters: ParameterDescriptor[];
+    readSet: string[];
+    writeSet: string[];
+    sourceFingerprint: string;
+    source: string;
 }
 /**
- * Node-facing YYDB handle. Looks like one library; owns a private loopback
- * `yydb serve` child under the hood.
+ * A pre-parsed, pre-lowered VOS query plan.
+ *
+ * Created by {@link Database.prepare}. The actual lowered op tree lives on
+ * the native side in a thread-local registry keyed by `statementId`; this
+ * class is a thin JS handle. Bind parameters and re-execute via
+ * {@link Statement.execute} without re-parsing or re-lowering the source.
+ *
+ * ```ts
+ * const stmt = await db.prepare('User.all().take($limit).collect()');
+ * const rows = await stmt.execute({ limit: 100 });
+ * // re-execute with different bind
+ * const rows2 = await stmt.execute({ limit: 50 });
+ * // release when done
+ * stmt.close();
+ * ```
+ */
+export declare class Statement {
+    private readonly native;
+    private readonly db;
+    private closed;
+    constructor(native: NativeStatementHandle, db: unknown);
+    /** The fingerprint-prefixed unique id for this statement. */
+    get statementId(): string;
+    /** Parameter descriptors — empty array when the statement takes no parameters. */
+    get parameters(): ParameterDescriptor[];
+    /** Full statement metadata. */
+    get info(): StatementInfo;
+    /** Whether this statement has been closed and can no longer execute. */
+    get isClosed(): boolean;
+    /**
+     * Execute this prepared statement with optional named parameter bindings.
+     *
+     * Missing parameters, extraneous parameters or mistyped parameters raise
+     * `YydbError` with code `yydb.query.bind`.
+     *
+     * @param params Named parameter values — keys match the parameter names
+     * in the VOS source (`$name` → `{ name: value }`). Omit when the statement
+     * takes no parameters.
+     */
+    execute<T = Record<string, unknown>>(params?: Record<string, unknown>): Promise<T[]>;
+    /** Release this statement's plan from the native registry. */
+    close(): void;
+}
+/**
+ * Transaction-local handle passed to {@link Database.transaction} callbacks.
+ * All CRUD methods forward to the underlying native handle while the
+ * transaction is in flight. Commit/rollback are owned by {@link Database}.
+ */
+export declare class TransactionHandle {
+    private readonly native;
+    constructor(native: ReturnType<ReturnType<typeof loadNative>['Database']['open']>);
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array | string): Promise<void>;
+    delete(key: string): Promise<void>;
+    scan(options?: ScanOptions): Promise<ScanRow[]>;
+    batch(changes: readonly BatchChange[]): Promise<void>;
+    compareExchange(key: string, expected: Uint8Array | string | null, replacement: Uint8Array | string | null): Promise<boolean>;
+    query<T = Record<string, unknown>>(source: string): Promise<T[]>;
+    execute(source: string): Promise<void>;
+}
+/**
+ * Node-facing YYDB local database handle.
+ *
+ * Directly owns a native `yydb::Connection` via the Node-API binding. No
+ * child process, no loopback TCP, no wire protocol in the hot path.
  */
 export declare class Database {
     readonly path: string;
-    readonly endpoint: string;
-    private client;
-    private child;
+    private readonly native;
     private readonly microRegistry;
     private constructor();
+    /** Open (create when missing) the database at `dbPath`. */
+    static open(dbPath: string, options?: OpenOptions): Promise<Database>;
+    /** Engine version string (same as `yydb --version`). */
+    serverVersion(): string;
+    /** Basic diagnostics: path, schema, record count, journal mode. */
+    info(): string;
+    /** Published schema metadata, or `null` before the first schema. */
+    getSchema(): Promise<{
+        version: number;
+        document: string;
+    } | null>;
     /**
-     * Open (create) a `.yydb` file. Spawns the engine on `127.0.0.1` automatically.
+     * Validate and publish a VOS schema document.
+     *
+     * Accepts either a raw `.vos` source string, one `@voml/vos` descriptor
+     * (`v.table()`, `v.class()`) or a list of descriptors. When descriptors
+     * are supplied, they are rendered to source via `emitSource` first.
      */
-    static open(dbPath: string, options?: OpenOptions): Promise<Database>;
-    serverVersion(): Promise<string>;
-    info(): Promise<string>;
-    getSchema(): Promise<import("@yydb/yydb-client").SchemaVersion | null>;
-    ensureSchema(version: number, document: string): Promise<void>;
+    ensureSchema(...input: [string] | [string, ...EmittableItem[]] | EmittableItem[]): Promise<void>;
+    /** Read one record, or `null` when the key is absent. */
     get(key: string): Promise<Uint8Array | null>;
+    /** Insert or replace one record. */
     put(key: string, value: Uint8Array | string): Promise<void>;
+    /** Delete one record by key. Silently succeeds when the key is absent. */
+    delete(key: string): Promise<void>;
+    /** List key/value pairs in lexical order. `prefix` defaults to `""` (all keys). */
+    scan(options?: ScanOptions): Promise<ScanRow[]>;
+    /** Atomically write or delete many keys in one call. */
+    batch(changes: readonly BatchChange[]): Promise<void>;
+    /**
+     * Compare-and-swap: replace or delete `key` only when its current value
+     * exactly equals `expected`. Both `expected` and `replacement` may be
+     * `null` (meaning absent / delete). Returns `true` when the swap applied.
+     */
+    compareExchange(key: string, expected: Uint8Array | string | null, replacement: Uint8Array | string | null): Promise<boolean>;
+    /** Fold the WAL into the main file and truncate the sidecar. */
+    checkpoint(): Promise<void>;
+    /** Checkpoint then copy a self-contained `.yydb` main file to `dest`. */
+    backup(dest: string): Promise<void>;
+    /** Copy main + WAL + SHM without checkpoint; opening `dest` replays the WAL tail. */
+    backupWithWal(dest: string): Promise<void>;
+    /** Run read-only consistency probes against the database. */
+    doctor(): Promise<DoctorReport>;
+    /** Fold WAL + reclaim orphan blobs (`.yydx` layouts only). */
+    compactYydx(): Promise<CompactReport>;
+    /**
+     * Run `fn` inside an explicit transaction. The transaction commits on
+     * normal return and rolls back on throw. Nested calls are not supported.
+     *
+     * ```ts
+     * await db.transaction(async (tx) => {
+     *     await tx.put('a', '1');
+     *     await tx.put('b', '2');
+     * });
+     * ```
+     */
+    transaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+    /**
+     * Prepare a VOS read pipeline into a reusable query plan.
+     *
+     * Returns a {@link Statement} handle. The actual lowered op tree lives
+     * on the native side in a thread-local registry — you can call
+     * `statement.execute({ paramName: value })` cheaply multiple times
+     * without re-parsing or re-lowering the source.
+     *
+     * Prepare requires no schema binding; plan building is a pure parse +
+     * lower pass. Execute still needs `ensureSchema` first.
+     *
+     * ```ts
+     * const stmt = await db.prepare('User.all().take($limit).collect()');
+     * const rows = await stmt.execute({ limit: 100 });
+     * const rows2 = await stmt.execute({ limit: 50 });
+     * stmt.close();
+     * ```
+     */
+    prepare(source: string): Promise<Statement>;
+    /** Execute a VOS read pipeline and return typed rows. */
+    query<T = Record<string, unknown>>(source: string): Promise<T[]>;
+    /** Execute a VOS write program. */
+    execute(source: string): Promise<void>;
     /**
-     * Build a typed session-local micro definition. Does not register it with
-     * the engine until [`registerMicro`](./database.ts) is called.
+     * Publish a new schema version, migrating existing records when their
+     * shape no longer matches.
+     *
+     * Accepts raw `.vos` source or `@voml/vos` descriptors (same as
+     * {@link Database.ensureSchema}). Use `renames` to tell the engine which
+     * old type/field names map to the new ones — records that would otherwise
+     * look structurally unrelated get preserved.
      */
+    migrateSchema(documentOrSource: string | EmittableItem, ...rest: (EmittableItem | MigrateOptions)[]): Promise<void>;
+    /** Build a typed session-local micro definition (without registering). */
     defineMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: Parameters<typeof buildMicro<TArgs, TReturn>>[0]): DefinedMicro<TArgs, TReturn>;
     /**
-     * Install a [`defineMicro`](./database.ts) definition into the current
-     * session registry and sync metadata to the private engine. Host micros are
-     * session-local and never written to `.yydb`.
+     * Install a session-local host micro into both the local registry and the
+     * native engine. Host micros never persist across processes.
      */
     registerMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: DefinedMicro<TArgs, TReturn>): Promise<MicroHandle>;
-    /** Invoke a registered scalar UDF on the private engine. */
+    /** Invoke a registered scalar UDF on the native engine. */
     callScalar(name: string, version: number, args: readonly (string | number | boolean | null)[]): Promise<string | number | boolean | null>;
-    /** Stop the private engine process. */
+    /** Release the native handle (best-effort; the engine also drops on GC). */
     close(): Promise<void>;
 }