@yydb/yydb 0.0.17 → 0.1.0

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,6 +1,6 @@
 import { type EmittableItem } from '@voml/vos';
 import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from '../shared/micro.js';
-import { loadNative } from '../native/binding.js';
+import { loadNative, type NativeStatement as NativeStatementHandle } from '../native/binding.js';
 import type { UdfScalarDescriptor } from '../shared/udf-types.js';
 /** Published schema metadata. */
 export interface SchemaVersion {
@@ -75,6 +75,75 @@ 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;
+}
+/**
+ * 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
@@ -160,6 +229,25 @@ export declare class Database {
      * ```
      */
     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. */

package/dist/api/database.js

@@ -4,6 +4,69 @@ import { emitSource, } from '@voml/vos';
 import { defineMicro as buildMicro, microFingerprint, udfWireKind, MicroSessionRegistry, } from '../shared/micro.js';
 import { loadNative } from '../native/binding.js';
 import { YydbError } from '../shared/errors.js';
+/**
+ * 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 class Statement {
+    native;
+    db;
+    closed = false;
+    constructor(native, db) {
+        this.native = native;
+        this.db = db;
+    }
+    /** The fingerprint-prefixed unique id for this statement. */
+    get statementId() { return this.native.statementId(); }
+    /** Parameter descriptors — empty array when the statement takes no parameters. */
+    get parameters() {
+        return JSON.parse(this.native.parametersJson());
+    }
+    /** Full statement metadata. */
+    get info() {
+        return JSON.parse(this.native.info());
+    }
+    /** Whether this statement has been closed and can no longer execute. */
+    get isClosed() { return this.closed; }
+    /**
+     * 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.
+     */
+    async execute(params) {
+        if (this.closed) {
+            throw new YydbError('yydb.statement.closed', 'statement has been closed');
+        }
+        const paramsJson = params !== undefined && params !== null ? JSON.stringify(params) : null;
+        const rowsJson = this.db.queryPrepared(this.native, paramsJson);
+        return JSON.parse(rowsJson);
+    }
+    /** Release this statement's plan from the native registry. */
+    close() {
+        if (!this.closed) {
+            this.native.close();
+            this.closed = true;
+        }
+    }
+}
 /**
  * Transaction-local handle passed to {@link Database.transaction} callbacks.
  * All CRUD methods forward to the underlying native handle while the
@@ -195,6 +258,28 @@ export class Database {
             throw YydbError.fromDiagnosticJson(err instanceof Error ? err.message : String(err)) ?? err;
         }
     }
+    /**
+     * 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();
+     * ```
+     */
+    async prepare(source) {
+        const nativeStmt = this.native.prepare(source);
+        return new Statement(nativeStmt, this.native);
+    }
     /** Execute a VOS read pipeline and return typed rows. */
     async query(source) {
         const rowsJson = this.native.queryVos(source);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Database, type OpenOptions, type SchemaVersion } from './api/database.js';
+export { Database, Statement, type OpenOptions, type SchemaVersion, type ParameterDescriptor, type QueryKind, type SlotType, type StatementInfo } from './api/database.js';
 export { YydbError, YydbErrorCodes, YydbClientErrorCodes, isYydbError } from './shared/errors.js';
 export type { YydbErrorCode, YydbErrorOptions } from './shared/errors.js';
 export { defineMicro, type DefinedMicro, type MicroHandle, type TsMicroDefinitionInput, MicroSessionRegistry } from './shared/micro.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Database } from './api/database.js';
+export { Database, Statement } from './api/database.js';
 export { YydbError, YydbErrorCodes, YydbClientErrorCodes, isYydbError } from './shared/errors.js';
 export { defineMicro, MicroSessionRegistry } from './shared/micro.js';
 export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './native/resolve.js';

package/dist/native/binding.d.ts

@@ -36,6 +36,10 @@ export interface NativeDatabase {
     queryVos(source: string): string;
     /** Execute a VOS write program. */
     executeVosWrite(source: string): void;
+    /** Prepare a VOS read pipeline into a reusable plan; returns a native Statement handle. */
+    prepare(source: string): NativeStatement;
+    /** Execute a previously prepared statement with optional JSON parameters. */
+    queryPrepared(statement: NativeStatement, paramsJson?: string | null): string;
     /** Publish a new schema version, optionally with rename map. */
     migrateSchema(document: string, renamesJson?: string | null): void;
     /** Checkpoint + copy self-contained `.yydb` main file (no WAL sidecars). */
@@ -49,6 +53,17 @@ export interface NativeDatabase {
     registerMicro(name: string, version: number, args: string[], returns: string, hostId: number, functionId: string, handleVersion: number, fingerprint: Uint8Array): void;
     callScalar(name: string, version: number, argsJson: string): string;
 }
+/** A prepared VOS query plan handle exposed by the native binding. */
+export interface NativeStatement {
+    /** Fingerprint-prefixed unique id for this prepared statement. */
+    statementId(): string;
+    /** Parameter descriptors JSON — the `parameters` field from a `PreparedStatement`. */
+    parametersJson(): string;
+    /** Full statement metadata as JSON (statementId, queryKind, parameters, readSet, writeSet, sourceFingerprint, source). */
+    info(): string;
+    /** Release this statement's plan from the registry; returns true when actually removed. */
+    close(): boolean;
+}
 /** One remote `yydb serve` handle exposed by the native binding. */
 export interface NativeClient {
     endpoint(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yydb/yydb",
-  "version": "0.0.17",
+  "version": "0.1.0",
   "description": "YYDB Node embedded engine and CLI",
   "license": "MPL-2.0",
   "type": "module",
@@ -49,7 +49,7 @@
   "dependencies": {
     "@vmz/commander": "^0.3.5",
     "@vmz/diagnostic": "^0.3.5",
-    "@voml/vos": "^0.0.1"
+    "@voml/vos": "^0.0.5"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
@@ -59,9 +59,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@yydb/yydb-darwin-arm64": "0.0.17",
-    "@yydb/yydb-darwin-x64": "0.0.17",
-    "@yydb/yydb-linux-x64": "0.0.17",
-    "@yydb/yydb-win32-x64": "0.0.17"
+    "@yydb/yydb-darwin-arm64": "0.1.0",
+    "@yydb/yydb-darwin-x64": "0.1.0",
+    "@yydb/yydb-linux-x64": "0.1.0",
+    "@yydb/yydb-win32-x64": "0.1.0"
   }
 }