@photostructure/sqlite 0.4.0 → 1.0.0

package/src/enhance.ts

@@ -3,9 +3,9 @@
  * compatible database, including `node:sqlite` DatabaseSync and this package's
  * DatabaseSync.
  *
- * This module provides the `enhance()` function which adds `.pragma()` and
- * `.transaction()` methods to database instances that don't have them (e.g.,
- * node:sqlite DatabaseSync).
+ * This module provides the `enhance()` function which adds `.pragma()`,
+ * `.transaction()`, and statement modes (`.pluck()`, `.raw()`, `.expand()`)
+ * to database instances that don't have them (e.g., node:sqlite DatabaseSync).
  */
 
 import { createTransaction } from "./transaction";
@@ -21,10 +21,88 @@ export interface EnhanceableDatabaseSync {
   exec(sql: string): void;
   /** Prepare a statement that can return results */
   prepare(sql: string): { all(): unknown[] };
+  /** Whether the database connection is open */
+  readonly isOpen?: boolean;
   /** Whether a transaction is currently active */
   readonly isTransaction: boolean;
 }
 
+/**
+ * Statement mode matching better-sqlite3's mutually exclusive modes.
+ * - "flat": Default — rows as `{ column: value }` objects
+ * - "pluck": First column value only
+ * - "raw": Rows as arrays of values
+ * - "expand": Rows namespaced by table, e.g. `{ users: { id: 1 }, posts: { title: "..." } }`
+ */
+type StatementMode = "flat" | "pluck" | "raw" | "expand";
+
+/**
+ * A statement enhanced with better-sqlite3-style `.pluck()`, `.raw()`, and
+ * `.expand()` methods. These are mutually exclusive — enabling one disables
+ * the others.
+ */
+export interface EnhancedStatementMethods {
+  /**
+   * Causes the statement to return only the first column value of each row.
+   *
+   * When plucking is turned on, raw and expand modes are turned off.
+   *
+   * @param toggle Enable (true) or disable (false) pluck mode. Defaults to true.
+   * @returns The same statement for chaining.
+   *
+   * @example
+   * ```typescript
+   * const count = db.prepare("SELECT COUNT(*) FROM users").pluck().get();
+   * // Returns: 42 (not { "COUNT(*)": 42 })
+   *
+   * const names = db.prepare("SELECT name FROM users").pluck().all();
+   * // Returns: ["Alice", "Bob"] (not [{ name: "Alice" }, { name: "Bob" }])
+   * ```
+   */
+  pluck(toggle?: boolean): this;
+
+  /**
+   * Causes the statement to return rows as arrays of values instead of objects.
+   *
+   * When raw mode is turned on, pluck and expand modes are turned off.
+   *
+   * @param toggle Enable (true) or disable (false) raw mode. Defaults to true.
+   * @returns The same statement for chaining.
+   *
+   * @example
+   * ```typescript
+   * const rows = db.prepare("SELECT id, name FROM users").raw().all();
+   * // Returns: [[1, "Alice"], [2, "Bob"]] (not [{ id: 1, name: "Alice" }, ...])
+   * ```
+   */
+  raw(toggle?: boolean): this;
+
+  /**
+   * Causes the statement to return data namespaced by table. Each key in a row
+   * object will be a table name, and each corresponding value will be a nested
+   * object containing that table's columns. Columns from expressions or
+   * subqueries are placed under the special `$` namespace.
+   *
+   * When expand mode is turned on, pluck and raw modes are turned off.
+   *
+   * Requires the statement to have a `.columns()` method (available on real
+   * statements but not minimal mocks).
+   *
+   * @param toggle Enable (true) or disable (false) expand mode. Defaults to true.
+   * @returns The same statement for chaining.
+   *
+   * @example
+   * ```typescript
+   * const rows = db.prepare("SELECT u.id, u.name, p.title FROM users u JOIN posts p ON ...").expand().all();
+   * // Returns: [{ users: { id: 1, name: "Alice" }, posts: { title: "Hello" } }]
+   * ```
+   */
+  expand(toggle?: boolean): this;
+
+  /** The database instance this statement was prepared from. */
+  readonly database: EnhanceableDatabaseSync;
+}
+
 /**
  * Interface for an enhanced database with pragma() and transaction() methods.
  */
