@yydb/yydb 0.0.15 → 0.0.17

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/package.json

@@ -1,38 +1,41 @@
 {
+  "name": "@yydb/yydb",
+  "version": "0.0.17",
+  "description": "YYDB Node embedded engine and CLI",
+  "license": "MPL-2.0",
+  "type": "module",
   "bin": {
     "yydb": "./dist/cli.js"
   },
-  "bugs": {
-    "url": "https://github.com/yy-database/yydb.rs/issues"
-  },
-  "dependencies": {
-    "@vmz/commander": "^0.3.5",
-    "@vmz/diagnostic": "^0.3.5",
-    "@voml/vos": "^0.0.1"
-  },
-  "description": "YYDB Node embedded engine and CLI",
-  "devDependencies": {
-    "@types/node": "^20.10.0",
-    "typescript": "~5.3.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./cli": {
-      "import": "./dist/cli.js",
-      "types": "./dist/cli.d.ts"
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
     }
   },
   "files": [
     "dist",
     "README.md"
   ],
-  "homepage": "https://github.com/yy-database/yydb.rs/tree/dev/projects/packages/yydb#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm run build && node --experimental-strip-types --test src/**/*.test.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yy-database/yydb.git",
+    "directory": "projects/packages/yydb"
+  },
+  "homepage": "https://github.com/yy-database/yydb/tree/dev/projects/packages/yydb#readme",
+  "bugs": {
+    "url": "https://github.com/yy-database/yydb/issues"
+  },
   "keywords": [
     "yydb",
     "vos",
@@ -40,28 +43,25 @@
     "embedded",
     "typescript"
   ],
-  "license": "MPL-2.0",
-  "main": "./dist/index.js",
-  "name": "@yydb/yydb",
-  "optionalDependencies": {
-    "@yydb/yydb-darwin-arm64": "0.0.15",
-    "@yydb/yydb-darwin-x64": "0.0.15",
-    "@yydb/yydb-linux-x64": "0.0.15",
-    "@yydb/yydb-win32-x64": "0.0.15"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "directory": "projects/packages/yydb",
-    "type": "git",
-    "url": "git+https://github.com/yy-database/yydb.rs.git"
+  "dependencies": {
+    "@vmz/commander": "^0.3.5",
+    "@vmz/diagnostic": "^0.3.5",
+    "@voml/vos": "^0.0.1"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "pnpm run build && node --experimental-strip-types --test src/**/*.test.ts"
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "~5.3.0"
   },
-  "type": "module",
-  "types": "./dist/index.d.ts",
-  "version": "0.0.15"
+  "engines": {
+    "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"
+  }
 }

package/dist/database.d.ts

@@ -1,50 +0,0 @@
-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

@@ -1,181 +0,0 @@
-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/micro.d.ts

@@ -1,63 +0,0 @@
-import type { InferUdfArgs, InferUdfReturn, MicroEffect, MicroInvocationMode, UdfTypeDescriptor } from './udf-types.js';
-/** Input accepted by [`Database.defineMicro`](./database.ts). */
-export interface TsMicroDefinitionInput<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor> {
-    readonly name: string;
-    readonly version: number;
-    readonly args: TArgs;
-    readonly returns: TReturn;
-    readonly effect: MicroEffect;
-    readonly deterministic: boolean;
-    readonly mode?: MicroInvocationMode;
-    readonly fn: (...args: InferUdfArgs<TArgs>) => InferUdfReturn<TReturn>;
-}
-/** Opaque definition produced by `defineMicro` before session registration. */
-export interface DefinedMicro<TArgs extends readonly UdfTypeDescriptor[] = readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor = UdfTypeDescriptor> {
-    readonly name: string;
-    readonly version: number;
-    readonly args: TArgs;
-    readonly returns: TReturn;
-    readonly effect: MicroEffect;
-    readonly deterministic: boolean;
-    readonly mode: MicroInvocationMode;
-    readonly placement: 'host';
-    readonly fn: (...args: InferUdfArgs<TArgs>) => InferUdfReturn<TReturn>;
-}
-/** Handle returned after `registerMicro` installs a micro into the session. */
-export interface MicroHandle {
-    readonly name: string;
-    readonly version: number;
-    readonly functionId: string;
-    readonly hostId: number;
-    /** Monotonic host implementation version for opaque handle checks. */
-    readonly implementationVersion: number;
-}
-type AnyDefinedMicro = DefinedMicro<readonly UdfTypeDescriptor[], UdfTypeDescriptor>;
-/**
- * Process-local registry for JS functions behind opaque host handles.
- * Rust keeps `host_id + function_id + version`, not the closure.
- */
-export declare class MicroSessionRegistry {
-    readonly hostId: number;
-    private nextFunctionId;
-    private readonly byKey;
-    private readonly byFunctionId;
-    constructor(hostId?: number);
-    /** Installs a defined micro into the current session registry. */
-    register<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(definition: DefinedMicro<TArgs, TReturn>): MicroHandle;
-    /** Returns a registered micro by opaque host handle. */
-    resolve(handle: MicroHandle): AnyDefinedMicro | undefined;
-    /** Invokes a registered micro from a wire `MicroHostInvoke` payload. */
-    invokeFromWire(payload: {
-        hostId: number;
-        handleVersion: number;
-        functionId: string;
-        args: readonly unknown[];
-    }): string | number | boolean | null;
-    /** Invokes a registered scalar micro (host adapter entry point). */
-    invokeScalar(handle: MicroHandle, args: unknown[]): unknown;
-    /** Lists logical names currently registered in this session. */
-    list(): string[];
-}
-/** Builds a session-local micro definition without registering it. */
-export declare function defineMicro<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(input: TsMicroDefinitionInput<TArgs, TReturn>): DefinedMicro<TArgs, TReturn>;
-export {};