@dolthub/doltlite 0.10.0

package/README.md

@@ -0,0 +1,167 @@
+# @dolthub/doltlite
+
+Node.js native bindings for [DoltLite](https://github.com/dolthub/doltlite) — a SQLite fork that adds Git-style version control (branches, commits, merges, diffs, blame) to your SQL database.
+
+[![CI](https://github.com/dolthub/doltlite-node/actions/workflows/ci.yml/badge.svg)](https://github.com/dolthub/doltlite-node/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@dolthub/doltlite)](https://www.npmjs.com/package/@dolthub/doltlite)
+
+## Install
+
+```bash
+npm install @dolthub/doltlite
+# or
+bun add @dolthub/doltlite
+```
+
+Prebuilt binaries are provided for Linux x64/arm64, macOS x64/arm64, and Windows x64. On unsupported platforms the package builds from source via `node-gyp`, which requires a C/C++ toolchain and Python 3.
+
+## Drop-in compatibility with `node:sqlite`
+
+`DatabaseSync` and `StatementSync` match the [Node.js `node:sqlite`](https://nodejs.org/api/sqlite.html) API exactly. Switch by changing one import line:
+
+```diff
+-import { DatabaseSync } from "node:sqlite"
++import { DatabaseSync } from "@dolthub/doltlite"
+```
+
+## Basic usage
+
+```ts
+import { DatabaseSync } from "@dolthub/doltlite"
+
+const db = new DatabaseSync("myapp.db")
+
+db.exec(`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)`)
+
+const insert = db.prepare("INSERT INTO users (name) VALUES (?)")
+insert.run("Alice")
+insert.run("Bob")
+
+const all = db.prepare("SELECT * FROM users")
+console.log(all.all())
+// [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+
+db.close()
+```
+
+## Version control
+
+All Dolt features are methods on `DatabaseSync` under `dolt*` names:
+
+```ts
+const db = new DatabaseSync("versioned.db")
+
+db.exec(`CREATE TABLE orders (id INTEGER PRIMARY KEY, amount REAL)`)
+db.exec(`INSERT INTO orders VALUES (1, 99.99)`)
+
+// Commit the current state
+const hash = db.doltCommit("initial data")
+
+// Branch and make changes
+db.doltBranch("experiment")
+db.doltCheckout("experiment")
+db.exec(`INSERT INTO orders VALUES (2, 49.99)`)
+db.doltCommit("add order 2")
+
+// See what changed
+console.log(db.doltStatus())
+console.log(db.doltLog({ limit: 5 }))
+
+// Merge back to main
+db.doltCheckout("main")
+const result = db.doltMerge("experiment")
+console.log(result) // { fast_forward: 0, conflicts: 0 }
+
+// Inspect history
+console.log(db.doltDiff("HEAD~1", "HEAD", "orders"))
+console.log(db.doltHistoryOf("orders"))
+console.log(db.doltBlameOf("orders"))
+
+// Tag a release
+db.doltTag("v1.0.0")
+
+db.close()
+```
+
+You can also call Dolt SQL functions directly if you prefer:
+
+```ts
+db.exec("SELECT dolt_commit('-Am', 'my message')")
+```
+
+## API
+
+### `new DatabaseSync(path, options?)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `open` | boolean | `true` | Open immediately |
+| `readOnly` | boolean | `false` | Read-only mode |
+
+### node:sqlite-compatible methods
+
+| Method | Description |
+|--------|-------------|
+| `exec(sql)` | Run SQL, no return value |
+| `prepare(sql)` | Compile a `StatementSync` |
+| `close()` | Close the connection |
+| `open(path)` | (Re-)open at path |
+| `location()` | Filesystem path, or `null` for `:memory:` |
+| `createFunction(name, fn)` | Register a scalar UDF |
+| `.isOpen` | `true` if connection is open |
+| `.inTransaction` | `true` if inside a transaction |
+
+### StatementSync
+
+| Method | Returns |
+|--------|---------|
+| `run(...params)` | `{ changes, lastInsertRowid }` |
+| `get(...params)` | First row object, or `undefined` |
+| `all(...params)` | All row objects |
+| `iterate(...params)` | `IterableIterator` |
+| `columns()` | Column metadata array |
+| `.sourceSQL` | Original SQL text |
+| `.expandedSQL` | SQL with parameters expanded |
+
+### Dolt methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `doltCommit(message)` | `string` (hash) | Stage all and commit |
+| `doltBranch(name, from?)` | `void` | Create a branch |
+| `doltCheckout(branch)` | `void` | Switch branch |
+| `doltMerge(branch)` | `{ fast_forward, conflicts }` | Merge a branch |
+| `doltReset(flag?)` | `void` | Reset HEAD; pass `"--hard"` for hard reset |
+| `doltAdd(table?)` | `void` | Stage a table, or all tables |
+| `doltStatus()` | `DoltStatusEntry[]` | Working-set status |
+| `doltLog(opts?)` | `DoltCommit[]` | Commit history, newest first |
+| `doltBranches()` | `DoltBranchInfo[]` | All branches |
+| `doltActiveBranch()` | `string` | Currently checked-out branch |
+| `doltDiff(from, to, table)` | `DoltDiffRow[]` | Row-level diff between two refs |
+| `doltHashOf(ref?)` | `string` | Content hash of the DB at a ref |
+| `doltVersion()` | `string` | DoltLite version string |
+| `doltTag(name)` | `void` | Create a tag at HEAD |
+| `doltTags()` | `DoltTagInfo[]` | All tags |
+| `doltHistoryOf(table)` | `object[]` | Full row history across all commits |
+| `doltBlameOf(table)` | `object[]` | Per-row blame |
+| `doltCherryPick(hash)` | `void` | Cherry-pick a commit onto HEAD |
+| `doltRevert(ref?)` | `void` | Revert a commit (default: HEAD) |
+
+## Building from source
+
+```bash
+git clone https://github.com/dolthub/doltlite-node
+cd doltlite-node
+npm install   # downloads amalgamation + compiles
+bun test      # run the test suite
+```
+
+**Requirements:** Python 3, and a C/C++ compiler (`gcc`/`clang` on Linux/macOS, MSVC Build Tools on Windows).
+
+## Versioning
+
+The package version tracks the DoltLite version. `@dolthub/doltlite@0.10.0` ships the DoltLite 0.10.0 amalgamation.
+
+## License
+
+Apache-2.0. See [DoltLite](https://github.com/dolthub/doltlite) for the underlying library.

package/binding.gyp

@@ -0,0 +1,54 @@
+{
+  "targets": [
+    {
+      "target_name": "doltlite",
+      "sources": [
+        "amalgamation/doltlite_orig.c",
+        "amalgamation/doltlite.c",
+        "src/addon.cpp",
+        "src/database.cpp",
+        "src/statement.cpp"
+      ],
+      "include_dirs": [
+        "amalgamation",
+        "doltlite-src",
+        "doltlite-src/src",
+        "doltlite-src/ext/blake3",
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "defines": [
+        "NAPI_DISABLE_CPP_EXCEPTIONS",
+        "SQLITE_THREADSAFE=1",
+        "SQLITE_ENABLE_FTS5",
+        "SQLITE_ENABLE_JSON1",
+        "SQLITE_ENABLE_RTREE",
+        "SQLITE_ENABLE_COLUMN_METADATA",
+        "DOLTLITE_PROLLY=1"
+      ],
+      "cflags": ["-std=c11", "-fvisibility=hidden"],
+      "cflags_cc": ["-std=c++17", "-fvisibility=hidden"],
+      "xcode_settings": {
+        "GCC_ENABLE_CPP_EXCEPTIONS": "NO",
+        "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
+        "MACOSX_DEPLOYMENT_TARGET": "10.15"
+      },
+      "msvs_settings": {
+        "VCCLCompilerTool": {
+          "AdditionalOptions": ["/std:c++17"]
+        }
+      },
+      "conditions": [
+        ["OS=='linux'", {
+          "libraries": ["-lpthread", "-ldl", "-lm"],
+          "cflags": ["-fPIC"]
+        }],
+        ["OS=='mac'", {
+          "libraries": ["-lpthread"]
+        }],
+        ["OS=='win'", {
+          "defines": ["strncasecmp=_strnicmp"]
+        }]
+      ]
+    }
+  ]
+}

package/index.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @dolthub/doltlite — Node.js bindings for DoltLite
+ *
+ * `DatabaseSync` and `StatementSync` are intentionally compatible with the
+ * Node.js built-in `node:sqlite` module so existing consumers can switch by
+ * changing their import. Dolt-specific methods are added under `dolt*` names.
+ */
+
+export interface ColumnInfo {
+  name: string | null
+  column: string | null
+  table: string | null
+  database: string | null
+  type: string | null
+}
+
+export interface RunResult {
+  changes: number
+  lastInsertRowid: number
+}
+
+export interface MergeResult {
+  fast_forward: number
+  conflicts: number
+}
+
+export interface DoltCommit {
+  commit_hash: string
+  committer: string
+  committer_email: string
+  message: string
+  date: string
+  parents: string
+}
+
+export interface DoltBranchInfo {
+  name: string
+  hash: string
+  latest_committer: string
+  latest_committer_email: string
+  latest_commit_date: string
+  latest_commit_message: string
+}
+
+export interface DoltStatusEntry {
+  table_name: string
+  staged: number
+  status: string
+}
+
+export interface DoltDiffRow {
+  from_commit: string
+  from_commit_date: string
+  to_commit: string
+  to_commit_date: string
+  diff_type: "added" | "removed" | "modified"
+  [column: string]: unknown
+}
+
+export interface DoltTagInfo {
+  tag_name: string
+  tag_hash: string
+  tagger: string
+  tagger_email: string
+  date: string
+  message: string
+}
+
+export interface DatabaseSyncOptions {
+  /** Open the database immediately (default: true). */
+  open?: boolean
+  /** Open in read-only mode (default: false). */
+  readOnly?: boolean
+}
+
+export class StatementSync {
+  /** Execute the statement and return change metadata. */
+  run(...params: unknown[]): RunResult
+  /** Return the first result row, or undefined. */
+  get(...params: unknown[]): Record<string, unknown> | undefined
+  /** Return all result rows. */
+  all(...params: unknown[]): Record<string, unknown>[]
+  /** Return an iterator over result rows. */
+  iterate(...params: unknown[]): IterableIterator<Record<string, unknown>>
+  /** Return column metadata for the statement. */
+  columns(): ColumnInfo[]
+  /** The SQL source text of the statement. */
+  readonly sourceSQL: string
+  /** The SQL text with bound parameters expanded. */
+  readonly expandedSQL: string
+}
+
+export class DatabaseSync {
+  constructor(path: string, options?: DatabaseSyncOptions)
+
+  // ── node:sqlite-compatible API ──────────────────────────────────────────
+
+  /** Execute one or more SQL statements (no result returned). */
+  exec(sql: string): void
+  /** Compile a SQL statement for repeated execution. */
+  prepare(sql: string): StatementSync
+  /** Close the database connection. */
+  close(): void
+  /** (Re-)open the database at the given path. */
+  open(path: string): void
+  /** Return the filesystem path of the database, or null for :memory:. */
+  location(): string | null
+  /** Register a user-defined scalar SQL function. */
+  createFunction(name: string, fn: (...args: unknown[]) => unknown): void
+
+  /** True if the database connection is open. */
+  readonly isOpen: boolean
+  /** True if a transaction is currently active. */
+  readonly inTransaction: boolean
+
+  // ── Dolt version-control API ────────────────────────────────────────────
+
+  /**
+   * Stage all modified tables and create a commit.
+   * Returns the new commit hash.
+   */
+  doltCommit(message: string): string
+
+  /**
+   * Create a new branch, optionally from a specific source branch.
+   */
+  doltBranch(name: string, fromBranch?: string): void
+
+  /** Check out an existing branch. */
+  doltCheckout(branch: string): void
+
+  /**
+   * Merge a branch into HEAD.
+   * Returns `{fast_forward, conflicts}`.
+   */
+  doltMerge(branch: string): MergeResult
+
+  /** Reset HEAD. Pass `"--hard"` for a hard reset. */
+  doltReset(flag?: "--hard"): void
+
+  /** Return the working-set status (staged/unstaged changes). */
+  doltStatus(): DoltStatusEntry[]
+
+  /** Return commit history, newest first. */
+  doltLog(options?: { limit?: number }): DoltCommit[]
+
+  /** Return all branches. */
+  doltBranches(): DoltBranchInfo[]
+
+  /** Return the name of the currently active branch. */
+  doltActiveBranch(): string
+
+  /**
+   * Stage a table (or all tables if no argument) for the next commit.
+   */
+  doltAdd(table?: string): void
+
+  /**
+   * Return row-level diff between two refs for a given table.
+   */
+  doltDiff(fromRef: string, toRef: string, table: string): DoltDiffRow[]
+
+  /** Return the content hash of the database at a ref (default: HEAD). */
+  doltHashOf(ref?: string): string
+
+  /** Return the DoltLite version string. */
+  doltVersion(): string
+
+  /** Create a tag at HEAD. */
+  doltTag(name: string): void
+
+  /** Return all tags. */
+  doltTags(): DoltTagInfo[]
+
+  /**
+   * Return the full history of rows in a table across all commits.
+   * Equivalent to `SELECT * FROM dolt_history_<table>`.
+   */
+  doltHistoryOf(table: string): Record<string, unknown>[]
+
+  /**
+   * Return blame information for a table — which commit last modified each row.
+   * Equivalent to `SELECT * FROM dolt_blame_<table>`.
+   */
+  doltBlameOf(table: string): Record<string, unknown>[]
+
+  /** Cherry-pick a commit onto HEAD. */
+  doltCherryPick(commitHash: string): void
+
+  /** Revert a commit (default: HEAD). */
+  doltRevert(ref?: string): void
+}

package/index.js

@@ -0,0 +1,27 @@
+"use strict"
+
+const path = require("path")
+
+// Try a prebuilt binary first (shipped with published packages),
+// then fall back to a locally compiled build.
+function loadAddon() {
+  const platform = process.platform
+  const arch = process.arch
+  const prebuilt = path.join(__dirname, "prebuilds", `${platform}-${arch}`, "doltlite.node")
+  const compiled = path.join(__dirname, "build", "Release", "doltlite.node")
+
+  for (const candidate of [prebuilt, compiled]) {
+    try {
+      return require(candidate)
+    } catch {}
+  }
+
+  throw new Error(
+    `@dolthub/doltlite: no native binary found for ${platform}-${arch}.\n` +
+    `Run \`npm install\` to build from source, or file an issue at ` +
+    `https://github.com/dolthub/doltlite-node/issues`
+  )
+}
+
+const { DatabaseSync, StatementSync } = loadAddon()
+module.exports = { DatabaseSync, StatementSync }

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dolthub/doltlite",
+  "version": "0.10.0",
+  "description": "Node.js bindings for DoltLite — a SQLite fork with Git-style version control",
+  "license": "Apache-2.0",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "binding.gyp",
+    "scripts/download.js",
+    "prebuilds/"
+  ],
+  "scripts": {
+    "install": "node scripts/download.js && node-gyp rebuild",
+    "build": "node-gyp rebuild",
+    "build:debug": "node-gyp rebuild --debug",
+    "test": "bun test test/",
+    "test:watch": "bun test --watch test/"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "bun-types": "latest"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "sqlite",
+    "dolt",
+    "doltlite",
+    "database",
+    "version-control",
+    "sql",
+    "git"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dolthub/doltlite-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dolthub/doltlite-node/issues"
+  },
+  "homepage": "https://github.com/dolthub/doltlite-node#readme"
+}

package/scripts/download.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Downloads the doltlite autoconf source tarball from GitHub releases and
+// builds a complete amalgamation from it.
+//
+// The autoconf tarball contains both sqlite3.c (the base SQLite amalgamation
+// with doltlite's storage patches) and the prolly tree + dolt SQL function
+// source files under src/.  We stitch them into a single doltlite.c that,
+// when compiled with -DDOLTLITE_PROLLY=1, has full version-control support.
+
+"use strict"
+
+const https  = require("https")
+const fs     = require("fs")
+const path   = require("path")
+const { execSync } = require("child_process")
+
+const pkg     = require("../package.json")
+const version = pkg.version
+
+const amalgDir  = path.join(__dirname, "../amalgamation")
+const outC      = path.join(amalgDir, "doltlite.c")
+const outH      = path.join(amalgDir, "doltlite.h")
+const srcRoot   = path.join(__dirname, "../doltlite-src")
+
+// Skip if already built.
+if (fs.existsSync(outC) && fs.existsSync(outH)) {
+  process.exit(0)
+}
+
+const tarballUrl = `https://github.com/dolthub/doltlite/releases/download/v${version}/doltlite-autoconf-${version}.tar.gz`
+const tarballPath = path.join(__dirname, `../doltlite-autoconf-${version}.tar.gz`)
+
+console.log(`Downloading doltlite source v${version}...`)
+
+function download(url, dest, cb) {
+  const file = fs.createWriteStream(dest)
+  function get(url) {
+    https.get(url, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        return get(res.headers.location)
+      }
+      if (res.statusCode !== 200) {
+        cb(new Error(`HTTP ${res.statusCode} downloading ${url}`))
+        return
+      }
+      res.pipe(file)
+      file.on("finish", () => file.close(cb))
+    }).on("error", cb)
+  }
+  get(url)
+}
+
+download(tarballUrl, tarballPath, (err) => {
+  if (err) {
+    console.error("Failed to download doltlite source:", err.message)
+    process.exit(1)
+  }
+
+  try {
+    fs.rmSync(srcRoot, { recursive: true, force: true })
+    fs.mkdirSync(srcRoot, { recursive: true })
+
+    // Extract tarball — tar is available on Linux, macOS, and Windows 10+.
+    execSync(`tar xzf "${tarballPath}" -C "${srcRoot}"`, { stdio: "inherit" })
+    fs.unlinkSync(tarballPath)
+
+    // The tarball nests everything under doltlite-autoconf-${version}/.
+    // Flatten it so doltlite-src/src/ and doltlite-src/sqlite3.c are the
+    // canonical paths that build-amalgamation.js expects.
+    const entries = fs.readdirSync(srcRoot)
+    if (entries.length === 1 && fs.statSync(path.join(srcRoot, entries[0])).isDirectory()) {
+      const subdir = path.join(srcRoot, entries[0])
+      for (const f of fs.readdirSync(subdir)) {
+        fs.renameSync(path.join(subdir, f), path.join(srcRoot, f))
+      }
+      fs.rmdirSync(subdir)
+    }
+
+    // Build the complete amalgamation.
+    execSync(`node "${path.join(__dirname, "build-amalgamation.js")}"`, { stdio: "inherit" })
+
+    console.log("Source ready.")
+  } catch (e) {
+    console.error("Failed to prepare doltlite source:", e.message)
+    process.exit(1)
+  }
+})

package/src/addon.cpp

@@ -0,0 +1,15 @@
+#include "database.h"
+#include "statement.h"
+
+extern "C" int doltliteInstallAutoExt(void);
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  doltliteInstallAutoExt();
+  // StatementSync must be initialised first so its constructor_ is set before
+  // Database::Prepare() can call Statement::Create().
+  Statement::Init(env, exports);
+  Database::Init(env, exports);
+  return exports;
+}
+
+NODE_API_MODULE(doltlite, Init)