@sqb/sqlite 6.0.9 → 6.0.10

package/README.md

@@ -60,5 +60,5 @@ SQB is available under [MIT](LICENSE) license.
 [downloads-url]: https://npmjs.org/package/@sqb/sqlite
 [ci-test-image]: https://github.com/panates/sqb/actions/workflows/test.yml/badge.svg
 [ci-test-url]: https://github.com/panates/sqb/actions/workflows/test.yml
-[coveralls-image]: https://coveralls.io/repos/github/sqbjs/sqb/badge.svg?branch=master
+[coveralls-image]: https://coveralls.io/repos/github/panates/sqb/badge.svg?branch=dev
 [coveralls-url]: https://coveralls.io/github/sqbjs/sqb?branch=master

package/constants.d.ts

@@ -0,0 +1,3 @@
+/** This package's own version, kept in step with its `package.json` by `rman version`
+ *  (see `.rmanrc` `version.stamp`) - never edit it by hand. */
+export declare const version = "6.0.10";

package/constants.js

@@ -0,0 +1,3 @@
+/** This package's own version, kept in step with its `package.json` by `rman version`
+ *  (see `.rmanrc` `version.stamp`) - never edit it by hand. */
+export const version = '6.0.10';

package/drivers/bun-driver.d.ts

@@ -1,2 +1,3 @@
 import type { SqliteDriver } from './types.js';
+/** {@link SqliteDriver} backed by Bun's built-in `bun:sqlite` module. */
 export declare const bunDriver: SqliteDriver;

package/drivers/bun-driver.js

@@ -1,11 +1,13 @@
 // This module is only ever loaded via a dynamic import() from a Bun
 // runtime (see ./index.ts), so a static import of 'bun:sqlite' is safe.
 import { Database } from 'bun:sqlite';
