@yydb/sqlite 0.0.0 → 0.0.2

package/bin/sqlite3.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+
+import { SqliteDatabase, SqliteSnapshot } from "../src/node.ts";
+
+const FORMAT_VERSION = "3.45.0";
+
+function runDotCommand(database, command) {
+    if (command === ".tables") {
+        const tables = database
+            .schema()
+            .filter((object) => (object.kind === "table" || object.kind === "view") && !object.name.startsWith("sqlite_"))
+            .map((object) => object.name)
+            .sort();
+        for (const name of tables) console.log(name);
+        return;
+    }
+    if (command === ".schema") {
+        const statements = database
+            .schema()
+            .filter((object) => object.sql && !object.name.startsWith("sqlite_"))
+            .map((object) => object.sql?.trimEnd() ?? "");
+        for (const source of statements) {
+            console.log(source.endsWith(";") ? source : `${source};`);
+        }
+        return;
+    }
+    if (command === ".ping") {
+        const status = database.ping();
+        console.log(`ok ${status}`);
+        return;
+    }
+    if (command === ".encoding") {
+        console.log(database.encoding());
+        return;
+    }
+    if (command === ".version") {
+        console.log(database.sqliteVersion());
+        return;
+    }
+    const dump = command.match(/^\.dump\s+(\S+)\s*$/);
+    if (dump) {
+        const table = dump[1];
+        const rows = database.table(table);
+        if (rows.length === 0) {
+            return;
+        }
+        const width = new Array(rows[0].columns.length).fill(0);
+        for (const row of rows) {
+            for (let i = 0; i < row.columns.length; i++) {
+                const text = formatValue(row.columns[i]);
+                width[i] = Math.max(width[i], text.length);
+            }
+        }
+        const line = (cells) => cells.map((c, i) => c.padEnd(width[i])).join(" | ");
+        for (const row of rows) {
+            console.log(
+                line([
+                    String(row.rowid),
+                    ...row.columns.map(formatValue),
+                ]),
+            );
+        }
+        return;
+    }
+    throw new Error(`unsupported dot command '${command}'`);
+}
+
+function formatValue(value) {
+    if (value.kind === "null") return "NULL";
+    if (value.kind === "integer") return String(value.valueInteger ?? "");
+    if (value.kind === "real") {
+        const n = value.valueReal;
+        return n === undefined ? "" : (Number.isInteger(n) ? `${n}.0` : String(n));
+    }
+    if (value.kind === "text") return value.valueText ?? "";
+    if (value.kind === "blob") {
+        const buf = value.valueBlob;
+        if (!buf) return "";
+        let hex = "";
+        for (let i = 0; i < Math.min(buf.length, 64); i++) {
+            hex += buf[i].toString(16).padStart(2, "0");
+        }
+        return `X'${hex}${buf.length > 64 ? "…" : ""}'`;
+    }
+    return "";
+}
+
+function main(args) {
+    if (args.length === 1 && ["--version", "-version"].includes(args[0])) {
+        console.log(`sqlite3 ${FORMAT_VERSION} (YYDS pure-Rust format-3 reader)`);
+        return;
+    }
+    if (args.length === 1 && ["--help", "-help"].includes(args[0])) {
+        console.log(
+            "Usage: sqlite3 DATABASE COMMAND\n" +
+                "Supported dot commands: .tables, .schema, .ping, .encoding, .version, .dump TABLE\n" +
+                "This CLI inspects on-disk main-file bytes only; SQL execution is not available.",
+        );
+        return;
+    }
+    if (args.length !== 2 || args[0].startsWith("-") || args[0] === "") {
+        throw new Error("expected DATABASE and one supported dot command");
+    }
+    const [path, input] = args;
+    const command = input.trim();
+    if (!command.startsWith(".")) {
+        throw new Error("SQL execution is not available; use a dot command");
+    }
+    const database = SqliteDatabase.open(path);
+    runDotCommand(database, command);
+}
+
+try {
+    main(process.argv.slice(2));
+} catch (error) {
+    console.error(`@yydb/sqlite: ${error.message}`);
+    process.exitCode = 1;
+}

