@mygo-plugins/sqlite 0.0.0-stage → 0.2.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyGo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# SQLite
 
-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.
+SQLite for MyGo, with Go connections and the `@mygo-plugins/sqlite`
+TypeScript client. The plugin ships prebuilt SQLite libraries and loads
+them through purego, so apps build without cgo or a C compiler.
+
+Register `mygo.Use(sqlite.Plugin)` only when the web frontend uses
+`@mygo-plugins/sqlite`. Go and native UI apps call `sqlite.Open` directly;
+they need no plugin registration and close their own connections.
+
+```go
+import (
+    "github.com/egoist/mygo"
+    "github.com/egoist/mygo/plugins/sqlite"
+)
+
+func main() {
+    mygo.Use(sqlite.Plugin)
+    // Create windows, then call mygo.App.Run().
+}
+```
+
+```ts
+import { open } from "@mygo-plugins/sqlite";
+
+const db = await open("app.db");
+await db.execute("CREATE TABLE IF NOT EXISTS tasks (id INTEGER PRIMARY KEY, title TEXT, done INTEGER)");
+const inserted = await db.execute("INSERT INTO tasks(title, done) VALUES (?, ?)", ["Learn MyGo", false]);
+const { columns, rows } = await db.query("SELECT id, title, done FROM tasks WHERE done = ?", [false]);
+await db.transaction([
+  { sql: "UPDATE tasks SET done = ? WHERE id = ?", params: [true, inserted.lastInsertId] },
+  { sql: "INSERT INTO tasks(title, done) VALUES (?, ?)", params: ["Ship the app", false] },
+]);
+await db.close();
+```
+
+Use `bun add @mygo-plugins/sqlite` once the npm package is published. In a
+checkout, `bun install && bun run build` installs and builds the workspace
+package. See [the full guide](../../docs/plugins/sqlite.md) for the Go API,
+types, cancellation, options and packaging.
+
+## Building the native libraries
+
+Prebuilt libraries are published in
+[sqlite-3.53.4-1](https://github.com/egoist/mygo/releases/tag/sqlite-3.53.4-1).
+CI and unpackaged programs download the matching library and verify its
+SHA-256. Testing and building apps require no Zig installation.
+
+To update SQLite or its C shim, with Zig **0.16.0** on the path:
+
+```sh
+go generate ./plugins/sqlite
+# Or build just this machine, from plugins/sqlite:
+go run ./internal/libbuild -target host
+```
+
+The generator downloads SQLite **3.53.4** from sqlite.org and checks its
+published SHA3-256 before extracting `sqlite3.c` and `sqlite3.h`. It builds
+macOS, Linux and Windows for amd64 and arm64, writes SHA-256 and release
+URLs to `mygo-plugin.json`, and populates the CLI's native-library cache.
+`mygo dev` and `mygo build` discover the manifest and bundle the matching
+library; macOS universal builds combine both architectures. Linux targets
+glibc 2.28 or later; macOS targets 12 or later. Binaries in `build/` are
+ignored by git.
+
+New binaries must be published before a fresh checkout or app build can
+download them. The default asset release is `sqlite-3.53.4-1`:
+
+```sh
+gh release create sqlite-3.53.4-1 plugins/sqlite/build/* --latest=false \
+  --title "SQLite 3.53.4 for MyGo" --notes "SQLite compiled with Zig 0.16.0 and the MyGo C shim."
+```
+
+Change the asset tag (or pass `-release <URL>`) when the shim, compiler or
+compile options change; regenerate and publish the manifest and binaries
+together. `-src <directory>` uses a local amalgamation instead of the
+verified download, intended for development.
+
+`MYGO_SQLITE_LIBRARY` overrides the library path. Otherwise the plugin
+looks in app resources, next to the executable, then the CLI's cache.
+Unpackaged programs download a missing library and verify its SHA-256;
+packaged apps never download native code at run time.
+
+SQLite is public domain; the plugin and C shim use the repository's MIT
+license. FTS5, RTree and JSON are enabled, with foreign keys on by default.
+Loadable extensions, shared cache and deprecated APIs are omitted.

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/** SQLite values: integers beyond Number's safe range are returned as bigint. */
+export type Value = null | number | bigint | string | Uint8Array;
+/** Booleans bind as SQLite integers 0 and 1. */
+export type Parameter = Value | boolean;
+export interface OpenOptions {
+    readOnly?: boolean;
+}
+export interface Result {
+    changes: number;
+    /** The last inserted rowid on this connection, without precision loss. */
+    lastInsertId: bigint;
+}
+/** Ordered columns and cells preserve duplicate column names. */
+export interface Rows {
+    columns: string[];
+    rows: Value[][];
+}
+export interface Statement {
+    sql: string;
+    params?: readonly Parameter[];
+}
+/** Opens a file name in the Go plugin's directory, or a private :memory: database. */
+export declare function open(name: string, options?: OpenOptions): Promise<Database>;
+/** A page-owned connection. It closes when the page navigates or the app quits. */
+export declare class Database {
+    private readonly id;
+    private closing?;
+    private closed;
+    private constructor();
+    static open(name: string, options?: OpenOptions): Promise<Database>;
+    /** Executes exactly one statement. Use placeholders, never interpolate values. */
+    execute(sql: string, params?: readonly Parameter[]): Promise<Result>;
+    /** Queries one statement, including RETURNING; select a bounded page for large results. */
+    query(sql: string, params?: readonly Parameter[]): Promise<Rows>;
+    /** Runs an atomic BEGIN IMMEDIATE batch. A failure rolls back every statement. */
+    transaction(statements: readonly Statement[]): Promise<Result[]>;
+    /** Closes this connection. Concurrent and repeated closes share the same call. */
+    close(): Promise<void>;
+    private assertOpen;
+}

package/dist/index.js

@@ -0,0 +1,104 @@
+// src/index.ts
+import { call } from "mygo-runtime";
+async function open(name, options = {}) {
+  return Database.open(name, options);
+}
+
+class Database {
+  id;
+  closing;
+  closed = false;
+  constructor(id) {
+    this.id = id;
+  }
+  static async open(name, options = {}) {
+    const id = await call("plugin:sqlite.Open", name, { readOnly: options.readOnly ?? false });
+    return new Database(id);
+  }
+  async execute(sql, params = []) {
+    this.assertOpen();
+    return result(await call("plugin:sqlite.Execute", this.id, sql, params.map(encode)));
+  }
+  async query(sql, params = []) {
+    this.assertOpen();
+    const value = await call("plugin:sqlite.Query", this.id, sql, params.map(encode));
+    return { columns: value.columns, rows: value.rows.map((row) => row.map(decode)) };
+  }
+  async transaction(statements) {
+    this.assertOpen();
+    const batch = statements.map((stmt) => ({ sql: stmt.sql, args: (stmt.params ?? []).map(encode) }));
+    return (await call("plugin:sqlite.Transaction", this.id, batch)).map(result);
+  }
+  close() {
+    if (this.closed)
+      return Promise.resolve();
+    if (!this.closing) {
+      this.closing = call("plugin:sqlite.Close", this.id).then(() => {
+        this.closed = true;
+      }, (error) => {
+        this.closing = undefined;
+        throw error;
+      });
+    }
+    return this.closing;
+  }
+  assertOpen() {
+    if (this.closed || this.closing)
+      throw new Error("sqlite: database is closed");
+  }
+}
+function result(value) {
+  return { changes: value.changes, lastInsertId: BigInt(value.lastInsertId) };
+}
+function encode(value) {
+  if (value === null)
+    return { type: "null" };
+  if (typeof value === "boolean")
+    return { type: "integer", integer: value ? "1" : "0" };
+  if (typeof value === "bigint") {
+    if (value < -(1n << 63n) || value >= 1n << 63n)
+      throw new RangeError("sqlite: integer exceeds signed 64-bit range");
+    return { type: "integer", integer: String(value) };
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new TypeError("sqlite: number must be finite");
+    if (Number.isInteger(value)) {
+      if (!Number.isSafeInteger(value))
+        throw new RangeError("sqlite: use bigint for integers outside Number's safe range");
+      return { type: "integer", integer: String(value) };
+    }
+    return { type: "real", real: value };
+  }
+  if (typeof value === "string")
+    return { type: "text", text: value };
+  if (value instanceof Uint8Array) {
+    let text = "";
+    for (let i = 0;i < value.length; i += 8192)
+      text += String.fromCharCode(...value.subarray(i, i + 8192));
+    return { type: "blob", blob: btoa(text) };
+  }
+  throw new TypeError("sqlite: unsupported parameter");
+}
+function decode(value) {
+  switch (value.type) {
+    case "null":
+      return null;
+    case "integer": {
+      const n = BigInt(value.integer);
+      return n >= BigInt(Number.MIN_SAFE_INTEGER) && n <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(n) : n;
+    }
+    case "real":
+      return Number(value.special ?? value.real ?? 0);
+    case "text":
+      return value.text ?? "";
+    case "blob":
+      return Uint8Array.from(atob(value.blob ?? ""), (c) => c.charCodeAt(0));
+    default:
+      throw new TypeError(`sqlite: unknown value type ${value.type}`);
+  }
+}
+export {
+  Database,
+  open
+};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@mygo-plugins/sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.17",
+  "description": "Parameterized SQLite queries and transactions for MyGo desktop apps",
+  "keywords": [
+    "mygo",
+    "desktop",
+    "sqlite",
+    "go",
+    "zig"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egoist/mygo.git",
+    "directory": "plugins/sqlite"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run ../build.ts",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "mygo-runtime": "^0.2.17"
+  },
+  "devDependencies": {
+    "mygo-runtime": "^0.2.17"
+  }
+}