@yydb/yyds 0.0.0-stage → 0.0.0

package/package.json

@@ -1,6 +1,63 @@
 {
+  "bugs": {
+    "url": "https://github.com/yy-database/yyds/issues"
+  },
+  "description": "YYDS scripting runtime for TypeScript and Node.js",
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "default": "./src/node/unsupported.ts",
+      "node": "./src/node/index.ts",
+      "types": "./src/node/index.ts"
+    },
+    "./node": {
+      "default": "./src/node/unsupported.ts",
+      "node": "./src/node/index.ts",
+      "types": "./src/node/index.ts"
+    },
+    "./node/cluster": {
+      "default": "./src/node/unsupported.ts",
+      "node": "./src/node/cluster.ts",
+      "types": "./src/node/cluster.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "homepage": "https://github.com/yy-database/yyds/tree/dev/projects/packages/yyds#readme",
+  "keywords": [
+    "yyds",
+    "scripting",
+    "typescript",
+    "napi"
+  ],
+  "license": "MPL-2.0",
   "name": "@yydb/yyds",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "optionalDependencies": {
+    "@yydb/yyds-darwin-arm64": "0.0.0",
+    "@yydb/yyds-darwin-x64": "0.0.0",
+    "@yydb/yyds-linux-x64": "0.0.0",
+    "@yydb/yyds-win32-x64": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "projects/packages/yyds",
+    "type": "git",
+    "url": "git+https://github.com/yy-database/yyds.git"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test \"./tests/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.0.0"
+}

package/readme.md

@@ -0,0 +1,13 @@
+# @yyds/yyds
+
+TypeScript facade for the YYDS scripting runtime.
+
+- Browser / Worker: default export (`@yyds/yyds`) or `@yyds/yyds/wasm`
+- Node.js: `@yyds/yyds/node`
+
+Build native and WASM artifacts from the repo root:
+
+```bash
+pnpm build:napi
+pnpm build:wasm
+```

package/src/bindings.ts

@@ -0,0 +1,5 @@
+/** Shared Node and WASM binding surface for `@yydb/yyds`. */
+export interface YydsBindings {
+    yydsVersion(): string;
+    ping(): string;
+}

package/src/browser/index.ts

@@ -0,0 +1,7 @@
+/**
+ * `@yydb/yyds` default export — browser / Worker facade (WASM inside).
+ *
+ * Node apps use `@yydb/yyds/node`. Low-level WASM loader: `@yydb/yyds/wasm`.
+ */
+
+export { initWasm, ping, yydsVersion, type InitWasmOptions, type WasmInitInput } from "../wasm/index.ts";

package/src/node/cluster.ts

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+
+export type YydsProtocol = "redis" | "mysql" | "postgresql";
+
+const portFlags: Record<YydsProtocol, string> = {
+    redis: "--redis-port",
+    mysql: "--mysql-port",
+    postgresql: "--pgsql-port",
+};
+const defaultPorts: Partial<Record<YydsProtocol, number>> = { mysql: 3306, postgresql: 5432 };
+
+export function yydsStartArguments(protocol: YydsProtocol, args: string[]): string[] {
+    const result = ["start"];
+    let protocolPortProvided = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (["--port", "-p", "-P"].includes(argument)) {
+            const value = args[++index];
+            if (value === undefined || value.startsWith("-"))
+                throw new Error(`missing port after ${argument}`);
+            result.push(portFlags[protocol], value);
+            protocolPortProvided = true;
+        } else {
+            result.push(argument);
+            if (argument === portFlags[protocol]) protocolPortProvided = true;
+        }
+    }
+    const defaultPort = defaultPorts[protocol];
+    if (!protocolPortProvided && defaultPort !== undefined)
+        result.push(portFlags[protocol], String(defaultPort));
+    return result;
+}
+
+export function launchYydsServer(protocol: YydsProtocol, args: string[]): Promise<number> {
+    const executable = process.env.YYDS_CLI_PATH || "yyds";
+    const child = spawn(executable, yydsStartArguments(protocol, args), {
+        stdio: "inherit",
+        windowsHide: true,
+    });
+    const forward = (signal: NodeJS.Signals) => child.kill(signal);
+    const onInterrupt = () => forward("SIGINT");
+    const onTerminate = () => forward("SIGTERM");
+    process.once("SIGINT", onInterrupt);
+    process.once("SIGTERM", onTerminate);
+
+    return new Promise((resolve, reject) => {
+        child.once("error", (error) =>
+            reject(new Error(`cannot start '${executable}': ${error.message}`)),
+        );
+        child.once("close", (code, signal) => {
+            process.removeListener("SIGINT", onInterrupt);
+            process.removeListener("SIGTERM", onTerminate);
+            resolve(code ?? (signal ? 1 : 0));
+        });
+    });
+}

package/src/node/index.ts

@@ -0,0 +1,20 @@
+/**
+ * `@yydb/yyds/node` — Node N-API facade.
+ *
+ * Browser code must use the default `@yydb/yyds` entry or `@yydb/yyds/wasm`.
+ */
+
+export type { YydsBindings } from "../bindings.ts";
+export type { YydsProtocol } from "./cluster.ts";
+export { launchYydsServer, yydsStartArguments } from "./cluster.ts";
+export { isYydsNativeInstalled, loadYydsNative, loadYydsSqliteNative } from "./load.ts";
+export type {
+    SqliteConnectionBinding,
+    SqliteQueryResultBinding,
+    SqliteReadLimits,
+    SqliteResultValueBinding,
+    SqliteSchemaObject,
+    SqliteSnapshotBinding,
+    SqliteTableRow,
+    YydsSqliteBindings,
+} from "./sqlite-bindings.ts";

