Document APIs.

Author: rkistner

DRIVER-API.md

@@ -110,10 +110,6 @@ Returning an array of cells for each row, along with a separate "columns" array,
 
 However, many current SQLite bindings do not expose the raw array calls. Even if they do, this path may be slower than using objects from the start. Since using the results as an array is quite rare in practice, this is left as an optional configuration, rather than a requirement for the all queries.
 
-### Separate bind/step/reset
-
-This allows a lot of flexibility, for example partial rebinding of parameters instead of specifying all parameters each time a prepared statement is used. However, those type of use cases are rare, and this is not important in the overall architecture. These could all be combined into a single "query with parameters" call, but would need to take into account optional streaming of results.
-
 ### bigint
 
 SQLite supports up to 8-byte signed integers (up to 2^64-1), while JavaScript's number is limited to 2^53-1. General approaches include:

packages/driver/src/driver-api.ts

@@ -12,10 +12,6 @@ export interface PrepareOptions {
   autoFinalize?: boolean;
 }
 
-export interface ResetOptions {
-  clearBindings?: boolean;
-}
-
 export interface SqliteDriverConnection {
   /**
    * Prepare a statement.
@@ -49,19 +45,43 @@ export interface StreamQueryOptions extends QueryOptions {
 }
 
 export interface SqliteDriverStatement {
+  /**
+   * Run a query, and return results as an array of row objects.
+   *
+   * If the query does not return results, an empty array is returned.
+   */
   all(
     parameters?: SqliteParameterBinding,
     options?: QueryOptions
   ): Promise<SqliteObjectRow[]>;
+
+  /**
+   * Run a query, and return results as an array of row arrays.
+   *
+   * If the query does not return results, an empty array is returned.
+   */
   allArray(
     parameters?: SqliteParameterBinding,
     options?: QueryOptions
   ): Promise<SqliteArrayRow[]>;
 
+  /**
+   * Run a query, and return as an iterator of array of row object chunks.
+   *
+   * It is an error to call any other query methods on the same statement
+   * before the iterator has returned.
+   */
   stream(
     parameters?: SqliteParameterBinding,
     options?: StreamQueryOptions
   ): AsyncIterableIterator<SqliteObjectRow[]>;
+
+  /**
+   * Run a query, and return as an iterator of array of row array chunks.
+   *
+   * It is an error to call any other query methods on the same statement
+   * before the iterator has returned.
+   */
   streamArray(
     parameters?: SqliteParameterBinding,
     options?: StreamQueryOptions
@@ -75,6 +95,9 @@ export interface SqliteDriverStatement {
     options?: QueryOptions
   ): Promise<SqliteChanges>;
 
+  /**
+   * Get the column names of the data returned by the query.
+   */
   getColumns(): Promise<string[]>;
 
   finalize(): void;
@@ -86,7 +109,6 @@ export interface SqliteDriverConnectionPool {
    * Reserve a connection for exclusive use.
    *
    * If there is no available connection, this will wait until one is available.
-   * @param options
    */
   reserveConnection(
     options?: ReserveConnectionOptions

packages/driver/src/worker_threads/worker-driver.ts

@@ -1,16 +1,15 @@
 import * as worker_threads from 'worker_threads';
 import {
   PrepareOptions,
-  ResetOptions,
-  SqliteDriverConnection,
-  SqliteDriverStatement,
-  SqliteParameterBinding,
-  SqliteChanges,
-  UpdateListener,
   QueryOptions,
   SqliteArrayRow,
+  SqliteChanges,
+  SqliteDriverConnection,
+  SqliteDriverStatement,
   SqliteObjectRow,
-  StreamQueryOptions
+  SqliteParameterBinding,
+  StreamQueryOptions,
+  UpdateListener
 } from '../driver-api.js';
 
 import { Deferred } from '../deferred.js';