@yydb/yydb 0.0.0 → 0.0.1

package/README.md

@@ -1,4 +1,30 @@
-# @yydb/yydb
+# `@yydb/yydb`
 
-Placeholder 0.0.0 for npm Trusted Publisher bootstrap.
-Real releases replace this from CI (`release-npm.yml`).
+TypeScript / Node **product surface** for YYDB. One dependency:
+
+```ts
+import { Database } from "@yydb/yydb";
+
+const db = await Database.open("app.yydb");
+await db.ensureSchema(1, "table Setting { @@id: uuid, key: utf8, value: utf8 }");
+await db.put("theme", "dark");
+await db.close();
+```
+
+You do **not** download `yydb.exe`, configure PATH, or call `serve` yourself.
+This package starts a loopback engine process behind the API (same Rust kernel
+as `backends/yydb`). Platform binaries ship as optionalDependencies
+(`@yydb/yydb-<platform>-<arch>`); npm installs only your OS’s package.
+
+| Package | Role |
+| --- | --- |
+| `@yydb/yydb` | High-level `Database.open` (this package) |
+| `@yydb/yydb-client` | Low-level YY wire (also used by WebUI) |
+| `@yydb/yydb-<os>-<arch>` | Prebuilt `yydb` binary (publish pipeline) |
+
+Local monorepo/dev: falls back to `target/release|debug/yydb` or `YYDB_BIN`.
+
+Browser: still use `@yydb/yydb-client` against a host that already runs
+the engine (e.g. Electron main used `@yydb/yydb`, renderer talks WS).
+
+Security: engine binds **loopback only**. No ACL — do not expose the port.

package/dist/database.d.ts

@@ -0,0 +1,32 @@
+export type { SchemaVersion } from "@yydb/yydb-client";
+export interface OpenOptions {
+    /** Override engine binary (tests / special installs). */
+    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 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>;
+    /** Stop the private engine process. */
+    close(): Promise<void>;
+}

package/dist/database.js

@@ -0,0 +1,139 @@
+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 { resolveYydbBinary } from "./resolve-bin.js";
+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;
+    constructor(dbPath, endpoint, client, child) {
+        this.path = dbPath;
+        this.endpoint = endpoint;
+        this.client = client;
+        this.child = child;
+    }
+    /**
+     * 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 binary = options.binary ?? resolveYydbBinary();
+        const port = options.port ?? (await freeLoopbackPort());
+        const bind = `127.0.0.1:${port}`;
+        const args = ["serve", resolved, "--bind", bind, ...(options.serveArgs ?? [])];
+        const child = spawn(binary, 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);
+    }
+    /** 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

@@ -0,0 +1,2 @@
+export { Database, type OpenOptions } from "./database.js";
+export { resolveYydbBinary, platformKey } from "./resolve-bin.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Database } from "./database.js";
+export { resolveYydbBinary, platformKey } from "./resolve-bin.js";

package/dist/resolve-bin.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+export type PlatformKey = "win32-x64" | "linux-x64" | "darwin-x64" | "darwin-arm64";
+/** Map Node platform/arch to optionalDependency package suffix. */
+export declare function platformKey(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PlatformKey | null;
+/**
+ * Resolve the `yydb` engine binary without asking the app developer to
+ * configure downloads. Order: `YYDB_BIN` → optional platform package →
+ * cargo `target/{release,debug}` (monorepo).
+ */
+export declare function resolveYydbBinary(): string;

package/dist/resolve-bin.js

@@ -0,0 +1,69 @@
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+/** Map Node platform/arch to optionalDependency package suffix. */
+export function platformKey(platform = process.platform, arch = process.arch) {
+    if (platform === "win32" && arch === "x64")
+        return "win32-x64";
+    if (platform === "linux" && arch === "x64")
+        return "linux-x64";
+    if (platform === "darwin" && arch === "x64")
+        return "darwin-x64";
+    if (platform === "darwin" && arch === "arm64")
+        return "darwin-arm64";
+    return null;
+}
+function binaryName(platform = process.platform) {
+    return platform === "win32" ? "yydb.exe" : "yydb";
+}
+function existsExecutable(filePath) {
+    try {
+        fs.accessSync(filePath, fs.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the `yydb` engine binary without asking the app developer to
+ * configure downloads. Order: `YYDB_BIN` → optional platform package →
+ * cargo `target/{release,debug}` (monorepo).
+ */
+export function resolveYydbBinary() {
+    const fromEnv = process.env.YYDB_BIN?.trim();
+    if (fromEnv) {
+        if (!existsExecutable(fromEnv)) {
+            throw new Error(`YYDB_BIN points to missing binary: ${fromEnv}`);
+        }
+        return path.resolve(fromEnv);
+    }
+    const key = platformKey();
+    if (key) {
+        const pkg = `@yydb/yydb-${key}`;
+        const name = binaryName();
+        try {
+            const pkgJson = require.resolve(`${pkg}/package.json`);
+            const candidate = path.join(path.dirname(pkgJson), name);
+            if (existsExecutable(candidate)) {
+                return candidate;
+            }
+        }
+        catch {
+            // optionalDependency not installed for this platform
+        }
+    }
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "../../..");
+    for (const profile of ["release", "debug"]) {
+        const candidate = path.join(repoRoot, "target", profile, binaryName());
+        if (existsExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error("YYDB engine binary not found. Install the matching optionalDependency " +
+        `(@yydb/yydb-${key ?? "<platform>"}), set YYDB_BIN, or build ` +
+        "`cargo build -p yydb-tools` in this repo.");
+}

package/package.json

@@ -1,14 +1,58 @@
 {
   "name": "@yydb/yydb",
-  "version": "0.0.0",
-  "description": "Placeholder — YYDB Node product API",
+  "version": "0.0.1",
+  "description": "YYDB for TypeScript/Node — one package; engine binary managed for you",
   "license": "MIT",
-  "private": false,
-  "publishConfig": {
-    "access": "public"
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --experimental-strip-types --test src/resolve-bin.test.ts"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/yy-database/yydb.git"
+    "url": "git+https://github.com/yy-database/yydb.rs.git",
+    "directory": "frontends/yydb"
+  },
+  "homepage": "https://github.com/yy-database/yydb.rs/tree/dev/frontends/yydb#readme",
+  "bugs": {
+    "url": "https://github.com/yy-database/yydb.rs/issues"
+  },
+  "keywords": [
+    "yydb",
+    "vos",
+    "database",
+    "embedded",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@yydb/yydb-client": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "~5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@yydb/yydb-win32-x64": "0.0.1",
+    "@yydb/yydb-linux-x64": "0.0.1",
+    "@yydb/yydb-darwin-x64": "0.0.1",
+    "@yydb/yydb-darwin-arm64": "0.0.1"
   }
 }