package/src/node/load.ts

@@ -0,0 +1,50 @@
+import { createRequire } from "node:module";
+
+import type { YydsBindings } from "../bindings.ts";
+import { resolvePlatformPackage } from "./platform-packages.ts";
+import type { YydsSqliteBindings } from "./sqlite-bindings.ts";
+
+const require = createRequire(import.meta.url);
+
+function normalizeBinding(module: Record<string, unknown>): YydsBindings {
+    const binding = (module.default ?? module) as Record<string, unknown>;
+    return {
+        yydsVersion: () => String((binding.yydsVersion as () => string)()),
+        ping: () => String((binding.ping as () => string)()),
+    };
+}
+
+/** Load the platform-specific Node-API binding. */
+export function loadYydsNative(): YydsBindings {
+    const specifier = resolvePlatformPackage();
+    return normalizeBinding(require(specifier) as Record<string, unknown>);
+}
+
+/** Load the independent SQLite snapshot reader, not a YYDS execution session. */
+export function loadYydsSqliteNative(): YydsSqliteBindings {
+    const module = require(resolvePlatformPackage()) as Record<string, unknown>;
+    const binding = (module.default ?? module) as Record<string, unknown>;
+    if (
+        typeof binding.SqliteSnapshot !== "function" ||
+        typeof binding.SqliteConnection !== "function"
+    ) {
+        throw new Error(
+            "Native addon lacks the SQLite snapshot reader. Rebuild the native package.",
+        );
+    }
+    return {
+        SqliteSnapshot: binding.SqliteSnapshot as YydsSqliteBindings["SqliteSnapshot"],
+        SqliteConnection: binding.SqliteConnection as YydsSqliteBindings["SqliteConnection"],
+    };
+}
+
+/** Whether the current platform optional dependency is installed. */
+export function isYydsNativeInstalled(): boolean {
+    try {
+        resolvePlatformPackage();
+        require.resolve(resolvePlatformPackage());
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/node/platform-packages.ts

@@ -0,0 +1,15 @@
+const PLATFORM_PACKAGES: Record<string, string> = {
+    "win32-x64": "@yydb/yyds-win32-x64",
+    "darwin-x64": "@yydb/yyds-darwin-x64",
+    "darwin-arm64": "@yydb/yyds-darwin-arm64",
+    "linux-x64": "@yydb/yyds-linux-x64",
+};
+
+export function resolvePlatformPackage(): string {
+    const key = `${process.platform}-${process.arch}`;
+    const specifier = PLATFORM_PACKAGES[key];
+    if (!specifier) {
+        throw new Error(`@yydb/yyds/node: unsupported platform ${key}`);
+    }
+    return specifier;
+}

package/src/node/sqlite-bindings.ts

@@ -0,0 +1,64 @@
+/** Bounds apply independently to each schema or table scan. */
+export interface SqliteReadLimits {
+    maxPages?: number;
+    maxRows?: number;
+    maxPayloadBytes?: number;
+    maxTotalPayloadBytes?: number;
+}
+
+/** SQL source is opaque. No CREATE statement is parsed or executed. */
+export interface SqliteSchemaObject {
+    kind: "table" | "index" | "view" | "trigger";
+    name: string;
+    tableName: string;
+    rootPage?: number;
+    sql?: string;
+}
+
+/** Raw storage values, not SQL results or INTEGER PRIMARY KEY expansion. */
+export interface SqliteTableRow {
+    rowid: bigint;
+    payload: Buffer;
+}
+
+export interface SqliteSnapshotBinding {
+    schema(limits?: SqliteReadLimits): SqliteSchemaObject[];
+    table(name: string, limits?: SqliteReadLimits): SqliteTableRow[];
+}
+
+/** An independent SQLite reader hosted in the same native addon. */
+export interface YydsSqliteBindings {
+    SqliteSnapshot: new (bytes: Buffer, maxSnapshotBytes?: number) => SqliteSnapshotBinding;
+    SqliteConnection: new (path: string, readOnly?: boolean) => SqliteConnectionBinding;
+}
+
+export interface SqliteConnectionBinding {
+    execute(sql: string): SqliteQueryResultBinding;
+    executeWithParameters(sql: string, parameters: SqliteParameterBinding[]): SqliteQueryResultBinding;
+    executeBatch(sql: string): void;
+    sourceId(): string;
+}
+
+export interface SqliteParameterBinding {
+    kind: "null" | "integer" | "real" | "text" | "blob";
+    integer?: string;
+    real?: number;
+    text?: Buffer;
+    blob?: Buffer;
+}
+
+export interface SqliteQueryResultBinding {
+    columns: string[];
+    rows: SqliteResultValueBinding[][];
+    changes: string;
+    lastInsertRowid: string;
+}
+
+export interface SqliteResultValueBinding {
+    kind: "null" | "integer" | "real" | "text" | "blob";
+    integer?: string;
+    real?: number;
+    text?: string;
+    textBytes?: Buffer;
+    blob?: Buffer;
+}

package/src/node/unsupported.ts

@@ -0,0 +1 @@
+throw new Error("@yydb/yyds/node is only available in Node.js runtimes");

package/src/wasm/index.ts

@@ -0,0 +1,8 @@
+export {
+    initWasm,
+    ping,
+    resetWasmBindingForTests,
+    yydsVersion,
+    type InitWasmOptions,
+    type WasmInitInput,
+} from "@yydb/yyds-unknown-wasm32";

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.