package/package.json

@@ -1,10 +1,60 @@
 {
   "name": "@yydb/sqlite",
-  "version": "0.0.0",
-  "description": "SQL Studio placeholder — not for production use.",
-  "license": "MIT",
-  "private": false,
+  "version": "0.0.2",
+  "description": "Bounded read-only SQLite format-3 snapshot reader, independent of YYDS storage.",
+  "license": "MPL-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./node": {
+      "types": "./src/node.ts",
+      "import": "./src/node.ts",
+      "default": "./src/node.ts"
+    }
+  },
+  "bin": {
+    "sqlite3": "./bin/sqlite3.mjs"
+  },
   "files": [
-    "README.md"
-  ]
+    "bin",
+    "src",
+    "readme.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --experimental-strip-types --test \"./tests/**/*.test.ts\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yy-database/yyds.git",
+    "directory": "projects/packages/sqlite"
+  },
+  "homepage": "https://github.com/yy-database/yyds/tree/dev/projects/packages/sqlite#readme",
+  "bugs": {
+    "url": "https://github.com/yy-database/yyds/issues"
+  },
+  "keywords": [
+    "yyds",
+    "sqlite",
+    "disguise",
+    "binary-compatible"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@yydb/yyds": "0.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
 }

package/readme.md

@@ -0,0 +1,31 @@
+# @yydb/sqlite
+
+Read-only inspection of SQLite format-3 main files. Copies bytes into memory, lists schema objects, and reads raw table records. Does not execute SQL, open a live database, or recover WAL sidecars.
+
+SQLite files are not YYDS storage. They are not routed through `.yyds` catalogs or `.yykv` shards.
+
+## Exports
+
+| Subpath | Use |
+|---------|-----|
+| `@yydb/sqlite` | Types only |
+| `@yydb/sqlite/node` | `SqliteSnapshot` (requires the `@yydb/yyds` native addon) |
+
+The `sqlite3` command supports `.tables` and `.schema` on a file path. It does not run SQL statements.
+
+## Example
+
+```ts
+import { readFileSync } from "node:fs";
+import { SqliteSnapshot } from "@yydb/sqlite/node";
+
+const snapshot = new SqliteSnapshot(readFileSync("app.sqlite"));
+const tables = snapshot.schema().filter((o) => o.kind === "table");
+const rows = snapshot.table("samples", { maxRows: 100 });
+```
+
+Each row is `{ rowid: bigint, payload: Buffer }` — storage bytes, not SQL-projected values. Schema `sql` fields are opaque CREATE text. The default snapshot size cap is 256 MiB; each scan accepts `maxPages`, `maxRows`, `maxPayloadBytes`, and `maxTotalPayloadBytes`.
+
+## Related packages
+
+- [`@yydb/yyds`](https://github.com/yy-database/yyds/tree/dev/projects/packages/yyds) — hosts the native `SqliteSnapshot` binding

package/src/disguise.ts

@@ -0,0 +1,3 @@
+/** Why this package does not route through YY-optimized storage. */
+export const WHY_NOT_YY_OPTIMIZED =
+    "SQLite requires binary-compatible on-disk bytes. YYDS stores VOS in .yyds and .yykv instead.";

package/src/index.ts

@@ -0,0 +1,12 @@
+export type {
+    SqliteDatabaseBinding,
+    SqliteDecodedRow,
+    SqliteReadLimits,
+    SqliteRecordValue,
+    SqliteSchemaObject,
+    SqliteSnapshotBinding,
+    SqliteTableRow,
+    SqliteTextEncoding,
+} from "./node.ts";
+
+export { SqliteSnapshot, SqliteDatabase, decodeRecord } from "./node.ts";

package/src/node.ts

@@ -0,0 +1,195 @@
+import { loadYydsSqliteNative } from "@yydb/yyds/node";
+import type {
+    SqliteDatabaseBinding,
+    SqliteDecodedRow,
+    SqliteReadLimits,
+    SqliteRecordValue,
+    SqliteSchemaObject,
+    SqliteSnapshotBinding,
+    SqliteTableRow,
+} from "@yydb/yyds/node";
+
+export type {
+    SqliteDatabaseBinding,
+    SqliteDecodedRow,
+    SqliteReadLimits,
+    SqliteRecordValue,
+    SqliteSchemaObject,
+    SqliteSnapshotBinding,
+    SqliteTableRow,
+} from "@yydb/yyds/node";
+
+/** Text encodings recognised by the SQLite header. */
+export type SqliteTextEncoding = "utf8" | "utf16le" | "utf16be";
+
+/** Read-only, copied main-file bytes. WAL/journal recovery is not performed. */
+export class SqliteSnapshot {
+    readonly #native: SqliteSnapshotBinding;
+
+    constructor(bytes: Uint8Array, maxSnapshotBytes = 256 * 1024 * 1024) {
+        unsignedLimit(maxSnapshotBytes, "maxSnapshotBytes");
+        if (!(bytes instanceof Uint8Array)) {
+            throw new TypeError("SQLite snapshot must be a Uint8Array or Buffer");
+        }
+        if (bytes.byteLength > maxSnapshotBytes) {
+            throw new RangeError("sqlite snapshot byte limit exceeded");
+        }
+        const native = loadYydsSqliteNative();
+        this.#native = new native.SqliteSnapshot(Buffer.from(bytes), maxSnapshotBytes);
+    }
+
+    schema(limits?: SqliteReadLimits): SqliteSchemaObject[] {
+        return this.#native.schema(validateLimits(limits));
+    }
+
+    table(name: string, limits?: SqliteReadLimits): SqliteTableRow[] {
+        if (typeof name !== "string") {
+            throw new TypeError("SQLite table name must be a string");
+        }
+        return this.#native.table(name, validateLimits(limits));
+    }
+
+    /** Reads rows with decoded storage-class values. */
+    tableDecoded(name: string, limits?: SqliteReadLimits): SqliteDecodedRow[] {
+        if (typeof name !== "string") {
+            throw new TypeError("SQLite table name must be a string");
+        }
+        return this.#native.tableDecoded(name, validateLimits(limits));
+    }
+
+    /** SQLite library version stamped in the snapshot header. */
+    sqliteVersion(): string {
+        return this.#native.sqliteVersion();
+    }
+
+    /** Returns the header-claimed text encoding. */
+    encoding(): SqliteTextEncoding {
+        const name = this.#native.encoding();
+        if (name === "utf16le" || name === "utf16be" || name === "utf8") return name;
+        throw new Error(`Unexpected SQLite encoding label: ${name}`);
+    }
+
+    /** Health probe re-running the full main-file validation. Returns 1 on success. */
+    ping(): number {
+        return this.#native.ping();
+    }
+
+    /** Raw main-file bytes, including the page-size header. */
+    pages(): Buffer {
+        return this.#native.pages();
+    }
+}
+
+/**
+ * File-backed or blank in-memory SQLite snapshot handle.
+ *
+ * No WAL or journal recovery is performed and no SQL engine is present.
+ * Use this when the path and header meta matter beyond raw main-file bytes.
+ */
+export class SqliteDatabase {
+    readonly #native: SqliteDatabaseBinding;
+
+    private constructor(native: SqliteDatabaseBinding) {
+        this.#native = native;
+    }
+
+    /** Opens a blank in-memory SQLite format-3 snapshot. */
+    static openInMemory(): SqliteDatabase {
+        const native = loadYydsSqliteNative();
+        return new SqliteDatabase(native.SqliteDatabase.openInMemory());
+    }
+
+    /** Opens or creates a file-backed SQLite snapshot (main-file only). */
+    static open(path: string): SqliteDatabase {
+        if (typeof path !== "string" || path.length === 0) {
+            throw new TypeError("SQLite path must be a non-empty string");
+        }
+        const native = loadYydsSqliteNative();
+        return new SqliteDatabase(native.SqliteDatabase.open(path));
+    }
+
+    /** File path when file-backed, `null` for in-memory. */
+    path(): string | null {
+        return this.#native.path();
+    }
+
+    /** Health probe re-running the full main-file validation. Returns 1 on success. */
+    ping(): number {
+        return this.#native.ping();
+    }
+
+    /** SQLite library version stamped in the snapshot header. */
+    sqliteVersion(): string {
+        return this.#native.sqliteVersion();
+    }
+
+    /** Returns the header-claimed text encoding. */
+    encoding(): SqliteTextEncoding {
+        const name = this.#native.encoding();
+        if (name === "utf16le" || name === "utf16be" || name === "utf8") return name;
+        throw new Error(`Unexpected SQLite encoding label: ${name}`);
+    }
+
+    schema(limits?: SqliteReadLimits): SqliteSchemaObject[] {
+        return this.#native.schema(validateLimits(limits));
+    }
+
+    /** Reads rows with decoded storage-class values from an ordinary rowid table. */
+    table(name: string, limits?: SqliteReadLimits): SqliteDecodedRow[] {
+        if (typeof name !== "string") {
+            throw new TypeError("SQLite table name must be a string");
+        }
+        return this.#native.table(name, validateLimits(limits));
+    }
+
+    /** Reads raw rows (undecoded payload) from an ordinary rowid table. */
+    tableRaw(name: string, limits?: SqliteReadLimits): SqliteTableRow[] {
+        if (typeof name !== "string") {
+            throw new TypeError("SQLite table name must be a string");
+        }
+        return this.#native.tableRaw(name, validateLimits(limits));
+    }
+
+    /** Raw main-file bytes, including the page-size header. */
+    pages(): Buffer {
+        return this.#native.pages();
+    }
+}
+
+/**
+ * Decodes one SQLite record payload into typed storage-class values.
+ *
+ * Defaults to `utf8`. Feed the database header encoding (see `encoding()`)
+ * when the snapshot advertises utf16le or utf16be.
+ */
+export function decodeRecord(
+    payload: Uint8Array,
+    encoding?: SqliteTextEncoding,
+): SqliteRecordValue[] {
+    if (!(payload instanceof Uint8Array)) {
+        throw new TypeError("payload must be a Uint8Array or Buffer");
+    }
+    const native = loadYydsSqliteNative();
+    const encArg: string | undefined =
+        encoding === undefined ? undefined : encoding;
+    return native.decodeRecord(Buffer.from(payload), encArg);
+}
+
+function unsignedLimit(value: number, name: string): void {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {
+        throw new RangeError(`${name} must be an unsigned 32-bit integer`);
+    }
+}
+
+function validateLimits(limits?: SqliteReadLimits): SqliteReadLimits | undefined {
+    if (limits === undefined) return undefined;
+    if (limits === null || typeof limits !== "object" || Array.isArray(limits)) {
+        throw new TypeError("SQLite scan limits must be an object");
+    }
+    const keys = new Set(["maxPages", "maxRows", "maxPayloadBytes", "maxTotalPayloadBytes"]);
+    for (const [key, value] of Object.entries(limits)) {
+        if (!keys.has(key)) throw new TypeError(`Unknown SQLite scan limit: ${key}`);
+        if (value !== undefined) unsignedLimit(value, key);
+    }
+    return limits;
+}

package/README.md

@@ -1,3 +0,0 @@
-# @yydb/sqlite
-
-Placeholder package (0.0.0). Reserved for SQL Studio (@yydb/*) Developer Preview.