[ODIN-436] iterator/iterable (#60)

anothersmith · Dec 15, 2020 · ca93503 · ca93503
1 parent a510bdf
commit ca93503
Show file tree

Hide file tree

Showing 20 changed files with 371 additions and 352 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -1,10 +1,10 @@
-coverage/
-dist
-node_modules/
-.eslintrc.js
-jest.config.js
-tsconfig.json
-duckdb
-addon
-nodemon.json
-examples
+/coverage/
+/dist
+/node_modules/
+/.eslintrc.js
+/jest.config.js
+/tsconfig.json
+/duckdb
+/addon
+/nodemon.json
+/examples
diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,10 @@
-node_modules
-build
-dist
-coverage
-duckdb
-duckdb.tar.gz
-prebuilds
-temp
-etc
-yarn-error.log
+/node_modules
+/build
+/dist
+/coverage
+/duckdb
+/duckdb.tar.gz
+/prebuilds
+/temp
+/etc
+/yarn-error.log
diff --git a/.npmignore b/.npmignore
@@ -1,6 +1,6 @@
-node_modules
-coverage
-build
-duckdb
-prebuilds
-examples
+/node_modules
+/coverage
+/build
+/duckdb
+/prebuilds
+/examples
diff --git a/.prettierignore b/.prettierignore
@@ -1,7 +1,7 @@
-coverage/
-node_modules/
-duckdb
-addon
-dist
-tsconfig.json
-examples
+/coverage/
+/node_modules/
+/duckdb
+/addon
+/dist
+/tsconfig.json
+/examples
diff --git a/docs/api/node-duckdb.connection.close.md b/docs/api/node-duckdb.connection.close.md
@@ -4,7 +4,7 @@
 
 ## Connection.close() method
 
-Close the connection (also closes all [ResultStream](./node-duckdb.resultstream.md) or [ResultIterator](./node-duckdb.resultiterator.md) objects associated with this connection).
+Close the connection (also closes all [Readable](https://nodejs.org/api/stream.html#stream_class_stream_readable) or [ResultIterator](./node-duckdb.resultiterator.md) objects associated with this connection).
 
 <b>Signature:</b>
 

diff --git a/docs/api/node-duckdb.connection.execute.md b/docs/api/node-duckdb.connection.execute.md
@@ -4,12 +4,12 @@
 
 ## Connection.execute() method
 
-Asynchronously executes the query and returns a node.js stream that wraps the result set.
+Asynchronously executes the query and returns a [Readable stream](https://nodejs.org/api/stream.html#stream_class_stream_readable) that wraps the result set.
 
 <b>Signature:</b>
 
 ```typescript
-execute<T>(command: string, options?: IExecuteOptions): Promise<ResultStream<T>>;
+execute<T>(command: string, options?: IExecuteOptions): Promise<Readable>;
 ```
 
 ## Parameters
@@ -21,7 +21,7 @@ execute<T>(command: string, options?: IExecuteOptions): Promise<ResultStream<T>>
 
 <b>Returns:</b>
 
-Promise&lt;[ResultStream](./node-duckdb.resultstream.md)<!-- -->&lt;T&gt;&gt;
+Promise&lt;Readable&gt;
 
 ## Example
 

diff --git a/docs/api/node-duckdb.connection.md b/docs/api/node-duckdb.connection.md
@@ -30,8 +30,8 @@ A single db instance can have multiple connections. Having more than one connect
 
 ## Methods
 
-| Method                                                                           | Modifiers | Description                                                                                                                                                                        |
-| -------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [close()](./node-duckdb.connection.close.md)                                     |           | Close the connection (also closes all [ResultStream](./node-duckdb.resultstream.md) or [ResultIterator](./node-duckdb.resultiterator.md) objects associated with this connection). |
-| [execute(command, options)](./node-duckdb.connection.execute.md)                 |           | Asynchronously executes the query and returns a node.js stream that wraps the result set.                                                                                          |
-| [executeIterator(command, options)](./node-duckdb.connection.executeiterator.md) |           | Asynchronously executes the query and returns an iterator that points to the first result in the result set.                                                                       |
+| Method                                                                           | Modifiers | Description                                                                                                                                                                                                      |
+| -------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [close()](./node-duckdb.connection.close.md)                                     |           | Close the connection (also closes all [Readable](https://nodejs.org/api/stream.html#stream_class_stream_readable) or [ResultIterator](./node-duckdb.resultiterator.md) objects associated with this connection). |
+| [execute(command, options)](./node-duckdb.connection.execute.md)                 |           | Asynchronously executes the query and returns a [Readable stream](https://nodejs.org/api/stream.html#stream_class_stream_readable) that wraps the result set.                                                    |
+| [executeIterator(command, options)](./node-duckdb.connection.executeiterator.md) |           | Asynchronously executes the query and returns an iterator that points to the first result in the result set.                                                                                                     |
diff --git a/docs/api/node-duckdb.md b/docs/api/node-duckdb.md
@@ -52,7 +52,6 @@ For more examples see [here](https://github.com/deepcrawl/node-duckdb/tree/featu
 | [Connection](./node-duckdb.connection.md)         | Represents a DuckDB connection.                                                                                                                                                            |
 | [DuckDB](./node-duckdb.duckdb.md)                 | The DuckDB class represents a DuckDB database instance.                                                                                                                                    |
 | [ResultIterator](./node-duckdb.resultiterator.md) | ResultIterator represents the result set of a DuckDB query. Instances of this class are returned by the [Connection.executeIterator](./node-duckdb.connection.executeiterator.md)<!-- -->. |
-| [ResultStream](./node-duckdb.resultstream.md)     | This is a Readable stream that wrapps the ResultIterator. Instances of this class are returned by [Connection.execute](./node-duckdb.connection.execute.md)<!-- -->.                       |
 
 ## Enumerations
 

diff --git a/docs/api/node-duckdb.resultiterator._symbol.iterator_.md b/docs/api/node-duckdb.resultiterator._symbol.iterator_.md
@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Node-DuckDB API](./node-duckdb.md) &gt; [ResultIterator](./node-duckdb.resultiterator.md) &gt; [\[Symbol.iterator\]](./node-duckdb.resultiterator._symbol.iterator_.md)
+
+## ResultIterator.\[Symbol.iterator\]() method
+
+<b>Signature:</b>
+
+```typescript
+[Symbol.iterator](): this;
+```
+
+<b>Returns:</b>
+
+this
diff --git a/docs/api/node-duckdb.resultiterator.md b/docs/api/node-duckdb.resultiterator.md
@@ -9,9 +9,11 @@ ResultIterator represents the result set of a DuckDB query. Instances of this cl
 <b>Signature:</b>
 
 ```typescript
-export declare class ResultIterator<T>
+export declare class ResultIterator<T> implements IterableIterator<T>
 ```
 
+<b>Implements:</b> IterableIterator&lt;T&gt;
+
 ## Remarks
 
 The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ResultIterator` class.
@@ -25,9 +27,11 @@ The constructor for this class is marked as internal. Third-party code should no
 
 ## Methods
 
-| Method                                                         | Modifiers | Description                     |
-| -------------------------------------------------------------- | --------- | ------------------------------- |
-| [close()](./node-duckdb.resultiterator.close.md)               |           | Close the ResultIterator        |
-| [describe()](./node-duckdb.resultiterator.describe.md)         |           | Describe the result set schema. |
-| [fetchAllRows()](./node-duckdb.resultiterator.fetchallrows.md) |           | Fetch all rows                  |
-| [fetchRow()](./node-duckdb.resultiterator.fetchrow.md)         |           | Fetch the next row              |
+| Method                                                                     | Modifiers | Description                     |
+| -------------------------------------------------------------------------- | --------- | ------------------------------- |
+| [\[Symbol.iterator\]()](./node-duckdb.resultiterator._symbol.iterator_.md) |           |                                 |
+| [close()](./node-duckdb.resultiterator.close.md)                           |           | Close the ResultIterator        |
+| [describe()](./node-duckdb.resultiterator.describe.md)                     |           | Describe the result set schema. |
+| [fetchAllRows()](./node-duckdb.resultiterator.fetchallrows.md)             |           | Fetch all rows                  |
+| [fetchRow()](./node-duckdb.resultiterator.fetchrow.md)                     |           | Fetch the next row              |
+| [next()](./node-duckdb.resultiterator.next.md)                             |           |                                 |
diff --git a/docs/api/node-duckdb.resultiterator.next.md b/docs/api/node-duckdb.resultiterator.next.md
@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Node-DuckDB API](./node-duckdb.md) &gt; [ResultIterator](./node-duckdb.resultiterator.md) &gt; [next](./node-duckdb.resultiterator.next.md)
+
+## ResultIterator.next() method
+
+<b>Signature:</b>
+
+```typescript
+next(): IteratorResult<T>;
+```
+
+<b>Returns:</b>
+
+IteratorResult&lt;T&gt;
diff --git a/docs/api/node-duckdb.resultstream.md b/docs/api/node-duckdb.resultstream.md
diff --git a/src/addon/connection.ts b/src/addon/connection.ts
@@ -1,40 +1,43 @@
-import { ConnectionBinding } from "../addon-bindings";
-import { ResultStream } from "./result-stream";
-import {DuckDB} from "./duckdb";
-import { ResultIterator } from "./result-iterator";
+import { Readable } from "stream";
+
+import { ConnectionBinding } from "@addon-bindings";
 import { IExecuteOptions } from "@addon-types";
 
+import { DuckDB } from "./duckdb";
+import { ResultIterator } from "./result-iterator";
+import { getResultStream } from "./result-stream";
+
 /**
  * Represents a DuckDB connection.
- * 
+ *
  * @remarks
  * A single db instance can have multiple connections. Having more than one connection instance is required when executing concurrent queries.
- * 
+ *
  * @public
  */
 export class Connection {
   /**
-     * Connection constructor.
-     * @param duckdb - {@link DuckDB | DuckDB} instance to connect to.
-     * 
-     * 
-     * @example
-     * Initializing a connection:
-     * ```ts
-     * import { DuckDB } from "node-duckdb";
-     * const db = new DuckDB();
-     * const connection = new Connection(db);
-     * ```
-     * 
-     * @public
-     */
+   * Connection constructor.
+   * @param duckdb - {@link DuckDB | DuckDB} instance to connect to.
+   *
+   *
+   * @example
+   * Initializing a connection:
+   * ```ts
+   * import { DuckDB } from "node-duckdb";
+   * const db = new DuckDB();
+   * const connection = new Connection(db);
+   * ```
+   *
+   * @public
+   */
   constructor(private duckdb: DuckDB) {}
   private connectionBinding = new ConnectionBinding(this.duckdb.db);
   /**
-   * Asynchronously executes the query and returns a node.js stream that wraps the result set.
+   * Asynchronously executes the query and returns a {@link https://nodejs.org/api/stream.html#stream_class_stream_readable | Readable stream} that wraps the result set.
    * @param command - SQL command to execute
    * @param options - optional options object of type {@link IExecuteOptions | IExecuteOptions}
-   * 
+   *
    * @example
    * Streaming results of a DuckDB query into a CSV file:
    * ```ts
@@ -64,15 +67,15 @@ export class Connection {
    * outputToFileAsCsv();
    * ```
    */
-  public async execute<T>(command: string, options?: IExecuteOptions): Promise<ResultStream<T>> {
+  public async execute<T>(command: string, options?: IExecuteOptions): Promise<Readable> {
     const resultIteratorBinding = await this.connectionBinding.execute<T>(command, options);
-    return new ResultStream(new ResultIterator(resultIteratorBinding));
+    return getResultStream(new ResultIterator(resultIteratorBinding));
   }
   /**
    * Asynchronously executes the query and returns an iterator that points to the first result in the result set.
    * @param command - SQL command to execute
    * @param options - optional options object of type {@link IExecuteOptions | IExecuteOptions}
-   * 
+   *
    * @example
    * Printing rows:
    * ```ts
@@ -83,7 +86,7 @@ export class Connection {
    *   await connection.executeIterator("CREATE TABLE people(id INTEGER, name VARCHAR);");
    *   await connection.executeIterator("INSERT INTO people VALUES (1, 'Mark'), (2, 'Hannes'), (3, 'Bob');");
    *   const result = await connection.executeIterator("SELECT * FROM people;");
-   *   // print the first row    
+   *   // print the first row
    *   console.log(result.fetchRow());
    *   // print the rest of the rows
    *   console.log(result.fetchAllRows());
@@ -94,7 +97,7 @@ export class Connection {
    * }
    * queryDatabaseWithIterator();
    * ```
-   * 
+   *
    * @example
    * Providing generics type:
    * ```ts
@@ -108,7 +111,7 @@ export class Connection {
     return new ResultIterator(await this.connectionBinding.execute<T>(command, options));
   }
   /**
-   * Close the connection (also closes all {@link ResultStream | ResultStream} or {@link ResultIterator | ResultIterator} objects associated with this connection).
+   * Close the connection (also closes all {@link https://nodejs.org/api/stream.html#stream_class_stream_readable | Readable} or {@link ResultIterator | ResultIterator} objects associated with this connection).
    * @remarks
    * Even though GC will automatically destroy the Connection object at some point, DuckDB data is stored in the native address space, not the V8 heap, meaning you can easily have a Node.js process taking gigabytes of memory (more than the default heap size for Node.js) with V8 not triggering GC. So, definitely think about manually calling `close()`.
    */