@yydb/yydb 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { Database, type OpenOptions } from './api/database.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from '@yydb/yydb-client';
-export type { YydbErrorCode, YydbErrorOptions } from '@yydb/yydb-client';
+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';
 export { type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarDescriptor, type UdfScalarKind, } from './shared/udf-types.js';
 export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './native/resolve.js';

package/dist/index.js

@@ -1,5 +1,5 @@
-export { Database } from './api/database.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from '@yydb/yydb-client';
+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';
 export * from './shared/vos.js';

package/dist/native/binding.d.ts

@@ -1,3 +1,8 @@
+/** Schema version returned by N-API Database.schema_version / Client.schema_version. */
+export interface NativeSchemaVersion {
+    version: number;
+    document: string;
+}
 /** One open `.yydb` handle exposed by the native binding. */
 export interface NativeDatabase {
     path(): string | null;
@@ -13,6 +18,65 @@ export interface NativeDatabase {
     walFrameCount(): number;
     get(key: string): Uint8Array | null;
     put(key: string, value: Uint8Array): void;
+    /** Delete one record by key. */
+    delete(key: string): void;
+    /** Scan keys with a prefix; returns JSON `[{ key, value }, ...]`. */
+    scanPrefix(prefix: string, after: string | null, limit: number): string;
+    /** Atomically write or delete many keys; body is JSON `[{ key, value|null }, ...]`. */
+    writeBatch(changesJson: string): void;
+    /** Compare-and-swap; returns true on success. */
+    compareExchange(key: string, expected: Uint8Array | null, replacement: Uint8Array | null): boolean;
+    /** Begin an explicit transaction. */
+    begin(): void;
+    /** Commit the current transaction. */
+    commit(): void;
+    /** Roll back the current transaction. */
+    rollback(): void;
+    /** Execute a VOS read pipeline; returns JSON rows. */
+    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). */
+    backup(dest: string): void;
+    /** Copy main + WAL + SHM without checkpoint (opening replays the tail). */
+    backupWithWal(dest: string): void;
+    /** Read-only consistency probe; returns DoctorReport JSON. */
+    doctor(): string;
+    /** Fold WAL + reclaim orphan blobs (`.yydx` only); returns CompactReport JSON. */
+    compactYydx(): string;
+    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;
+    serverVersion(): string;
+    info(): string;
+    schemaVersion(): number | null;
+    schemaDocument(): string | null;
+    ensureSchema(document: string): void;
+    get(key: string): Uint8Array | null;
+    put(key: string, value: Uint8Array): void;
+    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;
+    close(): void;
 }
 /** Atomic operations exported by the Node-API binding. */
 export interface YydbNative {
@@ -21,6 +85,9 @@ export interface YydbNative {
     Database: {
         open(dbPath: string): NativeDatabase;
     };
+    Client: {
+        connect(endpoint: string): NativeClient;
+    };
 }
 /** Load the platform native binding used by the `yydb` CLI. */
 export declare function loadNative(): YydbNative;

package/dist/shared/errors.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Host-facing YYDB error surface.
+ *
+ * Every public failure carries a stable `code`: engine codes come from the
+ * Rust core (`yydb.schema.invalid`, …) over N-API or the wire; client codes
+ * are minted locally with the `yydb.client.` prefix. **Branch on `code`** —
+ * `message` is display text only and must never be used for retry decisions.
+ *
+ * ## Where codes live
+ *
+ * Engine codes live in Rust (`yydb_types::Error` variants → DiagnosticEnvelope).
+ * The TS side no longer keeps a hardcoded engine-code table — when Rust gains a
+ * new variant, hosts pick up the new code string via {@link fromDiagnosticJson}
+ * without any TS change. Client codes (`yydb.client.*`) are minted only on the
+ * host side and remain available as constants below.
+ */
+/**
+ * Client-side error codes that never originate from Rust.
+ *
+ * Engine codes (`yydb.schema.*`, `yydb.udf.*`, `yydb.io`, …) are emitted by
+ * Rust and should be matched via string literals or from the diagnostic JSON
+ * envelope — they are intentionally not duplicated here.
+ */
+export declare const YydbClientErrorCodes: {
+    /** serve() endpoint is empty or invalid. */
+    readonly clientInvalidEndpoint: "yydb.client.invalid_endpoint";
+    /** connect() socket / transport layer failure. */
+    readonly clientTransportFailure: "yydb.client.transport_failure";
+    /** Server replied with a request id we did not send. */
+    readonly clientRequestIdMismatch: "yydb.client.request_id_mismatch";
+    /** Server replied with a msg_type we did not request. */
+    readonly clientUnexpectedResponse: "yydb.client.unexpected_response";
+    /** Could not parse an Error frame body from the wire. */
+    readonly clientDecodeFailure: "yydb.client.decode_failure";
+    /** The YYDB session is already closed. */
+    readonly sessionClosed: "yydb.session.closed";
+};
+/**
+ * @deprecated Engine codes moved to Rust — use string literals or match on
+ * {@link YydbError.code} returned from {@link fromDiagnosticJson}. This table
+ * exists only for transition; new engine error variants will **not** be added here.
+ */
+export declare const YydbErrorCodes: {
+    /** serve() endpoint is empty or invalid. */
+    readonly clientInvalidEndpoint: "yydb.client.invalid_endpoint";
+    /** connect() socket / transport layer failure. */
+    readonly clientTransportFailure: "yydb.client.transport_failure";
+    /** Server replied with a request id we did not send. */
+    readonly clientRequestIdMismatch: "yydb.client.request_id_mismatch";
+    /** Server replied with a msg_type we did not request. */
+    readonly clientUnexpectedResponse: "yydb.client.unexpected_response";
+    /** Could not parse an Error frame body from the wire. */
+    readonly clientDecodeFailure: "yydb.client.decode_failure";
+    /** The YYDB session is already closed. */
+    readonly sessionClosed: "yydb.session.closed";
+    readonly io: "yydb.io";
+    readonly corrupt: "yydb.corrupt";
+    readonly schemaConflict: "yydb.schema.conflict";
+    readonly schemaInvalid: "yydb.schema.invalid";
+    readonly udfNotFound: "yydb.udf.not_found";
+    readonly udfArity: "yydb.udf.arity";
+    readonly udfFailed: "yydb.udf.failed";
+    readonly udfVersionMismatch: "yydb.udf.version_mismatch";
+    readonly objectNotFound: "yydb.object.not_found";
+    readonly objectCorrupt: "yydb.object.corrupt";
+    readonly unsupported: "yydb.unsupported";
+    readonly protocol: "yydb.protocol";
+    readonly casConflict: "yydb.cas.conflict";
+    readonly leaseUnavailable: "yydb.lease.unavailable";
+    readonly fencingMismatch: "yydb.fencing.mismatch";
+    readonly leaseExpired: "yydb.lease.expired";
+    readonly quotaExceeded: "yydb.quota.exceeded";
+};
+/** Any stable YYDB error code string — engine, client, or future variant. */
+export type YydbErrorCode = string;
+/** Options carried by a {@link YydbError}. */
+export interface YydbErrorOptions {
+    /** Operation that failed (`schemaGet`, `kvPut`, `query`, …). */
+    operation?: string;
+    /**
+     * Whether the caller may retry with the same arguments.
+     *
+     * When omitted, constructor defaults to `false` (conservative). Callers
+     * that mint their own errors (especially client-local retryable ones like
+     * `yydb.client.transport_failure`) **must** set this explicitly. Engine
+     * errors coming through {@link fromDiagnosticJson} always carry the Rust-
+     * authoritative `retryable` value and override the default.
+     */
+    retryable?: boolean;
+    /** Structured parameters for catalog templating (when present). */
+    params?: Readonly<Record<string, string>>;
+    /** Underlying failure when this error wraps one. */
+    cause?: unknown;
+}
+/** YYDB failure with a stable machine-readable {@link YydbError.code}. */
+export declare class YydbError extends Error {
+    /** Stable code — engine code (from Rust) or `yydb.client.*`. */
+    readonly code: string;
+    /** Operation that failed. */
+    readonly operation: string;
+    /** Whether the same call may be retried. */
+    readonly retryable: boolean;
+    /** Structured parameters for catalog templating (when present). */
+    readonly params?: Readonly<Record<string, string>>;
+    constructor(code: YydbErrorCode, message: string, options?: YydbErrorOptions);
+    /**
+     * Parse the diagnostic JSON that N-API and WASM surfaces embed in their
+     * `Error.message`. Every boundary surface (N-API reason field, WASM JSON
+     * envelope, wire protocol) carries the same `{ code, operation, retryable,
+     * message, params? }` contract produced by `yydb::Error::to_json`.
+     *
+     * Returns the parsed {@link YydbError} if `value` is a diagnostic object,
+     * or `null` when the input is plain text. Hosts typically use this as a
+     * fallback in catch blocks:
+     *
+     * ```ts
+     * try {
+     *     await db.put('key', value);
+     * } catch (err) {
+     *     const parsed = YydbError.fromDiagnosticJson(
+     *         err instanceof Error ? err.message : String(err),
+     *     );
+     *     if (parsed) {
+     *         // branch on parsed.code / retryable / operation
+     *     }
+     * }
+     * ```
+     */
+    static fromDiagnosticJson(value: unknown): YydbError | null;
+}
+/** Narrowing helper so callers can branch without `instanceof` imports. */
+export declare function isYydbError(value: unknown): value is YydbError;

package/dist/shared/errors.js

@@ -0,0 +1,154 @@
+/**
+ * Host-facing YYDB error surface.
+ *
+ * Every public failure carries a stable `code`: engine codes come from the
+ * Rust core (`yydb.schema.invalid`, …) over N-API or the wire; client codes
+ * are minted locally with the `yydb.client.` prefix. **Branch on `code`** —
+ * `message` is display text only and must never be used for retry decisions.
+ *
+ * ## Where codes live
+ *
+ * Engine codes live in Rust (`yydb_types::Error` variants → DiagnosticEnvelope).
+ * The TS side no longer keeps a hardcoded engine-code table — when Rust gains a
+ * new variant, hosts pick up the new code string via {@link fromDiagnosticJson}
+ * without any TS change. Client codes (`yydb.client.*`) are minted only on the
+ * host side and remain available as constants below.
+ */
+/**
+ * Client-side error codes that never originate from Rust.
+ *
+ * Engine codes (`yydb.schema.*`, `yydb.udf.*`, `yydb.io`, …) are emitted by
+ * Rust and should be matched via string literals or from the diagnostic JSON
+ * envelope — they are intentionally not duplicated here.
+ */
+export const YydbClientErrorCodes = {
+    /** serve() endpoint is empty or invalid. */
+    clientInvalidEndpoint: 'yydb.client.invalid_endpoint',
+    /** connect() socket / transport layer failure. */
+    clientTransportFailure: 'yydb.client.transport_failure',
+    /** Server replied with a request id we did not send. */
+    clientRequestIdMismatch: 'yydb.client.request_id_mismatch',
+    /** Server replied with a msg_type we did not request. */
+    clientUnexpectedResponse: 'yydb.client.unexpected_response',
+    /** Could not parse an Error frame body from the wire. */
+    clientDecodeFailure: 'yydb.client.decode_failure',
+    /** The YYDB session is already closed. */
+    sessionClosed: 'yydb.session.closed',
+};
+/**
+ * @deprecated Engine codes moved to Rust — use string literals or match on
+ * {@link YydbError.code} returned from {@link fromDiagnosticJson}. This table
+ * exists only for transition; new engine error variants will **not** be added here.
+ */
+export const YydbErrorCodes = {
+    // Engine codes (deprecated)
+    io: 'yydb.io',
+    corrupt: 'yydb.corrupt',
+    schemaConflict: 'yydb.schema.conflict',
+    schemaInvalid: 'yydb.schema.invalid',
+    udfNotFound: 'yydb.udf.not_found',
+    udfArity: 'yydb.udf.arity',
+    udfFailed: 'yydb.udf.failed',
+    udfVersionMismatch: 'yydb.udf.version_mismatch',
+    objectNotFound: 'yydb.object.not_found',
+    objectCorrupt: 'yydb.object.corrupt',
+    unsupported: 'yydb.unsupported',
+    protocol: 'yydb.protocol',
+    casConflict: 'yydb.cas.conflict',
+    leaseUnavailable: 'yydb.lease.unavailable',
+    fencingMismatch: 'yydb.fencing.mismatch',
+    leaseExpired: 'yydb.lease.expired',
+    quotaExceeded: 'yydb.quota.exceeded',
+    // Client codes (still canonical for client-local errors)
+    ...YydbClientErrorCodes,
+};
+/** YYDB failure with a stable machine-readable {@link YydbError.code}. */
+export class YydbError extends Error {
+    /** Stable code — engine code (from Rust) or `yydb.client.*`. */
+    code;
+    /** Operation that failed. */
+    operation;
+    /** Whether the same call may be retried. */
+    retryable;
+    /** Structured parameters for catalog templating (when present). */
+    params;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = 'YydbError';
+        this.code = code;
+        this.operation = options.operation ?? 'unknown';
+        this.retryable = options.retryable ?? false;
+        if (options.params !== undefined) {
+            this.params = options.params;
+        }
+    }
+    /**
+     * Parse the diagnostic JSON that N-API and WASM surfaces embed in their
+     * `Error.message`. Every boundary surface (N-API reason field, WASM JSON
+     * envelope, wire protocol) carries the same `{ code, operation, retryable,
+     * message, params? }` contract produced by `yydb::Error::to_json`.
+     *
+     * Returns the parsed {@link YydbError} if `value` is a diagnostic object,
+     * or `null` when the input is plain text. Hosts typically use this as a
+     * fallback in catch blocks:
+     *
+     * ```ts
+     * try {
+     *     await db.put('key', value);
+     * } catch (err) {
+     *     const parsed = YydbError.fromDiagnosticJson(
+     *         err instanceof Error ? err.message : String(err),
+     *     );
+     *     if (parsed) {
+     *         // branch on parsed.code / retryable / operation
+     *     }
+     * }
+     * ```
+     */
+    static fromDiagnosticJson(value) {
+        let obj;
+        if (typeof value === 'string') {
+            try {
+                const parsed = JSON.parse(value);
+                if (!parsed || typeof parsed !== 'object')
+                    return null;
+                obj = parsed;
+            }
+            catch {
+                return null;
+            }
+        }
+        else if (value && typeof value === 'object') {
+            obj = value;
+        }
+        else {
+            return null;
+        }
+        // WASM envelopes nest the diagnostic under `{ ok, error: {...} }`.
+        let diag = obj;
+        if (typeof obj['ok'] === 'boolean' && !obj['ok'] && obj['error'] && typeof obj['error'] === 'object') {
+            diag = obj['error'];
+        }
+        const code = typeof diag['code'] === 'string' ? diag['code'] : null;
+        const message = typeof diag['message'] === 'string' ? diag['message'] : '';
+        if (!code)
+            return null;
+        const operation = typeof diag['operation'] === 'string' ? diag['operation'] : undefined;
+        const retryable = typeof diag['retryable'] === 'boolean' ? diag['retryable'] : undefined;
+        const params = diag['params'] && typeof diag['params'] === 'object'
+            ? diag['params']
+            : undefined;
+        const opts = {};
+        if (operation !== undefined)
+            opts.operation = operation;
+        if (retryable !== undefined)
+            opts.retryable = retryable;
+        if (params !== undefined)
+            opts.params = params;
+        return new YydbError(code, message, opts);
+    }
+}
+/** Narrowing helper so callers can branch without `instanceof` imports. */
+export function isYydbError(value) {
+    return value instanceof YydbError;
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@yydb/yydb",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "YYDB Node embedded engine and CLI",
   "license": "MPL-2.0",
   "type": "module",
   "bin": {
-    "yydb": "./dist/cli.js"
+    "yydb": "dist/cli.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -47,9 +47,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@vmz/commander": "^0.2.0",
-    "@voml/vos": "^0.0.1",
-    "@yydb/yydb-client": "0.1.1"
+    "@vmz/commander": "^0.3.5",
+    "@vmz/diagnostic": "^0.3.5",
+    "@voml/vos": "^0.0.5"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
@@ -59,9 +59,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@yydb/yydb-win32-x64": "0.1.1",
-    "@yydb/yydb-linux-x64": "0.1.1",
-    "@yydb/yydb-darwin-x64": "0.1.1",
-    "@yydb/yydb-darwin-arm64": "0.1.1"
+    "@yydb/yydb-darwin-arm64": "0.1.2",
+    "@yydb/yydb-darwin-x64": "0.1.2",
+    "@yydb/yydb-linux-x64": "0.1.2",
+    "@yydb/yydb-win32-x64": "0.1.2"
   }
 }