@yydb/yydb 0.0.3 → 0.0.4

package/README.md

@@ -1,25 +1,22 @@
 # `@yydb/yydb`
 
-**All-in-one YYDB for Node.js: CLI, embedded engine, and local `serve`.**
-
-Open a `.yydb` file with one dependency — `@yydb/yydb` spawns a private loopback server and talks to it over the YY
-wire protocol. For a **lightweight client only** (browser, renderer, or an app that already runs `yydb serve`), use
-[`@yydb/yydb-client`](../yydb-client).
+Opens a `.yydb` file in Node.js with one dependency: a private loopback `yydb serve` process starts automatically and
+the package talks to it over the YY wire protocol. For a lightweight client only (browser, 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)
-[![Check Rust](https://github.com/yy-database/yydb/actions/workflows/check-rust.yml/badge.svg?branch=dev)](https://github.com/yy-database/yydb/actions/workflows/check-rust.yml)
-[![Check TypeScript](https://github.com/yy-database/yydb/actions/workflows/check-typescript.yml/badge.svg?branch=dev)](https://github.com/yy-database/yydb/actions/workflows/check-typescript.yml)
 
-## Install
+## Exports
 
-```bash
-npm install @yydb/yydb
-```
+| Import           | Role                                     |
+|------------------|------------------------------------------|
+| `@yydb/yydb`     | `Database` API and default entry         |
+| `@yydb/yydb/cli` | CLI (`version`, `init`, `info`, `serve`) |
+
+Node.js 18+. The matching platform `.node` binding installs via optional dependencies.
 
-Node.js 18 or newer is supported. The matching `yydb-napi` binding is installed as an optional platform dependency and
-is
-started on a private loopback endpoint when `Database.open()` runs.
+Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents.
 
 ## Example
 
@@ -38,19 +35,16 @@ await db.ensureSchema(
 );
 
 await db.put("theme", "dark");
-const value = await db.get("theme");
-console.log(value && new TextDecoder().decode(value));
-
+console.log(await db.get("theme"));
 await db.close();
 ```
 
-The database file is created if it does not exist. The VOS schema and its version are stored with the data, so reopening
-the file does not depend on a separate schema registry.
+The file is created when missing. Schema version and VOS document persist with the data.
 
 ## API
 
 ```ts
-const db = await Database.open(path, options ?);
+const db = await Database.open(path, options?);
 
 await db.ensureSchema(version, vosDocument);
 await db.getSchema();
@@ -61,30 +55,21 @@ await db.serverVersion();
 await db.close();
 ```
 
-`OpenOptions` supports `cli` (an explicit CLI script path), `port` (a preferred loopback port), and `serveArgs` (extra
-arguments forwarded to `yydb serve`). `binary` is a deprecated alias for `cli`.
-
-## Use a different package when
-
-| Need                                   | Package                                   |
-|----------------------------------------|-------------------------------------------|
-| Node all-in-one (CLI + engine + serve) | **`@yydb/yydb`** (this package)           |
-| Lightweight wire client only           | [`@yydb/yydb-client`](../yydb-client)     |
-| In-process Rust embed                  | [`yydb`](https://crates.io/crates/yydb)   |
-| Rust wire server crate (used by N-API) | [`yydb-server`](../../crates/yydb-server) |
-| Rust remote client                     | [`yydb-client`](../../crates/yydb-client) |
+`OpenOptions`: `cli` (explicit CLI script path), `port` (preferred loopback port), `serveArgs` (extra `yydb serve`
+arguments). `binary` is a deprecated alias for `cli`.
 
-For Electron, the main process can use `@yydb/yydb`; renderer code can use
-`@yydb/yydb-client` against the main process endpoint.
+## Related packages
 
-## Security
+| Need                           | Package                                                                |
+|--------------------------------|------------------------------------------------------------------------|
+| Node all-in-one (this package) | **`@yydb/yydb`**                                                       |
+| 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) |
 
-The managed engine listens on `127.0.0.1` and has no authentication layer. Keep the endpoint private and use the
-operating system's file permissions for the `.yydb` file.
+Electron: main process can use `@yydb/yydb`; renderer code can use `@yydb/yydb-client` against the main-process
+endpoint.
 
-## Links
+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)
-- [API documentation](https://docs.rs/yydb)
-- [License](https://github.com/yy-database/yydb.rs/blob/dev/License.md)
+[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/cli/cli.js

@@ -1,7 +1,6 @@
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createCli } from '@vmz/commander';
-import { registerGenerateCommand } from './generate-cmd.js';
 import { registerInfoCommand } from './info-cmd.js';
 import { registerInitCommand } from './init-cmd.js';
 import { registerServeCommand } from './serve-cmd.js';
@@ -13,7 +12,6 @@ function buildYydbCli() {
     registerInitCommand(cli);
     registerInfoCommand(cli);
     registerServeCommand(cli);
-    registerGenerateCommand(cli);
     return cli;
 }
 export async function runCli(argv) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yydb/yydb",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "YYDB all-in-one for Node: embedded engine, CLI, and local serve",
   "license": "MPL-2.0",
   "type": "module",
@@ -17,10 +17,6 @@
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
-    },
-    "./generator": {
-      "types": "./dist/generator/index.d.ts",
-      "import": "./dist/generator/index.js"
     }
   },
   "files": [
@@ -52,7 +48,7 @@
   },
   "dependencies": {
     "@vmz/commander": "^0.2.0",
-    "@yydb/yydb-client": "0.0.3"
+    "@yydb/yydb-client": "0.0.4"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
@@ -62,9 +58,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@yydb/yydb-win32-x64": "0.0.3",
-    "@yydb/yydb-linux-x64": "0.0.3",
-    "@yydb/yydb-darwin-x64": "0.0.3",
-    "@yydb/yydb-darwin-arm64": "0.0.3"
+    "@yydb/yydb-win32-x64": "0.0.4",
+    "@yydb/yydb-linux-x64": "0.0.4",
+    "@yydb/yydb-darwin-x64": "0.0.4",
+    "@yydb/yydb-darwin-arm64": "0.0.4"
   }
 }

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

@@ -1,3 +0,0 @@
-import type { Cli, ParsedOptions } from '@vmz/commander';
-export declare function registerGenerateCommand(cli: Cli): void;
-export declare function cmdGenerate(options: ParsedOptions): number;

package/dist/cli/generate-cmd.js

@@ -1,25 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { generateTypeScript } from '../generator/index.js';
-import { requiredPositional, str } from './options.js';
-export function registerGenerateCommand(cli) {
-    cli.command('generate', 'cli.cmd.generate')
-        .option('-o, --output <path>', 'cli.opt.output')
-        .option('--schema-version <n>', 'cli.opt.schema-version')
-        .action((options) => cmdGenerate(options));
-}
-export function cmdGenerate(options) {
-    const input = requiredPositional(options, 'generate');
-    const output = str(options, 'output');
-    if (!output) {
-        throw new Error('generate requires --output <path>');
-    }
-    const schemaVersion = Number.parseInt(str(options, 'schema-version') ?? '1', 10);
-    const source = fs.readFileSync(input, 'utf8');
-    const ts = generateTypeScript(source, schemaVersion);
-    const outPath = path.resolve(output);
-    fs.mkdirSync(path.dirname(outPath), { recursive: true });
-    fs.writeFileSync(outPath, ts);
-    console.log(`wrote ${outPath}`);
-    return 0;
-}

package/dist/generator/emit-typescript.d.ts

@@ -1,3 +0,0 @@
-import { type TsSchemaIr } from './ir.js';
-/** Generate `schema.generated.ts` source from IR. */
-export declare function emitTypeScript(ir: TsSchemaIr): string;

package/dist/generator/emit-typescript.js

@@ -1,26 +0,0 @@
-import { scalarToTs } from './ir.js';
-const BANNER = '// @generated by `yydb generate`, do not edit!';
-/** Generate `schema.generated.ts` source from IR. */
-export function emitTypeScript(ir) {
-    const lines = [BANNER];
-    lines.push(`export const APP_SCHEMA_VERSION = ${ir.schemaVersion};`);
-    lines.push(`export const APP_SCHEMA = ${JSON.stringify(ir.vosSource)};`);
-    for (const table of ir.tables) {
-        lines.push(emitInterfaceRow(table));
-    }
-    lines.push(emitInterfaceAppDb(ir));
-    lines.push(`export type AppDbTableName = keyof AppDb["tables"];`);
-    return `${lines.join('\n')}\n`;
-}
-function emitInterfaceRow(table) {
-    const lines = [`export interface ${table.name}Row {`];
-    for (const field of table.fields) {
-        lines.push(`    ${field.name}: ${scalarToTs(field.ty)};`);
-    }
-    lines.push('}');
-    return lines.join('\n');
-}
-function emitInterfaceAppDb(ir) {
-    const tableLines = ir.tables.map((table) => `        ${table.name}: ${table.name}Row;`);
-    return ['export interface AppDb {', '    tables: {', ...tableLines, '    };', '}'].join('\n');
-}

package/dist/generator/fixtures/setting.generated.d.ts

@@ -1,13 +0,0 @@
-export declare const APP_SCHEMA_VERSION = 1;
-export declare const APP_SCHEMA = "table Setting {\n    @@id: uuid,\n    key: utf8,\n    value: utf8,\n}\n";
-export interface SettingRow {
-    id: string;
-    key: string;
-    value: string;
-}
-export interface AppDb {
-    tables: {
-        Setting: SettingRow;
-    };
-}
-export type AppDbTableName = keyof AppDb["tables"];

package/dist/generator/fixtures/setting.generated.js

@@ -1,3 +0,0 @@
-// @generated by `yydb generate`, do not edit!
-export const APP_SCHEMA_VERSION = 1;
-export const APP_SCHEMA = "table Setting {\n    @@id: uuid,\n    key: utf8,\n    value: utf8,\n}\n";

package/dist/generator/index.d.ts

@@ -1,6 +0,0 @@
-export type { SchemaField, SchemaTable, ScalarType, TsSchemaIr } from './ir.js';
-export { emitTypeScript } from './emit-typescript.js';
-export { parseVosSubset, VosParseError } from './parse-vos.js';
-/** Generate TypeScript from a VOS document. */
-export declare function generateTypeScript(vosSource: string, schemaVersion: number): string;
-export { generateTypeScript as generateTypescript };

package/dist/generator/index.js

@@ -1,10 +0,0 @@
-import { emitTypeScript } from './emit-typescript.js';
-import { parseVosSubset } from './parse-vos.js';
-export { emitTypeScript } from './emit-typescript.js';
-export { parseVosSubset, VosParseError } from './parse-vos.js';
-/** Generate TypeScript from a VOS document. */
-export function generateTypeScript(vosSource, schemaVersion) {
-    const ir = parseVosSubset(vosSource, schemaVersion);
-    return emitTypeScript(ir);
-}
-export { generateTypeScript as generateTypescript };

package/dist/generator/ir.d.ts

@@ -1,20 +0,0 @@
-/** Scalar types supported by the MVP emitter (expand with `vos-parser`). */
-export type ScalarType = 'uuid' | 'utf8' | 'bool' | 'i64' | 'f64';
-export interface SchemaField {
-    readonly name: string;
-    readonly ty: ScalarType;
-    /** True when this field is declared via `@@id`. */
-    readonly isId: boolean;
-}
-export interface SchemaTable {
-    readonly name: string;
-    readonly fields: readonly SchemaField[];
-}
-/** One schema document ready for TypeScript emission. */
-export interface TsSchemaIr {
-    /** Original VOS source (database truth embedded into generated module). */
-    readonly vosSource: string;
-    readonly schemaVersion: number;
-    readonly tables: readonly SchemaTable[];
-}
-export declare function scalarToTs(ty: ScalarType): string;

package/dist/generator/ir.js

@@ -1,12 +0,0 @@
-export function scalarToTs(ty) {
-    switch (ty) {
-        case 'uuid':
-        case 'utf8':
-            return 'string';
-        case 'bool':
-            return 'boolean';
-        case 'i64':
-        case 'f64':
-            return 'number';
-    }
-}

package/dist/generator/parse-vos.d.ts

@@ -1,6 +0,0 @@
-import type { TsSchemaIr } from './ir.js';
-export declare class VosParseError extends Error {
-    constructor(message: string);
-}
-/** Interim VOS subset parser for `yydb generate` (MVP). */
-export declare function parseVosSubset(source: string, schemaVersion: number): TsSchemaIr;

package/dist/generator/parse-vos.js

@@ -1,149 +0,0 @@
-export class VosParseError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'VosParseError';
-    }
-}
-/** Interim VOS subset parser for `yydb generate` (MVP). */
-export function parseVosSubset(source, schemaVersion) {
-    if (source.includes('\0')) {
-        throw new VosParseError('VOS document must not contain NUL bytes');
-    }
-    let normalized = source.startsWith('\uFEFF') ? source.slice(1) : source;
-    normalized = normalized.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-    const lexer = new Lexer(normalized);
-    const tables = [];
-    while (!lexer.eof()) {
-        lexer.skipWsAndComments();
-        if (lexer.eof()) {
-            break;
-        }
-        tables.push(parseTable(lexer));
-    }
-    if (tables.length === 0) {
-        throw new VosParseError('expected at least one `table` declaration');
-    }
-    return {
-        vosSource: normalized,
-        schemaVersion,
-        tables,
-    };
-}
-function parseTable(lexer) {
-    lexer.expectIdent('table');
-    const name = lexer.expectAnyIdent();
-    lexer.expectPunct('{');
-    const fields = [];
-    while (true) {
-        lexer.skipWsAndComments();
-        if (lexer.eatPunct('}')) {
-            break;
-        }
-        if (lexer.eatPunct('@')) {
-            lexer.expectPunct('@');
-            const attr = lexer.expectAnyIdent();
-            if (attr !== 'id') {
-                throw new VosParseError(`unsupported table attribute \`@@${attr}\` (MVP supports \`@@id\` only)`);
-            }
-            lexer.expectPunct(':');
-            const ty = parseScalar(lexer);
-            fields.push({ name: 'id', ty, isId: true });
-        }
-        else {
-            const fieldName = lexer.expectAnyIdent();
-            lexer.expectPunct(':');
-            const ty = parseScalar(lexer);
-            fields.push({ name: fieldName, ty, isId: false });
-        }
-        lexer.skipWsAndComments();
-        lexer.eatPunct(',');
-    }
-    if (!fields.some((field) => field.isId)) {
-        throw new VosParseError(`table \`${name}\` requires \`@@id: <type>\``);
-    }
-    return { name, fields };
-}
-function parseScalar(lexer) {
-    const name = lexer.expectAnyIdent();
-    switch (name) {
-        case 'uuid':
-            return 'uuid';
-        case 'utf8':
-            return 'utf8';
-        case 'bool':
-            return 'bool';
-        case 'i64':
-            return 'i64';
-        case 'f64':
-            return 'f64';
-        default:
-            throw new VosParseError(`unsupported scalar type \`${name}\` (MVP: uuid, utf8, bool, i64, f64)`);
-    }
-}
-class Lexer {
-    src;
-    i = 0;
-    constructor(src) {
-        this.src = src;
-    }
-    eof() {
-        return this.i >= this.src.length;
-    }
-    peek() {
-        return this.src[this.i];
-    }
-    bump() {
-        const ch = this.peek();
-        if (ch === undefined) {
-            return undefined;
-        }
-        this.i += 1;
-        return ch;
-    }
-    skipWsAndComments() {
-        while (true) {
-            while (this.peek() !== undefined && /\s/.test(this.peek())) {
-                this.bump();
-            }
-            if (this.src.startsWith('//', this.i)) {
-                while (this.peek() !== undefined && this.peek() !== '\n') {
-                    this.bump();
-                }
-                continue;
-            }
-            break;
-        }
-    }
-    eatPunct(expected) {
-        this.skipWsAndComments();
-        if (this.peek() === expected) {
-            this.bump();
-            return true;
-        }
-        return false;
-    }
-    expectPunct(expected) {
-        if (!this.eatPunct(expected)) {
-            throw new VosParseError(`expected \`${expected}\` at byte ${this.i}`);
-        }
-    }
-    expectIdent(expected) {
-        const got = this.expectAnyIdent();
-        if (got !== expected) {
-            throw new VosParseError(`expected \`${expected}\`, found \`${got}\``);
-        }
-    }
-    expectAnyIdent() {
-        this.skipWsAndComments();
-        const start = this.i;
-        const first = this.peek();
-        if (first === undefined || !/[A-Za-z_]/.test(first)) {
-            throw new VosParseError(`expected identifier at byte ${this.i}`);
-        }
-        this.bump();
-        while (this.peek() !== undefined && /[A-Za-z0-9_]/.test(this.peek())) {
-            this.bump();
-        }
-        return this.src.slice(start, this.i);
-    }
-}