@@ -63,10 +141,248 @@ export interface EnhancedMethods {
 }
 
 /**
- * A database instance that has been enhanced with pragma() and transaction() methods.
+ * A database instance that has been enhanced with pragma(), transaction(),
+ * and statement modes (pluck/raw/expand) on statements returned by prepare().
+ */
+export type EnhancedDatabaseSync<T extends EnhanceableDatabaseSync> = Omit<
+  T,
+  "prepare"
+> &
+  EnhancedMethods & {
+    prepare(
+      ...args: Parameters<T["prepare"]>
+    ): ReturnType<T["prepare"]> & EnhancedStatementMethods;
+  };
+
+/** Symbol to track whether prepare() has been wrapped */
+const ENHANCED_PREPARE = Symbol.for("@photostructure/sqlite:enhancedPrepare");
+
+/**
+ * Extract the first column value from a row object or array.
+ */
+function extractFirstColumn(row: unknown): unknown {
+  if (row == null) return row;
+  if (Array.isArray(row)) return row[0];
+  const keys = Object.keys(row as Record<string, unknown>);
+  return keys.length > 0
+    ? (row as Record<string, unknown>)[keys[0]!]
+    : undefined;
+}
+
+/**
+ * Build a column-to-table mapping from statement metadata, used by expand mode.
+ * Returns an array parallel to column order: each entry is the table name
+ * (or "$" for expressions/subqueries) and the column name.
  */