+/** {@link NativeStatement} implementation wrapping `bun:sqlite`'s `Statement`. */
 class BunStatement {
     _stmt;
     constructor(_stmt) {
         this._stmt = _stmt;
     }
+    /** Runs the statement, normalizing the result to {@link NativeRunResult}'s shape. */
     run(params) {
         const r = params ? this._stmt.run(params) : this._stmt.run();
         return {
@@ -22,6 +24,7 @@ class BunStatement {
     iterate(params) {
         return params ? this._stmt.iterate(params) : this._stmt.iterate();
     }
+    /** Converts `bun:sqlite`'s column metadata into {@link NativeColumnInfo}. */
     columns() {
         const names = this._stmt.columnNames;
         let types = [];
@@ -38,6 +41,7 @@ class BunStatement {
         }));
     }
 }
+/** {@link NativeDatabase} implementation wrapping `bun:sqlite`'s `Database`. */
 class BunDatabase {
     _db;
     constructor(_db) {
@@ -56,6 +60,7 @@ class BunDatabase {
         this._db.close();
     }
 }
+/** {@link SqliteDriver} backed by Bun's built-in `bun:sqlite` module. */
 export const bunDriver = {
     open(filename) {
         return new BunDatabase(new Database(filename));

package/drivers/index.d.ts

@@ -1,2 +1,8 @@
 import type { NativeDatabase } from './types.js';
+/**
+ * Opens `filename` with the driver matching the current JS runtime -
+ * `bun:sqlite` under Bun, `node:sqlite` otherwise - dynamically importing
+ * only the matching driver module, so the other runtime's native module
+ * (unavailable outside its own runtime) is never loaded.
+ */
 export declare function openDatabase(filename: string): Promise<NativeDatabase>;

package/drivers/index.js

@@ -1,5 +1,12 @@
+/** Detects a Bun runtime by the presence of the global `Bun` object and its `version` string. */
 const isBun = typeof globalThis.Bun !== 'undefined' &&
     typeof globalThis.Bun.version === 'string';
+/**
+ * Opens `filename` with the driver matching the current JS runtime -
+ * `bun:sqlite` under Bun, `node:sqlite` otherwise - dynamically importing
+ * only the matching driver module, so the other runtime's native module
+ * (unavailable outside its own runtime) is never loaded.
+ */
 export async function openDatabase(filename) {
     if (isBun) {
         const { bunDriver } = await import('./bun-driver.js');

package/drivers/node-driver.d.ts

@@ -1,2 +1,3 @@
 import type { SqliteDriver } from './types.js';
+/** {@link SqliteDriver} backed by Node's built-in `node:sqlite` module. */
 export declare const nodeDriver: SqliteDriver;

package/drivers/node-driver.js

@@ -1,11 +1,13 @@
 // This module is only ever loaded via a dynamic import() from a Node.js
 // runtime (see ./index.ts), so a static import of 'node:sqlite' is safe.
 import { DatabaseSync, } from 'node:sqlite';
+/** {@link NativeStatement} implementation wrapping `node:sqlite`'s `StatementSync`. */
 class NodeStatement {
     _stmt;
     constructor(_stmt) {
         this._stmt = _stmt;
     }
+    /** Runs the statement, converting `node:sqlite`'s `bigint` result fields to plain `number`s (see {@link NativeRunResult}). */
     run(params) {
         const r = params ? this._stmt.run(params) : this._stmt.run();
         return {
@@ -22,6 +24,7 @@ class NodeStatement {
     iterate(params) {
         return (params ? this._stmt.iterate(params) : this._stmt.iterate());
     }
+    /** Converts `node:sqlite`'s column metadata into {@link NativeColumnInfo}. */
     columns() {
         return this._stmt.columns().map((c) => ({
             name: c.name,
@@ -29,6 +32,7 @@ class NodeStatement {
         }));
     }
 }
+/** {@link NativeDatabase} implementation wrapping `node:sqlite`'s `DatabaseSync`. */
 class NodeDatabase {
     _db;
     constructor(_db) {
@@ -47,6 +51,7 @@ class NodeDatabase {
         this._db.close();
     }
 }
+/** {@link SqliteDriver} backed by Node's built-in `node:sqlite` module. */
 export const nodeDriver = {
     open(filename) {
         return new NodeDatabase(new DatabaseSync(filename));

package/drivers/types.d.ts

@@ -1,11 +1,14 @@
+/** A single result column's name and (if declared in the schema) SQL type, as reported by a {@link NativeStatement}. */
 export interface NativeColumnInfo {
     name: string;
     declaredType: string | null;
 }
+/** Outcome of a data-modifying statement, normalized to plain `number`s across both `node:sqlite` (which returns `bigint`) and `bun:sqlite`. */
 export interface NativeRunResult {
     changes: number;
     lastInsertRowid: number;
 }
+/** Common surface a prepared statement must expose, implemented separately for `node:sqlite` (`./node-driver.ts`) and `bun:sqlite` (`./bun-driver.ts`) so {@link SqliteConnection} can stay driver-agnostic. */
 export interface NativeStatement {
     run(params?: Record<string, any>): NativeRunResult;
     get(params?: Record<string, any>): Record<string, any> | undefined;
@@ -17,12 +20,14 @@ export interface NativeStatement {
      */
     columns(): NativeColumnInfo[];
 }
+/** Common surface an open database connection must expose, implemented separately for `node:sqlite` (`./node-driver.ts`) and `bun:sqlite` (`./bun-driver.ts`). */
 export interface NativeDatabase {
     readonly inTransaction: boolean;
     exec(sql: string): void;
     prepare(sql: string): NativeStatement;
     close(): void;
 }
+/** Opens a {@link NativeDatabase} for a given runtime - see `./index.ts`, which picks `bunDriver` or `nodeDriver` based on which runtime is active. */
 export interface SqliteDriver {
     open(filename: string): NativeDatabase;
 }

package/index.d.ts

@@ -1,4 +1,15 @@
+/**
+ * @sqb/sqlite - `@sqb/connect` database driver for SQLite, backed by
+ * Node's built-in `node:sqlite` or, when running under Bun, `bun:sqlite`.
+ *
+ * Importing this package (even without using any of its exports) registers
+ * {@link SqliteAdapter} with `@sqb/connect`'s `AdapterRegistry` as a side
+ * effect (and, via `@sqb/sqlite-dialect`, `@sqb/builder`'s
+ * `SerializerRegistry`), making `new SqbClient({ dialect: 'sqlite', ...
+ * })` work.
+ */
 import '@sqb/sqlite-dialect';
+export * from './constants.js';
 export * from './sqlite-adapter.js';
 export * from './sqlite-connection.js';
 export * from './sqlite-cursor.js';

package/index.js

@@ -1,6 +1,17 @@
+/**
+ * @sqb/sqlite - `@sqb/connect` database driver for SQLite, backed by
+ * Node's built-in `node:sqlite` or, when running under Bun, `bun:sqlite`.
+ *
+ * Importing this package (even without using any of its exports) registers
+ * {@link SqliteAdapter} with `@sqb/connect`'s `AdapterRegistry` as a side
+ * effect (and, via `@sqb/sqlite-dialect`, `@sqb/builder`'s
+ * `SerializerRegistry`), making `new SqbClient({ dialect: 'sqlite', ...
+ * })` work.
+ */
 import '@sqb/sqlite-dialect';
 import { AdapterRegistry } from '@sqb/connect';
 import { SqliteAdapter } from './sqlite-adapter.js';
+export * from './constants.js';
 export * from './sqlite-adapter.js';
 export * from './sqlite-connection.js';
 export * from './sqlite-cursor.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sqb/sqlite",
   "description": "SQB adapter for Node.js and Bun's native SQLite drivers",
-  "version": "6.0.9",
+  "version": "6.0.10",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "homepage": "https://www.sqbjs.org",
@@ -9,9 +9,9 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@sqb/builder": "^6.0.9",
-    "@sqb/connect": "^6.0.9",
-    "@sqb/sqlite-dialect": "^6.0.9"
+    "@sqb/builder": "^6.0.10",
+    "@sqb/connect": "^6.0.10",
+    "@sqb/sqlite-dialect": "^6.0.10"
   },
   "type": "module",
   "module": "./index.js",
@@ -28,7 +28,9 @@
   },
   "contributors": [
     "Eray Hanoglu <e.hanoglu@panates.com>",
-    "Ilker Gurelli <i.gurelli@panates.com>"
+    "Ilker Gurelli <i.gurelli@panates.com>",
+    "Onur Tokel <o.tokel@panates.com>",
+    "Bircan Yuruk <b.yuruk@panates.com>"
   ],
   "repository": {
     "type": "git",
@@ -50,4 +52,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/sqlite-adapter.d.ts

@@ -1,9 +1,29 @@
 import '@sqb/sqlite-dialect';
 import type { Adapter, ClientConfiguration } from '@sqb/connect';
+/**
+ * `@sqb/connect` {@link Adapter} for SQLite, wrapping either Node's
+ * built-in `node:sqlite` or, when running under Bun, `bun:sqlite` (see
+ * `./drivers/index.ts`). Registered automatically as a side effect of
+ * importing this package - see `index.ts`.
+ */
 export declare class SqliteAdapter implements Adapter {
     driver: string;
     dialect: string;
     features: Adapter.Features;
+    /**
+     * Opens (or reuses, via {@link dbCache}) the native SQLite database at
+     * `config.database` - a `:memory:`/`:memory:name` in-memory database, or
+     * a file path resolved relative to the current working directory.
+     *
+     * @throws {Error} if `config.database` isn't given
+     */
     connect(config: ClientConfiguration): Promise<Adapter.Connection>;
 }
+/**
+ * Closes and evicts an in-memory database from {@link dbCache} by name
+ * (defaulting to the unnamed `:memory:` database). In-memory databases are
+ * never closed automatically by a connection's `close()` (unlike file
+ * databases, which are refcounted), so this is the only way to release one
+ * once no longer needed - primarily useful for test teardown.
+ */
 export declare function closeMemoryDatabase(name?: string): Promise<void>;

package/sqlite-adapter.js

@@ -2,13 +2,38 @@ import '@sqb/sqlite-dialect';
 import path from 'path';
 import { openDatabase } from './drivers/index.js';
 import { SqliteConnection } from './sqlite-connection.js';
+/**
+ * Open native databases keyed by resolved file path, shared across
+ * concurrent SQB connections opened against the same file - SQLite has no
+ * connection pooling of its own, so a second `connect()` call for a file
+ * already open reuses the same native handle (refcounted) rather than
+ * opening it twice. An in-memory database (`:memory:` or `:memory:name`)
+ * is cached too (so multiple connections can see the same in-memory data)
+ * but is never refcount-closed by {@link SqliteAdapter.connect}'s closer -
+ * only {@link closeMemoryDatabase} closes one, since closing it on the
+ * last connection's `close()` would silently discard that in-memory data
+ * for any code still expecting to reopen it by name.
+ */
 const dbCache = new Map();
+/**
+ * `@sqb/connect` {@link Adapter} for SQLite, wrapping either Node's
+ * built-in `node:sqlite` or, when running under Bun, `bun:sqlite` (see
+ * `./drivers/index.ts`). Registered automatically as a side effect of
+ * importing this package - see `index.ts`.
+ */
 export class SqliteAdapter {
     driver = 'sqlite';
     dialect = 'sqlite';
     features = {
         cursor: true,
     };
+    /**
+     * Opens (or reuses, via {@link dbCache}) the native SQLite database at
+     * `config.database` - a `:memory:`/`:memory:name` in-memory database, or
+     * a file path resolved relative to the current working directory.
+     *
+     * @throws {Error} if `config.database` isn't given
+     */
     async connect(config) {
         if (!config.database)
             throw new Error('You must provide a sqlite database file');
@@ -35,6 +60,13 @@ export class SqliteAdapter {
         });
     }
 }
+/**
+ * Closes and evicts an in-memory database from {@link dbCache} by name
+ * (defaulting to the unnamed `:memory:` database). In-memory databases are
+ * never closed automatically by a connection's `close()` (unlike file
+ * databases, which are refcounted), so this is the only way to release one
+ * once no longer needed - primarily useful for test teardown.
+ */
 export async function closeMemoryDatabase(name) {
     const memoryDbName = name || ':memory:';
     const memDb = dbCache.get(memoryDbName);

package/sqlite-connection.d.ts

@@ -1,18 +1,46 @@
 import type { Adapter, QueryRequest } from '@sqb/connect';
 import type { NativeDatabase } from './drivers/types.js';
+/**
+ * `@sqb/connect` {@link Adapter.Connection} wrapping a {@link
+ * NativeDatabase} (Node's `node:sqlite` or Bun's `bun:sqlite`, behind a
+ * common driver interface - see `./drivers/types.ts`): translates
+ * `QueryRequest`s into driver calls (including cursor-mode iteration and
+ * `RETURNING`-on-`INSERT`/`UPDATE` emulation, since this layer's SQL
+ * generation doesn't rely on SQLite's own `RETURNING` support) and
+ * normalizes results/column metadata back into SQB's portable shape.
+ */
 export declare class SqliteConnection implements Adapter.Connection {
     private _onClose;
     private intlcon?;
     constructor(db: NativeDatabase, _onClose: () => void | Promise<void>);
+    /** SQLite has no server-side session concept - always `0`. */
     get sessionId(): any;
+    /** Releases this connection's reference to the underlying native database via the closer passed to the constructor (see {@link SqliteAdapter.connect}), closing the file once no connection references it. */
     close(): Promise<void>;
+    /** Rolls back any open transaction, readying the connection to be pooled/reused. */
     reset(): Promise<void>;
+    /** Begins a transaction (`BEGIN`), swallowing the driver's error for a transaction already being open rather than throwing. */
     startTransaction(): Promise<void>;
+    /** Commits the current transaction, swallowing the driver's error for no transaction being open rather than throwing. */
     commit(): Promise<void>;
+    /** Rolls back the current transaction, swallowing the driver's error for no transaction being open rather than throwing. */
     rollback(): Promise<void>;
     getInTransaction(): boolean;
+    /** Validates the connection with a trivial `SELECT 1`. */
     test(): Promise<void>;
+    /**
+     * Executes one query. For an `INSERT`/`UPDATE` with `returningFields`,
+     * runs the statement then a synthesized follow-up `SELECT` to emulate
+     * `RETURNING` (an `INSERT` is matched back by `ROWID`, an `UPDATE` by
+     * reusing the original `WHERE` clause) - `DELETE` isn't emulated here
+     * since there's nothing left to re-select afterward. Otherwise prepares
+     * and iterates the statement, wrapping it in a {@link SqliteCursor}
+     * (returned directly in cursor mode, or eagerly drained up to
+     * `fetchRows` rows otherwise).
+     */
     execute(query: QueryRequest): Promise<Adapter.Response>;
+    /** Copies a synthesized `SELECT` statement's rows/fields onto `out` - used to emulate `RETURNING` on `INSERT`/`UPDATE`. */
     private _fillSelectResult;
+    /** Converts the driver's column metadata into SQB's portable {@link Adapter.Field} shape via {@link mapDeclaredType}. */
     private _convertFields;
 }

package/sqlite-connection.js

@@ -1,4 +1,13 @@
 import { SqliteCursor } from './sqlite-cursor.js';
+/**
+ * `@sqb/connect` {@link Adapter.Connection} wrapping a {@link
+ * NativeDatabase} (Node's `node:sqlite` or Bun's `bun:sqlite`, behind a
+ * common driver interface - see `./drivers/types.ts`): translates
+ * `QueryRequest`s into driver calls (including cursor-mode iteration and
+ * `RETURNING`-on-`INSERT`/`UPDATE` emulation, since this layer's SQL
+ * generation doesn't rely on SQLite's own `RETURNING` support) and
+ * normalizes results/column metadata back into SQB's portable shape.
+ */
 export class SqliteConnection {
     _onClose;
     intlcon;
@@ -6,18 +15,22 @@ export class SqliteConnection {
         this._onClose = _onClose;
         this.intlcon = db;
     }
+    /** SQLite has no server-side session concept - always `0`. */
     get sessionId() {
         return 0;
     }
+    /** Releases this connection's reference to the underlying native database via the closer passed to the constructor (see {@link SqliteAdapter.connect}), closing the file once no connection references it. */
     async close() {
         if (this.intlcon) {
             this.intlcon = undefined;
             await this._onClose();
         }
     }
+    /** Rolls back any open transaction, readying the connection to be pooled/reused. */
     async reset() {
         return this.rollback();
     }
+    /** Begins a transaction (`BEGIN`), swallowing the driver's error for a transaction already being open rather than throwing. */
     async startTransaction() {
         assertDefined(this.intlcon);
         try {
@@ -29,6 +42,7 @@ export class SqliteConnection {
             throw e;
         }
     }
+    /** Commits the current transaction, swallowing the driver's error for no transaction being open rather than throwing. */
     async commit() {
         assertDefined(this.intlcon);
         try {
@@ -40,6 +54,7 @@ export class SqliteConnection {
             throw e;
         }
     }
+    /** Rolls back the current transaction, swallowing the driver's error for no transaction being open rather than throwing. */
     async rollback() {
         assertDefined(this.intlcon);
         try {
@@ -54,10 +69,21 @@ export class SqliteConnection {
     getInTransaction() {
         return !!this.intlcon?.inTransaction;
     }
+    /** Validates the connection with a trivial `SELECT 1`. */
     async test() {
         assertDefined(this.intlcon);
         this.intlcon.exec('select 1');
     }
+    /**
+     * Executes one query. For an `INSERT`/`UPDATE` with `returningFields`,
+     * runs the statement then a synthesized follow-up `SELECT` to emulate
+     * `RETURNING` (an `INSERT` is matched back by `ROWID`, an `UPDATE` by
+     * reusing the original `WHERE` clause) - `DELETE` isn't emulated here
+     * since there's nothing left to re-select afterward. Otherwise prepares
+     * and iterates the statement, wrapping it in a {@link SqliteCursor}
+     * (returned directly in cursor mode, or eagerly drained up to
+     * `fetchRows` rows otherwise).
+     */
     async execute(query) {
         assertDefined(this.intlcon);
         const intlcon = this.intlcon;
@@ -109,6 +135,7 @@ export class SqliteConnection {
         }
         return out;
     }
+    /** Copies a synthesized `SELECT` statement's rows/fields onto `out` - used to emulate `RETURNING` on `INSERT`/`UPDATE`. */
     _fillSelectResult(out, stmt, rows, query) {
         const columns = stmt.columns();
         out.fields = this._convertFields(columns);
@@ -118,6 +145,7 @@ export class SqliteConnection {
                 ? rows.map(r => columns.map(c => r[c.name]))
                 : rows;
     }
+    /** Converts the driver's column metadata into SQB's portable {@link Adapter.Field} shape via {@link mapDeclaredType}. */
     _convertFields(columns) {
         const result = [];
         for (const c of columns) {
@@ -132,10 +160,12 @@ export class SqliteConnection {
         return result;
     }
 }
+/** Throws if the connection has already been closed. */
 function assertDefined(d) {
     if (d == null)
         throw new Error('DB session is closed');
 }
+/** Rewrites SQB's plain-named params (`{ name: value }`) into the `:name`-prefixed keys both `node:sqlite` and `bun:sqlite` require for named binding. */
 function mapParams(params) {
     const out = {};
     for (const k of Object.keys(params))

package/sqlite-cursor.d.ts

@@ -1,5 +1,11 @@
 import type { Adapter, RowType } from '@sqb/connect';
 import type { NativeColumnInfo } from './drivers/types.js';
+/**
+ * `@sqb/connect` {@link Adapter.Cursor} wrapping a `NativeStatement`'s
+ * synchronous `iterate()` result: `fetch(n)` pulls up to `n` rows at a
+ * time, converting each row to an array (column-ordered via the
+ * statement's column metadata) when `rowType` is `'array'`.
+ */
 export declare class SqliteCursor implements Adapter.Cursor {
     private _iterator?;
     private readonly _rowType;
@@ -10,6 +16,8 @@ export declare class SqliteCursor implements Adapter.Cursor {
     });
     get isClosed(): boolean;
     get rowType(): RowType;
+    /** Stops consuming the iterator by dropping it - SQLite's synchronous iterator has no `close()`/`return()` of its own that needs calling. */
     close(): Promise<void>;
+    /** Pulls up to `nRows` more rows from the iterator, or `undefined` once it's exhausted. */
     fetch(nRows: number): Promise<any[] | undefined>;
 }

package/sqlite-cursor.js

@@ -1,3 +1,9 @@
+/**
+ * `@sqb/connect` {@link Adapter.Cursor} wrapping a `NativeStatement`'s
+ * synchronous `iterate()` result: `fetch(n)` pulls up to `n` rows at a
+ * time, converting each row to an array (column-ordered via the
+ * statement's column metadata) when `rowType` is `'array'`.
+ */
 export class SqliteCursor {
     _iterator;
     _rowType;
@@ -13,9 +19,11 @@ export class SqliteCursor {
     get rowType() {
         return this._rowType;
     }
+    /** Stops consuming the iterator by dropping it - SQLite's synchronous iterator has no `close()`/`return()` of its own that needs calling. */
     async close() {
         this._iterator = undefined;
     }
+    /** Pulls up to `nRows` more rows from the iterator, or `undefined` once it's exhausted. */
     async fetch(nRows) {
         if (!this._iterator)
             return undefined;