@yydb/yydb 0.0.11 → 0.0.12

package/dist/api/database.d.ts

@@ -1,5 +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 type { UdfScalarDescriptor } from '../shared/udf-types.js';
 /** Published schema metadata. */
 export interface SchemaVersion {
@@ -11,6 +12,54 @@ export interface OpenOptions {
     /** 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;
+    }>;
+}
+/**
+ * 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.
  *
@@ -39,26 +88,52 @@ export declare class Database {
      * 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.
-     *
-     * ```ts
-     * // Raw source (unchanged behaviour):
-     * await db.ensureSchema('namespace demo { table User { @@id: uuid } }');
-     *
-     * // Zod-like builder — the Vos schema-ecosystem sweet spot:
-     * const User = v.table('User', { id: v.uuid().primary(), name: v.utf8() });
-     * await db.ensureSchema(User);
-     *
-     * // Multiple declarations in one shot:
-     * await db.ensureSchema(TableA, TableB, ClassC);
-     * ```
      */
     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>;
+    /**
+     * 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>;
+    /** 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>;
+    /**
+     * 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>;
     /**

package/dist/api/database.js

@@ -3,6 +3,44 @@ import path from 'node:path';
 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';
+/**
+ * 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 class TransactionHandle {
+    native;
+    constructor(native) {
+        this.native = native;
+    }
+    async get(key) { return this.native.get(key); }
+    async put(key, value) {
+        const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
+        this.native.put(key, bytes);
+    }
+    async delete(key) { this.native.delete(key); }
+    async scan(options = {}) {
+        const rowsJson = this.native.scanPrefix(options.prefix ?? '', options.after ?? null, options.limit ?? 1000);
+        const rows = JSON.parse(rowsJson);
+        return rows.map((r) => ({ key: r.key, value: new Uint8Array(r.value) }));
+    }
+    async batch(changes) {
+        const body = changes.map((c) => ({
+            key: c.key,
+            value: c.value === null ? null : typeof c.value === 'string' ? Array.from(new TextEncoder().encode(c.value)) : Array.from(c.value),
+        }));
+        this.native.writeBatch(JSON.stringify(body));
+    }
+    async compareExchange(key, expected, replacement) {
+        const toBytes = (v) => v === null ? null : typeof v === 'string' ? new TextEncoder().encode(v) : v;
+        return this.native.compareExchange(key, toBytes(expected), toBytes(replacement));
+    }
+    async query(source) {
+        return JSON.parse(this.native.queryVos(source));
+    }
+    async execute(source) { this.native.executeVosWrite(source); }
+}
 /**
  * Node-facing YYDB local database handle.
  *
@@ -57,27 +95,13 @@ export class Database {
      * 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.
-     *
-     * ```ts
-     * // Raw source (unchanged behaviour):
-     * await db.ensureSchema('namespace demo { table User { @@id: uuid } }');
-     *
-     * // Zod-like builder — the Vos schema-ecosystem sweet spot:
-     * const User = v.table('User', { id: v.uuid().primary(), name: v.utf8() });
-     * await db.ensureSchema(User);
-     *
-     * // Multiple declarations in one shot:
-     * await db.ensureSchema(TableA, TableB, ClassC);
-     * ```
      */
     async ensureSchema(...input) {
         let document;
         if (typeof input[0] === 'string') {
-            // Raw source string, optionally followed by descriptors we just ignore.
             document = input[0];
         }
         else {
-            // One or more Vos descriptor items → render to source.
             document = emitSource(input);
         }
         this.native.ensureSchema(document);
@@ -91,10 +115,112 @@ export class Database {
         const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
         this.native.put(key, bytes);
     }
+    /** Delete one record by key. Silently succeeds when the key is absent. */
+    async delete(key) {
+        this.native.delete(key);
+    }
+    /** List key/value pairs in lexical order. `prefix` defaults to `""` (all keys). */
+    async scan(options = {}) {
+        const rowsJson = this.native.scanPrefix(options.prefix ?? '', options.after ?? null, options.limit ?? 1000);
+        const rows = JSON.parse(rowsJson);
+        return rows.map((r) => ({ key: r.key, value: new Uint8Array(r.value) }));
+    }
+    /** Atomically write or delete many keys in one call. */
+    async batch(changes) {
+        const body = changes.map((c) => ({
+            key: c.key,
+            value: c.value === null
+                ? null
+                : typeof c.value === 'string'
+                    ? Array.from(new TextEncoder().encode(c.value))
+                    : Array.from(c.value),
+        }));
+        this.native.writeBatch(JSON.stringify(body));
+    }
+    /**
+     * 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.
+     */
+    async compareExchange(key, expected, replacement) {
+        const toBytes = (v) => v === null ? null : typeof v === 'string' ? new TextEncoder().encode(v) : v;
+        return this.native.compareExchange(key, toBytes(expected), toBytes(replacement));
+    }
     /** Fold the WAL into the main file and truncate the sidecar. */
     async checkpoint() {
         this.native.checkpoint();
     }
+    /**
+     * 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');
+     * });
+     * ```
+     */
+    async transaction(fn) {
+        this.native.begin();
+        const tx = new TransactionHandle(this.native);
+        try {
+            const result = await fn(tx);
+            this.native.commit();
+            return result;
+        }
+        catch (err) {
+            try {
+                this.native.rollback();
+            }
+            catch {
+                // rollback already failed, don't mask the original error
+            }
+            throw YydbError.fromDiagnosticJson(err instanceof Error ? err.message : String(err)) ?? err;
+        }
+    }
+    /** Execute a VOS read pipeline and return typed rows. */
+    async query(source) {
+        const rowsJson = this.native.queryVos(source);
+        return JSON.parse(rowsJson);
+    }
+    /** Execute a VOS write program. */
+    async execute(source) {
+        this.native.executeVosWrite(source);
+    }
+    /**
+     * 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.
+     */
+    async migrateSchema(documentOrSource, ...rest) {
+        let document;
+        let options = {};
+        const all = [documentOrSource, ...rest];
+        const last = all[all.length - 1];
+        if (last &&
+            typeof last === 'object' &&
+            !('table' in last) &&
+            !('class' in last) &&
+            !('emit' in last) &&
+            ('renames' in last || Object.keys(last).length === 0)) {
+            options = all.pop() ?? {};
+        }
+        if (typeof all[0] === 'string') {
+            document = all[0];
+        }
+        else {
+            document = emitSource(all);
+        }
+        const renamesJson = options.renames?.length
+            ? JSON.stringify(options.renames)
+            : null;
+        this.native.migrateSchema(document, renamesJson);
+    }
     /** Build a typed session-local micro definition (without registering). */
     defineMicro(definition) {
         return buildMicro(definition);

package/dist/native/binding.d.ts

@@ -18,6 +18,26 @@ 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;
+    /** Publish a new schema version, optionally with rename map. */
+    migrateSchema(document: string, renamesJson?: string | null): 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;
 }

package/dist/shared/errors.d.ts

@@ -40,6 +40,8 @@ export declare function isRetryableYydbCode(code: string): boolean;
 export interface YydbErrorOptions {
     /** Operation that failed (`schemaGet`, `kvPut`, `query`, …). */
     operation?: string;
+    /** Structured parameters for catalog templating (when present). */
+    params?: Readonly<Record<string, string>>;
     /** Underlying failure when this error wraps one. */
     cause?: unknown;
 }
@@ -51,7 +53,33 @@ export declare class YydbError extends Error {
     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

@@ -54,12 +54,75 @@ export class YydbError extends Error {
     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 = isRetryableYydbCode(code);
+        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;
+        }
+        const code = typeof obj.code === 'string' ? obj.code : null;
+        const message = typeof obj.message === 'string' ? obj.message : '';
+        if (!code)
+            return null;
+        const operation = typeof obj.operation === 'string' ? obj.operation : undefined;
+        const retryable = typeof obj.retryable === 'boolean' ? obj.retryable : undefined;
+        const params = obj.params && typeof obj.params === 'object'
+            ? obj.params
+            : undefined;
+        const err = new YydbError(code, message, {
+            operation,
+            params,
+        });
+        if (typeof retryable === 'boolean') {
+            err.retryable = retryable;
+        }
+        return err;
     }
 }
 /** Narrowing helper so callers can branch without `instanceof` imports. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yydb/yydb",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "YYDB Node embedded engine and CLI",
   "license": "MPL-2.0",
   "type": "module",
@@ -59,9 +59,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@yydb/yydb-darwin-arm64": "0.0.11",
-    "@yydb/yydb-darwin-x64": "0.0.11",
-    "@yydb/yydb-linux-x64": "0.0.11",
-    "@yydb/yydb-win32-x64": "0.0.11"
+    "@yydb/yydb-darwin-arm64": "0.0.12",
+    "@yydb/yydb-darwin-x64": "0.0.12",
+    "@yydb/yydb-linux-x64": "0.0.12",
+    "@yydb/yydb-win32-x64": "0.0.12"
   }
 }