-export type EnhancedDatabaseSync<T extends EnhanceableDatabaseSync> = T &
-  EnhancedMethods;
+function buildColumnTableMap(
+  stmt: any,
+): Array<{ table: string; column: string }> | undefined {
+  if (typeof stmt.columns !== "function") return undefined;
+  const cols: Array<{ name: string; table: string | null }> = stmt.columns();
+  return cols.map((c) => ({
+    table: c.table ?? "$",
+    column: c.name,
+  }));
+}
+
+/**
+ * Transform a row array into a table-namespaced expanded object.
+ * Uses array indices to match columns, avoiding data loss from duplicate names.
+ */
+function expandRowFromArray(
+  row: unknown[],
+  columnMap: Array<{ table: string; column: string }>,
+): Record<string, Record<string, unknown>> {
+  const result: Record<string, Record<string, unknown>> = {};
+  for (let i = 0; i < columnMap.length && i < row.length; i++) {
+    const { table, column } = columnMap[i]!; // eslint-disable-line security/detect-object-injection
+    // eslint-disable-next-line security/detect-object-injection -- table/column from our own columnMap
+    result[table] ??= {};
+    result[table]![column] = row[i]; // eslint-disable-line security/detect-object-injection
+  }
+  return result;
+}
+
+/**
+ * Transform a flat row object into a table-namespaced expanded object.
+ * Fallback for mocks without setReturnArrays — cannot handle duplicate column
+ * names correctly, but mocks typically don't produce them.
+ */
+function expandRowFromObject(
+  row: Record<string, unknown>,
+  columnMap: Array<{ table: string; column: string }>,
+): Record<string, Record<string, unknown>> {
+  const result: Record<string, Record<string, unknown>> = {};
+  const keys = Object.keys(row);
+  for (let i = 0; i < keys.length && i < columnMap.length; i++) {
+    const { table, column } = columnMap[i]!; // eslint-disable-line security/detect-object-injection
+    // eslint-disable-next-line security/detect-object-injection -- table/column from our own columnMap
+    result[table] ??= {};
+    result[table]![column] = row[keys[i]!]; // eslint-disable-line security/detect-object-injection
+  }
+  return result;
+}
+
+/**
+ * Validate a boolean toggle argument, matching better-sqlite3's pattern.
+ */
+function validateToggle(value: unknown): boolean {
+  const use = value === undefined ? true : value;
+  if (typeof use !== "boolean") {
+    throw new TypeError("Expected first argument to be a boolean");
+  }
+  return use;
+}
+
+/**
+ * Transform a row based on the current statement mode.
+ */
+function transformRow(
+  row: unknown,
+  mode: StatementMode,
+  columnMap: Array<{ table: string; column: string }> | undefined,
+): unknown {
+  if (row == null || mode === "flat") return row;
+  if (mode === "pluck") return extractFirstColumn(row);
+  if (mode === "expand") {
+    // columnMap is guaranteed non-null here — setMode() throws if columns() is
+    // unavailable, so we'll never reach this branch with columnMap == null.
+    // Prefer array-based expand (used when setReturnArrays is available)
+    // to correctly handle duplicate column names across tables.
+    // Fall back to object-based expand for mocks without setReturnArrays.
+    if (Array.isArray(row)) {
+      return expandRowFromArray(row, columnMap!);
+    }
+    return expandRowFromObject(row as Record<string, unknown>, columnMap!);
+  }
+  // "raw" mode is handled natively by setReturnArrays(), so no transform needed
+  return row;
+}
+
+/**
+ * Add `.pluck()`, `.raw()`, and `.expand()` methods to a statement instance.
+ * These modes are mutually exclusive — enabling one disables the others,
+ * matching better-sqlite3's behavior.
+ */
+function enhanceStatement<S extends { all(): unknown[] }>(
+  stmt: S,
+): S & EnhancedStatementMethods {
+  // Idempotency: if already enhanced, return as-is
+  if (typeof (stmt as any).pluck === "function") {
+    return stmt as S & EnhancedStatementMethods;
+  }
+
+  let mode: StatementMode = "flat";
+  let columnMap: Array<{ table: string; column: string }> | undefined;
+
+  // Cast to any to avoid TypeScript strictness around bound method signatures.
+  // At runtime these are native C++ methods that accept variadic bind parameters.
+  const originalGet: any =
+    typeof (stmt as any).get === "function"
+      ? (stmt as any).get.bind(stmt)
+      : undefined;
+  const originalAll: any = (stmt as any).all.bind(stmt);
+  const originalIterate: any =
+    typeof (stmt as any).iterate === "function"
+      ? (stmt as any).iterate.bind(stmt)
+      : undefined;
+
+  // Toggle helper matching better-sqlite3's mode switching:
+  // enable(true) sets to target mode; enable(false) resets to flat ONLY if
+  // currently in that mode, otherwise leaves mode unchanged.
+  function setMode(target: StatementMode, use: boolean): void {
+    if (use) {
+      mode = target;
+      // Cache column map on first expand() call
+      if (target === "expand" && columnMap == null) {
+        columnMap = buildColumnTableMap(stmt);
+        if (columnMap == null) {
+          throw new TypeError(
+            "expand() requires the statement to have a columns() method",
+          );
+        }
+      }
+    } else if (mode === target) {
+      mode = "flat";
+    }
+    // If use=false and mode !== target, no-op (matches better-sqlite3)
+
+    // Sync native array mode: both raw and expand need arrays from the native layer.
+    // Expand needs arrays to correctly handle duplicate column names across tables.
+    if (typeof (stmt as any).setReturnArrays === "function") {
+      (stmt as any).setReturnArrays(mode === "raw" || mode === "expand");
+    }
+  }
+
+  Object.defineProperty(stmt, "pluck", {
+    value: function pluck(toggle?: boolean): S {
+      setMode("pluck", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+
+  Object.defineProperty(stmt, "raw", {
+    value: function raw(toggle?: boolean): S {
+      setMode("raw", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+
+  Object.defineProperty(stmt, "expand", {
+    value: function expand(toggle?: boolean): S {
+      setMode("expand", validateToggle(toggle));
+      return stmt;
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+
+  if (originalGet != null) {
+    Object.defineProperty(stmt, "get", {
+      value: (...params: any[]) => {
+        const row = originalGet(...params);
+        return transformRow(row, mode, columnMap);
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  Object.defineProperty(stmt, "all", {
+    value: (...params: any[]) => {
+      const rows = originalAll(...params);
+      if (mode === "flat" || mode === "raw") return rows;
+      return rows.map((row: unknown) => transformRow(row, mode, columnMap));
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+
+  if (originalIterate != null) {
+    Object.defineProperty(stmt, "iterate", {
+      value: function* (...params: any[]) {
+        const iter = originalIterate(...params);
+        for (const row of iter) {
+          yield transformRow(row, mode, columnMap);
+        }
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  return stmt as S & EnhancedStatementMethods;
+}
 
 /**
  * Implementation of pragma() that works on any EnhanceableDatabaseSync.
@@ -95,23 +411,12 @@ function pragmaImpl(
   }
 
   const stmt = this.prepare(`PRAGMA ${source}`);
-  const rows = stmt.all() as Record<string, unknown>[];
 
   if (simple) {
-    // Return the first column of the first row, or undefined if no rows
-    const firstRow = rows[0];
-    if (firstRow == null) {
-      return undefined;
-    }
-    const keys = Object.keys(firstRow);
-    const firstKey = keys[0];
-    if (firstKey == null) {
-      return undefined;
-    }
-    return firstRow[firstKey];
+    return extractFirstColumn(stmt.all()[0]);
   }
 
-  return rows;
+  return stmt.all();
 }
 
 /**
@@ -139,71 +444,93 @@ function hasEnhancedMethods(
 }
 
 /**
- * Ensures that `.pragma()` and `.transaction()` methods are available on the
- * given database.
+ * Ensures that `.pragma()`, `.transaction()`, and statement modes
+ * (`.pluck()`, `.raw()`, `.expand()`) are available on the given database.
  *
  * This function can enhance:
  * - `node:sqlite` DatabaseSync instances (adds the methods)
- * - `@photostructure/sqlite` DatabaseSync instances (no-op, already has these
- *   methods)
+ * - `@photostructure/sqlite` DatabaseSync instances (adds the methods)
  * - Any object with compatible `exec()`, `prepare()`, and `isTransaction`
  *
  * The enhancement is done by adding methods directly to the instance, not the
  * prototype, so it won't affect other instances or the original class.
  *
  * @param db The database instance to enhance
- * @returns The same instance with `.pragma()` and `.transaction()` methods
- * guaranteed
+ * @returns The same instance with `.pragma()`, `.transaction()`, and
+ * `.pluck()` / `.raw()` / `.expand()` (on prepared statements) guaranteed
  *
  * @example
  * ```typescript
- * // With node:sqlite
- * import { DatabaseSync } from 'node:sqlite';
- * import { enhance } from '@photostructure/sqlite';
+ * import { DatabaseSync, enhance } from '@photostructure/sqlite';
  *
  * const db = enhance(new DatabaseSync(':memory:'));
  *
- * // Now you can use better-sqlite3-style methods
+ * // better-sqlite3-style pragma
  * db.pragma('journal_mode = wal');
+ *
+ * // better-sqlite3-style transactions
  * const insertMany = db.transaction((items) => {
  *   for (const item of items) insert.run(item);
  * });
- * ```
  *
- * @example
- * ```typescript
- * // With @photostructure/sqlite (no-op, already enhanced)
- * import { DatabaseSync, enhance } from '@photostructure/sqlite';
- *
- * const db = enhance(new DatabaseSync(':memory:'));
- * // db already had these methods, enhance() just returns it unchanged
+ * // better-sqlite3-style pluck
+ * const count = db.prepare("SELECT COUNT(*) FROM users").pluck().get();
+ * const names = db.prepare("SELECT name FROM users").pluck().all();
  * ```
  */
 export function enhance<T extends EnhanceableDatabaseSync>(
   db: T,
 ): EnhancedDatabaseSync<T> {
-  // If already enhanced, return as-is
-  if (hasEnhancedMethods(db)) {
-    return db;
+  // Add pragma and transaction if not already present
+  if (!hasEnhancedMethods(db)) {
+    // Using Object.defineProperty to make them non-enumerable like native methods
+    Object.defineProperty(db, "pragma", {
+      value: pragmaImpl,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+
+    Object.defineProperty(db, "transaction", {
+      value: transactionImpl,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
   }
 
-  // Add methods directly to the instance
-  // Using Object.defineProperty to make them non-enumerable like native methods
-  Object.defineProperty(db, "pragma", {
-    value: pragmaImpl,
-    writable: true,
-    configurable: true,
-    enumerable: false,
-  });
+  // Wrap prepare() to add pluck() to returned statements
+  // eslint-disable-next-line security/detect-object-injection -- ENHANCED_PREPARE is a Symbol
+  if (!(db as any)[ENHANCED_PREPARE]) {
+    const originalPrepare: any = db.prepare.bind(db);
 
-  Object.defineProperty(db, "transaction", {
-    value: transactionImpl,
-    writable: true,
-    configurable: true,
-    enumerable: false,
-  });
+    Object.defineProperty(db, "prepare", {
+      value: (...args: any[]) => {
+        const stmt = originalPrepare(...args);
+        enhanceStatement(stmt);
+        // Add stmt.database back-reference for better-sqlite3 compat
+        Object.defineProperty(stmt, "database", {
+          value: db,
+          writable: false,
+          configurable: true,
+          enumerable: false,
+        });
+        return stmt;
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+
+    Object.defineProperty(db, ENHANCED_PREPARE, {
+      value: true,
+      writable: false,
+      configurable: false,
+      enumerable: false,
+    });
+  }
 
-  return db as EnhancedDatabaseSync<T>;
+  return db as unknown as EnhancedDatabaseSync<T>;
 }
 
 /**

package/src/index.ts

@@ -3,7 +3,10 @@ import nodeGypBuild from "node-gyp-build";
 import { join } from "node:path";
 import { _dirname } from "./dirname";
 import { SQLTagStore } from "./sql-tag-store";
-import { DatabaseSyncInstance } from "./types/database-sync-instance";
+import {
+  DatabaseSyncInstance,
+  DatabaseSyncLimits,
+} from "./types/database-sync-instance";
 import { DatabaseSyncOptions } from "./types/database-sync-options";
 import { SQLTagStoreInstance } from "./types/sql-tag-store-instance";
 import { SqliteAuthorizationActions } from "./types/sqlite-authorization-actions";
@@ -15,7 +18,10 @@ import { StatementSyncInstance } from "./types/statement-sync-instance";
 
 export type { AggregateOptions } from "./types/aggregate-options";
 export type { ChangesetApplyOptions } from "./types/changeset-apply-options";
-export type { DatabaseSyncInstance } from "./types/database-sync-instance";
+export type {
+  DatabaseSyncInstance,
+  DatabaseSyncLimits,
+} from "./types/database-sync-instance";
 export type { DatabaseSyncOptions } from "./types/database-sync-options";
 export type { PragmaOptions } from "./types/pragma-options";
 export type { SessionOptions } from "./types/session-options";
@@ -39,6 +45,7 @@ export {
   type EnhanceableDatabaseSync,
   type EnhancedDatabaseSync,
   type EnhancedMethods,
+  type EnhancedStatementMethods,
 } from "./enhance";
 
 // Use _dirname() helper that works in both CJS/ESM and Jest
@@ -203,6 +210,82 @@ DatabaseSync.prototype = _DatabaseSync.prototype;
   return new SQLTagStore(this, capacity);
 };
 
+// Limit name to SQLite limit ID mapping (matches upstream kLimitMapping order)
+const LIMIT_MAPPING: ReadonlyArray<{
+  name: keyof DatabaseSyncLimits;
+  id: number;
+}> = [
+  { name: "length", id: 0 },
+  { name: "sqlLength", id: 1 },
+  { name: "column", id: 2 },
+  { name: "exprDepth", id: 3 },
+  { name: "compoundSelect", id: 4 },
+  { name: "vdbeOp", id: 5 },
+  { name: "functionArg", id: 6 },
+  { name: "attach", id: 7 },
+  { name: "likePatternLength", id: 8 },
+  { name: "variableNumber", id: 9 },
+  { name: "triggerDepth", id: 10 },
+];
+
+const INT_MAX = 2147483647;
+
+// WeakMap to cache limits objects per database instance
+const limitsCache = new WeakMap<DatabaseSyncInstance, DatabaseSyncLimits>();
+
+function validateLimitValue(value: unknown): number {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new TypeError(
+      "Limit value must be a non-negative integer or Infinity.",
+    );
+  }
+  if (value === Infinity) {
+    return INT_MAX;
+  }
+  if (!Number.isFinite(value) || value !== Math.trunc(value)) {
+    throw new TypeError(
+      "Limit value must be a non-negative integer or Infinity.",
+    );
+  }
+  if (value < 0) {
+    throw new RangeError("Limit value must be non-negative.");
+  }
+  return value;
+}
+
+function createLimitsObject(db: DatabaseSyncInstance): DatabaseSyncLimits {
+  const obj = Object.create(null) as DatabaseSyncLimits;
+  for (const { name, id } of LIMIT_MAPPING) {
+    Object.defineProperty(obj, name, {
+      get() {
+        return db.getLimit(id);
+      },
+      set(value: unknown) {
+        const validated = validateLimitValue(value);
+        db.setLimit(id, validated);
+      },
+      enumerable: true,
+      configurable: false,
+    });
+  }
+  return obj;
+}
+
+if (!Object.getOwnPropertyDescriptor(DatabaseSync.prototype, "limits")) {
+  Object.defineProperty(DatabaseSync.prototype, "limits", {
+    get(this: DatabaseSyncInstance) {
+      let obj = limitsCache.get(this);
+      if (obj == null) {
+        obj = createLimitsObject(this);
+        limitsCache.set(this, obj);
+      }
+      return obj;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}
+
 // NOTE: .pragma() and .transaction() are NOT added to the prototype by default.
 // This keeps DatabaseSync 100% API-compatible with node:sqlite.
 // Users who want better-sqlite3-style methods should use enhance():