@yydb/yydb 0.0.12 → 0.0.15

package/README.md

@@ -1,86 +1,86 @@
-# `@yydb/yydb`
-
-Node embedded engine and CLI. `Database.open` starts a private loopback `yydb serve` process and talks over the YY
-wire protocol; platform `.node` bindings install through optional dependencies.
-
-Browsers are served by the pure TypeScript [`@yydb/light-db`](../light-db/readme.md) package. This package no longer
-ships a WebAssembly entry.
-
-For a wire client only (renderer or an app that already runs `yydb serve`), use
-[`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client).
-
-[![npm](https://img.shields.io/npm/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
-[![Node.js](https://img.shields.io/node/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
-
-## Exports
-
-| Import | Runtime | Role |
-|--------|---------|------|
-| `@yydb/yydb` | Node | `Database.open`, micro helpers, VOS re-exports |
-| `@yydb/yydb/cli` | Node | CLI (`version`, `init`, `info`, `serve`) |
-
-Node.js 18+.
-
-Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents.
-
-## Example
-
-```ts
-import { Database } from '@yydb/yydb';
-
-const db = await Database.open('./data/app.yydb');
-
-await db.ensureSchema(
-    1,
-    `table Setting {
-        @@id: uuid,
-        key: utf8,
-        value: utf8,
-    }`,
-);
-
-await db.put('theme', 'dark');
-console.log(await db.get('theme'));
-await db.close();
-```
-
-The file is created when missing. Schema version and VOS document persist with the data.
-
-## API
-
-```ts
-const db = await Database.open(path, options?);
-
-await db.ensureSchema(version, vosDocument);
-await db.getSchema();
-await db.put(key, stringOrBytes);
-await db.get(key);
-await db.info();
-await db.serverVersion();
-await db.registerMicro(microDefinition);
-await db.callScalar('double', 1, [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`.
-
-The native binding exposes additive operations (`schemaVersion`, `schemaDocument`, `recordCount`, `journalMode`,
-`checkpoint`, `walFrameCount`, `get`, `put`); the CLI composes commands from them.
-
-## Related packages
-
-| Need | Package |
-|------|---------|
-| Node embedded engine and CLI (this package) | **`@yydb/yydb`** |
-| Browser, pure TypeScript | **`@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) |
-
-Electron: main process can use `@yydb/yydb`; renderer code can use `@yydb/yydb-client` against the main-process
-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/yydb`
+
+Node embedded engine and CLI. `Database.open` starts a private loopback `yydb serve` process and talks over the YY
+wire protocol; platform `.node` bindings install through optional dependencies.
+
+Browsers are served by the pure TypeScript [`@yydb/light-db`](../light-db/readme.md) package. This package no longer
+ships a WebAssembly entry.
+
+For a wire client only (renderer or an app that already runs `yydb serve`), use
+[`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client).
+
+[![npm](https://img.shields.io/npm/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
+[![Node.js](https://img.shields.io/node/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
+
+## Exports
+
+| Import | Runtime | Role |
+|--------|---------|------|
+| `@yydb/yydb` | Node | `Database.open`, micro helpers, VOS re-exports |
+| `@yydb/yydb/cli` | Node | CLI (`version`, `init`, `info`, `serve`) |
+
+Node.js 18+.
+
+Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents.
+
+## Example
+
+```ts
+import { Database } from '@yydb/yydb';
+
+const db = await Database.open('./data/app.yydb');
+
+await db.ensureSchema(
+    1,
+    `table Setting {
+        @@id: uuid,
+        key: utf8,
+        value: utf8,
+    }`,
+);
+
+await db.put('theme', 'dark');
+console.log(await db.get('theme'));
+await db.close();
+```
+
+The file is created when missing. Schema version and VOS document persist with the data.
+
+## API
+
+```ts
+const db = await Database.open(path, options?);
+
+await db.ensureSchema(version, vosDocument);
+await db.getSchema();
+await db.put(key, stringOrBytes);
+await db.get(key);
+await db.info();
+await db.serverVersion();
+await db.registerMicro(microDefinition);
+await db.callScalar('double', 1, [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`.
+
+The native binding exposes additive operations (`schemaVersion`, `schemaDocument`, `recordCount`, `journalMode`,
+`checkpoint`, `walFrameCount`, `get`, `put`); the CLI composes commands from them.
+
+## Related packages
+
+| Need | Package |
+|------|---------|
+| Node embedded engine and CLI (this package) | **`@yydb/yydb`** |
+| Browser, pure TypeScript | **`@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) |
+
+Electron: main process can use `@yydb/yydb`; renderer code can use `@yydb/yydb-client` against the main-process
+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)

package/dist/api/database.d.ts

@@ -43,6 +43,38 @@ export interface MigrateOptions {
         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;
+}
 /**
  * Transaction-local handle passed to {@link Database.transaction} callbacks.
  * All CRUD methods forward to the underlying native handle while the
@@ -108,6 +140,14 @@ export declare class Database {
     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.

package/dist/api/database.js

@@ -150,6 +150,22 @@ export class Database {
     async checkpoint() {
         this.native.checkpoint();
     }
+    /** Checkpoint then copy a self-contained `.yydb` main file to `dest`. */
+    async backup(dest) {
+        this.native.backup(dest);
+    }
+    /** Copy main + WAL + SHM without checkpoint; opening `dest` replays the WAL tail. */
+    async backupWithWal(dest) {
+        this.native.backupWithWal(dest);
+    }
+    /** Run read-only consistency probes against the database. */
+    async doctor() {
+        return JSON.parse(this.native.doctor());
+    }
+    /** Fold WAL + reclaim orphan blobs (`.yydx` layouts only). */
+    async compactYydx() {
+        return JSON.parse(this.native.compactYydx());
+    }
     /**
      * Run `fn` inside an explicit transaction. The transaction commits on
      * normal return and rolls back on throw. Nested calls are not supported.

package/dist/cli/cli.js

@@ -1,16 +1,22 @@
-import { dirname, join } from 'node:path';
+import fs from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createCli } from '@vmz/commander';
+import { formatDiagnostic } from '@vmz/diagnostic';
+import { YydbError } from '../shared/errors.js';
 import { registerInfoCommand } from './info-cmd.js';
 import { registerInitCommand } from './init-cmd.js';
 import { registerServeCommand } from './serve-cmd.js';
+import { registerVerifyCommand } from './verify-cmd.js';
 import { registerVersionCommand } from './version-cmd.js';
+const CLI_CATALOG = JSON.parse(fs.readFileSync(resolve(import.meta.dirname, '../../locales/en-US/cli.json'), 'utf8'));
 function buildYydbCli() {
     const localesRoot = join(dirname(fileURLToPath(import.meta.url)), '../../locales');
     const cli = createCli('yydb').locales(localesRoot).intro('cli.intro');
     registerVersionCommand(cli);
     registerInitCommand(cli);
     registerInfoCommand(cli);
+    registerVerifyCommand(cli);
     registerServeCommand(cli);
     return cli;
 }
@@ -19,6 +25,27 @@ export async function runCli(argv) {
         return await buildYydbCli().parse(argv);
     }
     catch (error) {
+        const parsed = error instanceof Error
+            ? YydbError.fromDiagnosticJson(error.message)
+            : null;
+        if (parsed) {
+            // Structured engine error from N-API / wire / WASM envelope.
+            const severity = parsed.retryable ? 'warning' : 'error';
+            const text = formatDiagnostic({
+                path: '',
+                severity,
+                code: parsed.code,
+                args: parsed.params,
+                message: error instanceof Error ? error.message : String(error),
+            }, {
+                locale: 'en-US',
+                catalog: CLI_CATALOG,
+                style: 'compact',
+            });
+            console.error(text);
+            return parsed.retryable ? 13 : 1;
+        }
+        // Plain text fallback (commander parse failures, unknown errors).
         console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
         return 1;
     }

package/dist/cli/info-cmd.js

@@ -1,10 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatDiagnostic } from '@vmz/diagnostic';
 import { loadNative } from '../native/binding.js';
 import { requiredPositional } from './options.js';
+const CLI_CATALOG = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, '../../locales/en-US/cli.json'), 'utf8'));
 export function registerInfoCommand(cli) {
-    cli.command('info', 'cli.cmd.info').action((options) => cmdInfo(options));
+    cli.command('info', 'cli.cmd.info')
+        .option('--doctor', 'cli.opt.doctor')
+        .action((options) => cmdInfo(options));
 }
 export function cmdInfo(options) {
     const dbPath = requiredPositional(options, 'info');
+    const wantDoctor = Boolean(options.doctor);
     const database = loadNative().Database.open(dbPath);
     const lines = [`path=${database.path() ?? '<memory>'}`];
     const schemaVersion = database.schemaVersion();
@@ -25,6 +32,28 @@ export function cmdInfo(options) {
         lines.push(`shm=${shm}`);
     lines.push(`wal_frames=${database.walFrameCount()}`);
     console.log(lines.join('\n'));
+    if (wantDoctor) {
+        const report = JSON.parse(database.doctor());
+        if (report.issues.length === 0) {
+            console.log(`doctor=clean orphan_objects=${report.orphan_object_count}`);
+        }
+        else {
+            for (const issue of report.issues) {
+                const severity = issue.severity === 'error' ? 'error' : 'warning';
+                console.error(formatDiagnostic({
+                    path: dbPath,
+                    severity,
+                    code: issue.code,
+                    message: issue.message,
+                }, {
+                    locale: 'en-US',
+                    catalog: CLI_CATALOG,
+                    style: 'compact',
+                }));
+            }
+            console.error(`doctor=issues(${report.issues.length}) orphans=${report.orphan_object_count}`);
+        }
+    }
     return 0;
 }
 function summarizeDocument(document) {

package/dist/cli/verify-cmd.d.ts

@@ -0,0 +1,11 @@
+import type { Cli, ParsedOptions } from '@vmz/commander';
+export declare function registerVerifyCommand(cli: Cli): void;
+/**
+ * Run read-only consistency probes against a YYDB database file.
+ *
+ * Exit codes:
+ *   0  — clean (no issues)
+ *   1  — doctor found at least one error (database may be corrupt)
+ *   13 — only warnings present (readable but should be inspected)
+ */
+export declare function cmdVerify(options: ParsedOptions): number;

package/dist/cli/verify-cmd.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatDiagnostic } from '@vmz/diagnostic';
+import { loadNative } from '../native/binding.js';
+import { requiredPositional } from './options.js';
+/**
+ * Inline CLI catalog — commander's `.locales()` resolution is not exposed
+ * outside the CLI builder, so we ship a static copy here. Only one locale is
+ * loaded at runtime; future locale awareness should resolve the chosen locale
+ * from commander internals once they surface it.
+ */
+const CLI_CATALOG = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, '../../locales/en-US/cli.json'), 'utf8'));
+const DIAGNOSTIC_STYLE = 'compact';
+const DIAGNOSTIC_LOCALE = 'en-US';
+export function registerVerifyCommand(cli) {
+    cli.command('verify', 'cli.cmd.verify').action((options) => cmdVerify(options));
+}
+/**
+ * Run read-only consistency probes against a YYDB database file.
+ *
+ * Exit codes:
+ *   0  — clean (no issues)
+ *   1  — doctor found at least one error (database may be corrupt)
+ *   13 — only warnings present (readable but should be inspected)
+ */
+export function cmdVerify(options) {
+    const dbPath = requiredPositional(options, 'verify');
+    let report;
+    try {
+        const native = loadNative();
+        const db = native.Database.open(dbPath);
+        report = JSON.parse(db.doctor());
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(formatDiagnostic({
+            path: dbPath,
+            severity: 'error',
+            code: 'cli.err.open_failed',
+            args: { path: dbPath, reason: message },
+        }, {
+            locale: DIAGNOSTIC_LOCALE,
+            catalog: CLI_CATALOG,
+            style: DIAGNOSTIC_STYLE,
+        }));
+        return 1;
+    }
+    for (const issue of report.issues) {
+        const severity = issue.severity === 'error' ? 'error' : 'warning';
+        console.error(formatDiagnostic({
+            path: dbPath,
+            severity,
+            code: issue.code,
+            message: issue.message,
+        }, {
+            locale: DIAGNOSTIC_LOCALE,
+            catalog: CLI_CATALOG,
+            style: DIAGNOSTIC_STYLE,
+        }));
+    }
+    const errCount = report.issues.filter((i) => i.severity === 'error').length;
+    const warnCount = report.issues.length - errCount;
+    if (errCount > 0) {
+        console.log(`exit=1 errors=${errCount} warnings=${warnCount}`);
+        return 1;
+    }
+    if (warnCount > 0) {
+        console.log(`exit=13 errors=0 warnings=${warnCount}`);
+        return 13;
+    }
+    console.log(`exit=0 clean last_commit=${report.last_commit_sequence}`);
+    return 0;
+}

package/dist/database.d.ts

@@ -0,0 +1,50 @@
+import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from './micro.js';
+import type { UdfTypeDescriptor } from './udf-types.js';
+export type { SchemaVersion } from '@yydb/yydb-client';
+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[];
+}
+/**
+ * Node-facing YYDB handle. Looks like one library; owns a private loopback
+ * `yydb serve` child under the hood.
+ */
+export declare class Database {
+    readonly path: string;
+    readonly endpoint: string;
+    private client;
+    private child;
+    private readonly microRegistry;
+    private constructor();
+    /**
+     * Open (create) a `.yydb` file. Spawns the engine on `127.0.0.1` automatically.
+     */
+    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>;
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array | string): Promise<void>;
+    /**
+     * Build a typed session-local micro definition. Does not register it with
+     * the engine until [`registerMicro`](./database.ts) is called.
+     */
+    defineMicro<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(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`.
+     */
+    registerMicro<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(definition: DefinedMicro<TArgs, TReturn>): Promise<MicroHandle>;
+    /** Invoke a registered scalar UDF on the private engine. */
+    callScalar(name: string, version: number, args: readonly (string | number | boolean | null)[]): Promise<string | number | boolean | null>;
+    /** Stop the private engine process. */
+    close(): Promise<void>;
+}

package/dist/database.js

@@ -0,0 +1,181 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { connect } from '@yydb/yydb-client/node';
+import { defineMicro as buildMicro, MicroSessionRegistry } from './micro.js';
+import { resolveYydbCli } from './resolve-bin.js';
+function microFingerprint(name, version) {
+    const bytes = new Uint8Array(32);
+    const seed = `${name}@${version}`;
+    for (let index = 0; index < bytes.byteLength; index += 1) {
+        bytes[index] = seed.charCodeAt(index % seed.length) & 0xff;
+    }
+    return bytes;
+}
+async function freeLoopbackPort() {
+    return await new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                server.close();
+                reject(new Error('could not allocate loopback port'));
+                return;
+            }
+            const { port } = address;
+            server.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(port);
+            });
+        });
+        server.on('error', reject);
+    });
+}
+async function waitForTcp(host, port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            await new Promise((resolve, reject) => {
+                const socket = net.connect({ host, port }, () => {
+                    socket.end();
+                    resolve();
+                });
+                socket.on('error', reject);
+            });
+            return;
+        }
+        catch {
+            await new Promise((r) => setTimeout(r, 40));
+        }
+    }
+    throw new Error(`yydb engine did not accept connections on ${host}:${port}`);
+}
+/**
+ * Node-facing YYDB handle. Looks like one library; owns a private loopback
+ * `yydb serve` child under the hood.
+ */
+export class Database {
+    path;
+    endpoint;
+    client;
+    child;
+    microRegistry;
+    constructor(dbPath, endpoint, client, child) {
+        this.path = dbPath;
+        this.endpoint = endpoint;
+        this.client = client;
+        this.child = child;
+        this.microRegistry = new MicroSessionRegistry();
+        this.client.setMicroHostHandler((payload) => this.microRegistry.invokeFromWire(payload));
+    }
+    /**
+     * Open (create) a `.yydb` file. Spawns the engine on `127.0.0.1` automatically.
+     */
+    static async open(dbPath, options = {}) {
+        const resolved = path.resolve(dbPath);
+        fs.mkdirSync(path.dirname(resolved), { recursive: true });
+        const cli = options.cli ?? options.binary ?? resolveYydbCli();
+        const port = options.port ?? (await freeLoopbackPort());
+        const bind = `127.0.0.1:${port}`;
+        const args = [cli, 'serve', resolved, '--bind', bind, ...(options.serveArgs ?? [])];
+        const child = spawn(process.execPath, args, {
+            stdio: 'pipe',
+            windowsHide: true,
+        });
+        let stderr = '';
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        const exitPromise = new Promise((_, reject) => {
+            child.once('exit', (code, signal) => {
+                reject(new Error(`yydb engine exited early (code=${code}, signal=${signal}): ${stderr.trim()}`));
+            });
+            child.once('error', reject);
+        });
+        try {
+            await Promise.race([waitForTcp('127.0.0.1', port, 8000), exitPromise]);
+            const client = await connect(bind);
+            child.removeAllListeners('exit');
+            child.removeAllListeners('error');
+            child.on('exit', () => {
+                /* closed via Database.close or crash */
+            });
+            return new Database(resolved, bind, client, child);
+        }
+        catch (error) {
+            child.kill('SIGTERM');
+            throw error;
+        }
+    }
+    async serverVersion() {
+        return this.client.serverVersion();
+    }
+    async info() {
+        return this.client.info();
+    }
+    async getSchema() {
+        return this.client.getSchema();
+    }
+    async ensureSchema(version, document) {
+        await this.client.ensureSchema(version, document);
+    }
+    async get(key) {
+        return this.client.get(key);
+    }
+    async put(key, value) {
+        await this.client.put(key, value);
+    }
+    /**
+     * Build a typed session-local micro definition. Does not register it with
+     * the engine until [`registerMicro`](./database.ts) is called.
+     */
+    defineMicro(definition) {
+        return buildMicro(definition);
+    }
+    /**
+     * 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`.
+     */
+    async registerMicro(definition) {
+        const handle = this.microRegistry.register(definition);
+        await this.client.registerMicro({
+            hostId: handle.hostId,
+            handleVersion: handle.implementationVersion,
+            udfVersion: definition.version,
+            name: definition.name,
+            functionId: handle.functionId,
+            args: definition.args.map((arg) => arg.kind),
+            returns: definition.returns.kind,
+            fingerprint: microFingerprint(definition.name, definition.version),
+        });
+        return handle;
+    }
+    /** Invoke a registered scalar UDF on the private engine. */
+    async callScalar(name, version, args) {
+        return this.client.callScalar(name, version, args);
+    }
+    /** Stop the private engine process. */
+    async close() {
+        this.client.close();
+        const child = this.child;
+        this.child = null;
+        if (!child || child.exitCode !== null || child.killed) {
+            return;
+        }
+        await new Promise((resolve) => {
+            child.once('exit', () => resolve());
+            child.kill('SIGTERM');
+            setTimeout(() => {
+                if (child.exitCode === null && !child.killed) {
+                    child.kill('SIGKILL');
+                }
+                resolve();
+            }, 2000);
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Database, type OpenOptions, type SchemaVersion } from './api/database.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './shared/errors.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';
 export { type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarDescriptor, type UdfScalarKind, } from './shared/udf-types.js';