@sqb/sqlite 6.0.7 → 6.0.10

package/LICENSE

@@ -1,191 +1,30 @@
-
-                                 Apache License
-                           Version 2.0, January 2004
-                        https://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   Copyright 2013-2018 Docker, Inc.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       https://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+BSD 3-Clause License
+
+Copyright (c) 2020 Panates
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,5 +1,6 @@
-<p style="text-align:center">
-  <img src="https://user-images.githubusercontent.com/3836517/32965280-1a2b63ce-cbe7-11e7-8ee1-ba47313503c5.png" width="500px" alt="SQB Logo"/>
+
+<p style="text-align: center;">
+  <img src="https://sqb.panates.com/img/github-hero.webp" width="1280" alt="SQB" />
 </p>
 
 <br>
@@ -59,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,16 +1,17 @@
 {
   "name": "@sqb/sqlite",
   "description": "SQB adapter for Node.js and Bun's native SQLite drivers",
-  "version": "6.0.7",
+  "version": "6.0.10",
   "author": "Panates",
-  "license": "Apache-2.0",
+  "license": "BSD-3-Clause",
+  "homepage": "https://www.sqbjs.org",
   "dependencies": {
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@sqb/builder": "^6.0.7",
-    "@sqb/connect": "^6.0.7",
-    "@sqb/sqlite-dialect": "^6.0.7"
+    "@sqb/builder": "^6.0.10",
+    "@sqb/connect": "^6.0.10",
+    "@sqb/sqlite-dialect": "^6.0.10"
   },
   "type": "module",
   "module": "./index.js",
@@ -27,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",
@@ -49,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;