From 1cbc5a8f839a8a7ce9f43442f470ea81a6fd40b9 Mon Sep 17 00:00:00 2001 From: Rostislav Provodenko <60982217+rostislavdeepcrawl@users.noreply.github.com> Date: Thu, 10 Dec 2020 16:06:22 +0300 Subject: [PATCH] [ODIN-423] homepage (#38) * package.json * wip * wip * wip * wip * wip * fix * wip * wip * fix * wip * wip * wip * done * build * fixes * emails --- .gitignore | 2 + README.md | 100 +++++++-- api-extractor.json | 33 +++ CODE_OF_CONDUCT.md => docs/CODE_OF_CONDUCT.md | 0 CONTRIBUTING.md => docs/CONTRIBUTING.md | 0 docs/DEVELOPING.md | 22 ++ docs/api/index.md | 11 + docs/api/node-duckdb.accessmode.md | 22 ++ .../node-duckdb.connection._constructor_.md | 30 +++ docs/api/node-duckdb.connection.close.md | 21 ++ docs/api/node-duckdb.connection.execute.md | 56 ++++++ .../node-duckdb.connection.executeiterator.md | 61 ++++++ docs/api/node-duckdb.connection.isclosed.md | 13 ++ docs/api/node-duckdb.connection.md | 37 ++++ docs/api/node-duckdb.duckdb._constructor_.md | 49 +++++ docs/api/node-duckdb.duckdb.accessmode.md | 13 ++ .../node-duckdb.duckdb.checkpointwalsize.md | 13 ++ docs/api/node-duckdb.duckdb.close.md | 21 ++ docs/api/node-duckdb.duckdb.collation.md | 13 ++ .../node-duckdb.duckdb.defaultnullorder.md | 13 ++ .../node-duckdb.duckdb.defaultordertype.md | 13 ++ docs/api/node-duckdb.duckdb.enablecopy.md | 13 ++ docs/api/node-duckdb.duckdb.isclosed.md | 13 ++ docs/api/node-duckdb.duckdb.maximummemory.md | 13 ++ docs/api/node-duckdb.duckdb.md | 40 ++++ .../node-duckdb.duckdb.temporarydirectory.md | 13 ++ ...ode-duckdb.duckdb.usetemporarydirectory.md | 13 ++ docs/api/node-duckdb.iduckdbconfig.md | 20 ++ docs/api/node-duckdb.iduckdbconfig.options.md | 11 + docs/api/node-duckdb.iduckdbconfig.path.md | 13 ++ ...-duckdb.iduckdboptionsconfig.accessmode.md | 13 ++ ....iduckdboptionsconfig.checkpointwalsize.md | 13 ++ ...e-duckdb.iduckdboptionsconfig.collation.md | 13 ++ ...b.iduckdboptionsconfig.defaultnullorder.md | 13 ++ ...b.iduckdboptionsconfig.defaultordertype.md | 13 ++ ...-duckdb.iduckdboptionsconfig.enablecopy.md | 13 ++ ...ckdb.iduckdboptionsconfig.maximummemory.md | 13 ++ docs/api/node-duckdb.iduckdboptionsconfig.md | 28 +++ ...iduckdboptionsconfig.temporarydirectory.md | 13 ++ ...duckdb.iduckdboptionsconfig.usedirectio.md | 13 ++ ...ckdboptionsconfig.usetemporarydirectory.md | 13 ++ ...uckdb.iexecuteoptions.forcematerialized.md | 13 ++ docs/api/node-duckdb.iexecuteoptions.md | 20 ++ ...-duckdb.iexecuteoptions.rowresultformat.md | 13 ++ docs/api/node-duckdb.md | 74 +++++++ docs/api/node-duckdb.orderbynulltype.md | 22 ++ docs/api/node-duckdb.ordertype.md | 22 ++ docs/api/node-duckdb.resultiterator.close.md | 21 ++ .../node-duckdb.resultiterator.describe.md | 17 ++ ...node-duckdb.resultiterator.fetchallrows.md | 21 ++ .../node-duckdb.resultiterator.fetchrow.md | 21 ++ .../node-duckdb.resultiterator.isclosed.md | 13 ++ docs/api/node-duckdb.resultiterator.md | 33 +++ docs/api/node-duckdb.resultiterator.type.md | 13 ++ docs/api/node-duckdb.resultstream.md | 19 ++ docs/api/node-duckdb.resulttype.md | 20 ++ docs/api/node-duckdb.rowresultformat.md | 20 ++ docs/replace.sh | 4 + examples/src/stream-example.ts | 2 +- package.json | 12 +- src/addon-types/duckdb-config.ts | 80 +++++++- src/addon-types/result-type.ts | 10 + src/addon/connection.ts | 101 ++++++++++ src/addon/duckdb.ts | 83 ++++++++ src/addon/result-iterator.ts | 35 ++++ src/addon/result-stream.ts | 16 +- src/index.ts | 43 +++- tsconfig.json | 4 +- yarn.lock | 189 +++++++++++++++++- 69 files changed, 1752 insertions(+), 39 deletions(-) create mode 100644 api-extractor.json rename CODE_OF_CONDUCT.md => docs/CODE_OF_CONDUCT.md (100%) rename CONTRIBUTING.md => docs/CONTRIBUTING.md (100%) create mode 100644 docs/DEVELOPING.md create mode 100644 docs/api/index.md create mode 100644 docs/api/node-duckdb.accessmode.md create mode 100644 docs/api/node-duckdb.connection._constructor_.md create mode 100644 docs/api/node-duckdb.connection.close.md create mode 100644 docs/api/node-duckdb.connection.execute.md create mode 100644 docs/api/node-duckdb.connection.executeiterator.md create mode 100644 docs/api/node-duckdb.connection.isclosed.md create mode 100644 docs/api/node-duckdb.connection.md create mode 100644 docs/api/node-duckdb.duckdb._constructor_.md create mode 100644 docs/api/node-duckdb.duckdb.accessmode.md create mode 100644 docs/api/node-duckdb.duckdb.checkpointwalsize.md create mode 100644 docs/api/node-duckdb.duckdb.close.md create mode 100644 docs/api/node-duckdb.duckdb.collation.md create mode 100644 docs/api/node-duckdb.duckdb.defaultnullorder.md create mode 100644 docs/api/node-duckdb.duckdb.defaultordertype.md create mode 100644 docs/api/node-duckdb.duckdb.enablecopy.md create mode 100644 docs/api/node-duckdb.duckdb.isclosed.md create mode 100644 docs/api/node-duckdb.duckdb.maximummemory.md create mode 100644 docs/api/node-duckdb.duckdb.md create mode 100644 docs/api/node-duckdb.duckdb.temporarydirectory.md create mode 100644 docs/api/node-duckdb.duckdb.usetemporarydirectory.md create mode 100644 docs/api/node-duckdb.iduckdbconfig.md create mode 100644 docs/api/node-duckdb.iduckdbconfig.options.md create mode 100644 docs/api/node-duckdb.iduckdbconfig.path.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.accessmode.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.checkpointwalsize.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.collation.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.defaultnullorder.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.defaultordertype.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.enablecopy.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.maximummemory.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.temporarydirectory.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.usedirectio.md create mode 100644 docs/api/node-duckdb.iduckdboptionsconfig.usetemporarydirectory.md create mode 100644 docs/api/node-duckdb.iexecuteoptions.forcematerialized.md create mode 100644 docs/api/node-duckdb.iexecuteoptions.md create mode 100644 docs/api/node-duckdb.iexecuteoptions.rowresultformat.md create mode 100644 docs/api/node-duckdb.md create mode 100644 docs/api/node-duckdb.orderbynulltype.md create mode 100644 docs/api/node-duckdb.ordertype.md create mode 100644 docs/api/node-duckdb.resultiterator.close.md create mode 100644 docs/api/node-duckdb.resultiterator.describe.md create mode 100644 docs/api/node-duckdb.resultiterator.fetchallrows.md create mode 100644 docs/api/node-duckdb.resultiterator.fetchrow.md create mode 100644 docs/api/node-duckdb.resultiterator.isclosed.md create mode 100644 docs/api/node-duckdb.resultiterator.md create mode 100644 docs/api/node-duckdb.resultiterator.type.md create mode 100644 docs/api/node-duckdb.resultstream.md create mode 100644 docs/api/node-duckdb.resulttype.md create mode 100644 docs/api/node-duckdb.rowresultformat.md create mode 100755 docs/replace.sh diff --git a/.gitignore b/.gitignore index d050a43..013ad27 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,5 @@ coverage duckdb duckdb.tar.gz prebuilds +temp +etc diff --git a/README.md b/README.md index 92e19d7..f55289a 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,97 @@ # Node-DuckDB +###### [API](https://github.com/deepcrawl/node-duckdb/docs/api/node-duckdb.md) | [Code Of Conduct](https://github.com/deepcrawl/node-duckdb/docs/CODE_OF_CONDUCT.md) | [Contributing](https://github.com/deepcrawl/node-duckdb/docs/CONTRIBUTING.md) | [Developing](https://github.com/deepcrawl/node-duckdb/docs/DEVELOPING.md) + +> Production ready DuckDB Node.js library written in TypeScript. +> [](https://www.deepcrawl.com/) + ## Overview - This is a library that adds support for [DuckDB](https://duckdb.org/) to NodeJS. -- It comes preinstalled with DuckDB ver 0.2.2 with the parquet extension included. +- It comes preinstalled with DuckDB ver 0.2.2 with the **parquet** extension included. - Has been tested to work with Linux and MacOS. - Currently supports NodeJS v12.17.0+. - Supports BIGINT and HUGEINT types as [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt). -- Provides an async API and a streaming one. +- Provides a **Promise**-based API and a **Stream**-based one. -## Using +## Getting Started -[See examples](https://github.com/deepcrawl/node-duckdb/tree/master/examples) +### Installation -## Developing +To use Node-DuckDB in your project: + +``` +npm i node-duckdb +``` + +or + +``` +yarn add node-duckdb +``` + +Note: this will download the duckdb binary for your platform (currently Linux and MacOS are supported), or if it's not available will attempt to build it. + +### Usage + +Using node-duckdb is easy: + +```ts +const db = new DuckDB(); +const connection = new Connection(db); +await connection.execute("SELECT * FROM mytable;"); +``` + +#### Promise API example -First build: +An example using promises: -1. `yarn install` - installs dependencies including downloading duckdb -2. `yarn build:ts` - builds typescript -3. `yarn test` - runs all tests +```ts +import { Connection, DuckDB } from "node-duckdb"; -Other useful scripts: +async function queryDatabaseWithIterator() { + // create new database in memory + const db = new DuckDB(); + // create a new connection to the database + const connection = new Connection(db); -- `yarn build` - build everything -- `yarn build:addon` - build just the bindings code -- `yarn build:duckdb` - build just the duckdb database -- `yarn build:ts` - build just the typescript code -- `yarn lint` - lint the project -- `yarn test` - run all tests -- `yarn test csv` - run just the csv test suite + // perform some queries + 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;"); -## Publishing + // fetch and print result + console.log(result.fetchAllRows()); + + // release resources + connection.close(); + db.close(); +} + +queryDatabaseWithIterator(); +``` + +#### Streaming API example + +Getting a stream of data from DuckDB and piping into a destination stream: + +```ts +import { Connection, DuckDB } from "node-duckdb"; +const db = new DuckDB(); +const connection = new Connection(db); +const resultStream = await connection.execute("SELECT * FROM people;"); +// get destinationStream somehow +resultStream.pipe(destinationStream); +``` + +#### Complete sample project + +You can see a complete sample project using node-duckdb [here](https://github.com/deepcrawl/node-duckdb/tree/master/examples). + +## API + +API documentation is found [here](https://github.com/deepcrawl/node-duckdb/docs/api/node-duckdb.md). + +## Developing -- `export GITHUB_TOKEN=` - create a PAT in github that allows uploading artifacts to github releases -- `yarn login && yarn publish` - publish will do a bunch of various stuff, including prebuilding binaries for linux/mac and publishing those +Documentation for developers is found [here](https://github.com/deepcrawl/node-duckdb/docs/DEVELOPING.md). diff --git a/api-extractor.json b/api-extractor.json new file mode 100644 index 0000000..3bbbcd5 --- /dev/null +++ b/api-extractor.json @@ -0,0 +1,33 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "mainEntryPointFilePath": "/dist/index.d.ts", + "bundledPackages": [], + "compiler": {}, + "apiReport": { + "enabled": true + }, + "docModel": { + "enabled": true + }, + "dtsRollup": { + "enabled": true + }, + "tsdocMetadata": {}, + "messages": { + "compilerMessageReporting": { + "default": { + "logLevel": "error" + } + }, + "extractorMessageReporting": { + "default": { + "logLevel": "error" + } + }, + "tsdocMessageReporting": { + "default": { + "logLevel": "error" + } + } + } +} diff --git a/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md similarity index 100% rename from CODE_OF_CONDUCT.md rename to docs/CODE_OF_CONDUCT.md diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md diff --git a/docs/DEVELOPING.md b/docs/DEVELOPING.md new file mode 100644 index 0000000..972e81b --- /dev/null +++ b/docs/DEVELOPING.md @@ -0,0 +1,22 @@ +## Developing + +First build: + +1. `yarn install` - installs dependencies including downloading duckdb +2. `yarn build:ts` - builds typescript +3. `yarn test` - runs all tests + +Other useful scripts: + +- `yarn build` - build everything +- `yarn build:addon` - build just the bindings code +- `yarn build:duckdb` - build just the duckdb database +- `yarn build:ts` - build just the typescript code +- `yarn lint` - lint the project +- `yarn test` - run all tests +- `yarn test csv` - run just the csv test suite + +## Publishing + +- `export GITHUB_TOKEN=` - create a PAT in github that allows uploading artifacts to github releases +- `yarn login && yarn publish` - publish will do a bunch of various stuff, including prebuilding binaries for linux/mac and publishing those diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..b1e143a --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) + +## API Reference + +## Packages + +| Package | Description | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [node-duckdb](./node-duckdb.md) | Node-DuckDB is a thin wrapper on top of [DuckDB](https://duckdb.org/).Using it involves:1. Creating a [DuckDB](./node-duckdb.duckdb.md) object2. Creating a [Connection](./node-duckdb.connection.md) object to the DuckDB object3. Calling [Connection.execute](./node-duckdb.connection.execute.md) or [Connection.executeIterator](./node-duckdb.connection.executeiterator.md) on the Connection object | diff --git a/docs/api/node-duckdb.accessmode.md b/docs/api/node-duckdb.accessmode.md new file mode 100644 index 0000000..9606d18 --- /dev/null +++ b/docs/api/node-duckdb.accessmode.md @@ -0,0 +1,22 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [AccessMode](./node-duckdb.accessmode.md) + +## AccessMode enum + +Access mode specifier + +Signature: + +```typescript +export declare enum AccessMode +``` + +## Enumeration Members + +| Member | Value | Description | +| --------- | -------------- | ----------- | +| Automatic | 1 | | +| ReadOnly | 2 | | +| ReadWrite | 3 | | +| Undefined | 0 | | diff --git a/docs/api/node-duckdb.connection._constructor_.md b/docs/api/node-duckdb.connection._constructor_.md new file mode 100644 index 0000000..91840e1 --- /dev/null +++ b/docs/api/node-duckdb.connection._constructor_.md @@ -0,0 +1,30 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [Connection](./node-duckdb.connection.md) > [(constructor)](./node-duckdb.connection._constructor_.md) + +## Connection.(constructor) + +Connection constructor. + +Signature: + +```typescript +constructor(duckdb: DuckDB); +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | --------------------------------- | --------------------------------------------------------- | +| duckdb | [DuckDB](./node-duckdb.duckdb.md) | [DuckDB](./node-duckdb.duckdb.md) instance to connect to. | + +## Example + +Initializing a connection: + +``` +import { DuckDB } from "node-duckdb"; +const db = new DuckDB(); +const connection = new Connection(db); + +``` diff --git a/docs/api/node-duckdb.connection.close.md b/docs/api/node-duckdb.connection.close.md new file mode 100644 index 0000000..48c6f31 --- /dev/null +++ b/docs/api/node-duckdb.connection.close.md @@ -0,0 +1,21 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [Connection](./node-duckdb.connection.md) > [close](./node-duckdb.connection.close.md) + +## 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). + +Signature: + +```typescript +close(): void; +``` + +Returns: + +void + +## 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()`. diff --git a/docs/api/node-duckdb.connection.execute.md b/docs/api/node-duckdb.connection.execute.md new file mode 100644 index 0000000..5df3a45 --- /dev/null +++ b/docs/api/node-duckdb.connection.execute.md @@ -0,0 +1,56 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [Connection](./node-duckdb.connection.md) > [execute](./node-duckdb.connection.execute.md) + +## Connection.execute() method + +Asynchronously executes the query and returns a node.js stream that wraps the result set. + +Signature: + +```typescript +execute(command: string, options?: IExecuteOptions): Promise>; +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | --------------------------------------------------- | ----------------------------------------------------------------------------------- | +| command | string | SQL command to execute | +| options | [IExecuteOptions](./node-duckdb.iexecuteoptions.md) | optional options object of type [IExecuteOptions](./node-duckdb.iexecuteoptions.md) | + +Returns: + +Promise<[ResultStream](./node-duckdb.resultstream.md)<T>> + +## Example + +Streaming results of a DuckDB query into a CSV file: + +``` +import { Connection, DuckDB, RowResultFormat } from "node-duckdb"; +import { createWriteStream } from "fs"; +import { Transform } from "stream"; +class ArrayToCsvTransform extends Transform { + constructor() { + super({objectMode: true}) + } + _transform(chunk: any[], _encoding: string, callback: any) { + this.push(chunk.join(",") + '\n'); + callback(); + } +} + +async function outputToFileAsCsv() { + const db = new DuckDB(); + const connection = new Connection(db); + await connection.execute("CREATE TABLE people(id INTEGER, name VARCHAR);"); + await connection.execute("INSERT INTO people VALUES (1, 'Mark'), (2, 'Hannes'), (3, 'Bob');"); + const resultStream = await connection.execute("SELECT * FROM people;", {rowResultFormat: RowResultFormat.Array}); + const transformToCsvStream = new ArrayToCsvTransform(); + const writeStream = createWriteStream("my-people-output"); + resultStream.pipe(transformToCsvStream).pipe(writeStream); +} +outputToFileAsCsv(); + +``` diff --git a/docs/api/node-duckdb.connection.executeiterator.md b/docs/api/node-duckdb.connection.executeiterator.md new file mode 100644 index 0000000..2485b07 --- /dev/null +++ b/docs/api/node-duckdb.connection.executeiterator.md @@ -0,0 +1,61 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [Connection](./node-duckdb.connection.md) > [executeIterator](./node-duckdb.connection.executeiterator.md) + +## Connection.executeIterator() method + +Asynchronously executes the query and returns an iterator that points to the first result in the result set. + +Signature: + +```typescript +executeIterator(command: string, options?: IExecuteOptions): Promise>; +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | --------------------------------------------------- | ----------------------------------------------------------------------------------- | +| command | string | SQL command to execute | +| options | [IExecuteOptions](./node-duckdb.iexecuteoptions.md) | optional options object of type [IExecuteOptions](./node-duckdb.iexecuteoptions.md) | + +Returns: + +Promise<[ResultIterator](./node-duckdb.resultiterator.md)<T>> + +## Example 1 + +Printing rows: + +``` +import { Connection, DuckDB, RowResultFormat } from "node-duckdb"; +async function queryDatabaseWithIterator() { + const db = new DuckDB(); + const connection = new Connection(db); + 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 + console.log(result.fetchRow()); + // print the rest of the rows + console.log(result.fetchAllRows()); + const result2 = await connection.executeIterator("SELECT * FROM people;", {rowResultFormat: RowResultFormat.Array}); + console.log(result2.fetchAllRows()); + connection.close(); + db.close(); +} +queryDatabaseWithIterator(); + +``` + +## Example 2 + +Providing generics type: + +``` +const result = await connection.executeIterator(`SELECT CAST(1 AS TINYINT)`, { + rowResultFormat: RowResultFormat.Array, +}); +expect(result.fetchRow()).toMatchObject([1]); + +``` diff --git a/docs/api/node-duckdb.connection.isclosed.md b/docs/api/node-duckdb.connection.isclosed.md new file mode 100644 index 0000000..0e90045 --- /dev/null +++ b/docs/api/node-duckdb.connection.isclosed.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [Connection](./node-duckdb.connection.md) > [isClosed](./node-duckdb.connection.isclosed.md) + +## Connection.isClosed property + +If the connection is closed returns true, otherwise false. + +Signature: + +```typescript +get isClosed(): boolean; +``` diff --git a/docs/api/node-duckdb.connection.md b/docs/api/node-duckdb.connection.md new file mode 100644 index 0000000..8875da1 --- /dev/null +++ b/docs/api/node-duckdb.connection.md @@ -0,0 +1,37 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [Connection](./node-duckdb.connection.md) + +## Connection class + +Represents a DuckDB connection. + +Signature: + +```typescript +export declare class Connection +``` + +## Remarks + +A single db instance can have multiple connections. Having more than one connection instance is required when executing concurrent queries. + +## Constructors + +| Constructor | Modifiers | Description | +| ------------------------------------------------------------------ | --------- | ----------------------- | +| [(constructor)(duckdb)](./node-duckdb.connection._constructor_.md) | | Connection constructor. | + +## Properties + +| Property | Modifiers | Type | Description | +| ------------------------------------------------ | --------- | ------- | ---------------------------------------------------------- | +| [isClosed](./node-duckdb.connection.isclosed.md) | | boolean | If the connection is closed returns true, otherwise false. | + +## 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. | diff --git a/docs/api/node-duckdb.duckdb._constructor_.md b/docs/api/node-duckdb.duckdb._constructor_.md new file mode 100644 index 0000000..cb02f0b --- /dev/null +++ b/docs/api/node-duckdb.duckdb._constructor_.md @@ -0,0 +1,49 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [(constructor)](./node-duckdb.duckdb._constructor_.md) + +## DuckDB.(constructor) + +Represents a native instance of DuckDB. + +Signature: + +```typescript +constructor(config?: IDuckDBConfig); +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| config | [IDuckDBConfig](./node-duckdb.iduckdbconfig.md) | optional configuration object of type [IDuckDBConfig](./node-duckdb.iduckdbconfig.md). | + +## Example 1 + +Initializing a duckdb database in memory: + +``` +import { DuckDB } from "node-duckdb"; +const db = new DuckDB(); + +``` + +## Example 2 + +Initializing a duckdb database from file: + +``` +import { DuckDB } from "node-duckdb"; +const db = new DuckDB({ path: join(__dirname, "./mydb") }); + +``` + +## Example 3 + +Initializing a duckdb database from file and setting some additional options: + +``` +import { DuckDB, OrderType } from "node-duckdb"; +const db = new DuckDB({ path: join(__dirname, "./mydb"), options: { defaultOrderType: OrderType.Descending, temporaryDirectory: false } }); + +``` diff --git a/docs/api/node-duckdb.duckdb.accessmode.md b/docs/api/node-duckdb.duckdb.accessmode.md new file mode 100644 index 0000000..ef5b545 --- /dev/null +++ b/docs/api/node-duckdb.duckdb.accessmode.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [accessMode](./node-duckdb.duckdb.accessmode.md) + +## DuckDB.accessMode property + +Returns the [access mode](./node-duckdb.accessmode.md) used by the database. + +Signature: + +```typescript +get accessMode(): AccessMode; +``` diff --git a/docs/api/node-duckdb.duckdb.checkpointwalsize.md b/docs/api/node-duckdb.duckdb.checkpointwalsize.md new file mode 100644 index 0000000..07842a6 --- /dev/null +++ b/docs/api/node-duckdb.duckdb.checkpointwalsize.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [checkPointWALSize](./node-duckdb.duckdb.checkpointwalsize.md) + +## DuckDB.checkPointWALSize property + +Returns the checkpoint write ahead log size used by the database. + +Signature: + +```typescript +get checkPointWALSize(): number; +``` diff --git a/docs/api/node-duckdb.duckdb.close.md b/docs/api/node-duckdb.duckdb.close.md new file mode 100644 index 0000000..cf4a909 --- /dev/null +++ b/docs/api/node-duckdb.duckdb.close.md @@ -0,0 +1,21 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [close](./node-duckdb.duckdb.close.md) + +## DuckDB.close() method + +Closes the underlying duckdb database, frees associated memory and renders it unusuable. + +Signature: + +```typescript +close(): void; +``` + +Returns: + +void + +## Remarks + +Even though GC will automatically destroy the Database 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()`. diff --git a/docs/api/node-duckdb.duckdb.collation.md b/docs/api/node-duckdb.duckdb.collation.md new file mode 100644 index 0000000..1beec12 --- /dev/null +++ b/docs/api/node-duckdb.duckdb.collation.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [collation](./node-duckdb.duckdb.collation.md) + +## DuckDB.collation property + +Returns the collation used by the database. + +Signature: + +```typescript +get collation(): string; +``` diff --git a/docs/api/node-duckdb.duckdb.defaultnullorder.md b/docs/api/node-duckdb.duckdb.defaultnullorder.md new file mode 100644 index 0000000..0a68bbc --- /dev/null +++ b/docs/api/node-duckdb.duckdb.defaultnullorder.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [defaultNullOrder](./node-duckdb.duckdb.defaultnullorder.md) + +## DuckDB.defaultNullOrder property + +Returns the default [sort order for null values](./node-duckdb.orderbynulltype.md). + +Signature: + +```typescript +get defaultNullOrder(): OrderByNullType; +``` diff --git a/docs/api/node-duckdb.duckdb.defaultordertype.md b/docs/api/node-duckdb.duckdb.defaultordertype.md new file mode 100644 index 0000000..2942809 --- /dev/null +++ b/docs/api/node-duckdb.duckdb.defaultordertype.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [defaultOrderType](./node-duckdb.duckdb.defaultordertype.md) + +## DuckDB.defaultOrderType property + +Returns the default [sort order](./node-duckdb.ordertype.md). + +Signature: + +```typescript +get defaultOrderType(): OrderType; +``` diff --git a/docs/api/node-duckdb.duckdb.enablecopy.md b/docs/api/node-duckdb.duckdb.enablecopy.md new file mode 100644 index 0000000..0860e2f --- /dev/null +++ b/docs/api/node-duckdb.duckdb.enablecopy.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [enableCopy](./node-duckdb.duckdb.enablecopy.md) + +## DuckDB.enableCopy property + +Returns true of copying is enabled, false otherwise. + +Signature: + +```typescript +get enableCopy(): boolean; +``` diff --git a/docs/api/node-duckdb.duckdb.isclosed.md b/docs/api/node-duckdb.duckdb.isclosed.md new file mode 100644 index 0000000..88197c2 --- /dev/null +++ b/docs/api/node-duckdb.duckdb.isclosed.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [isClosed](./node-duckdb.duckdb.isclosed.md) + +## DuckDB.isClosed property + +Returns true if the underlying database has been closed, false otherwise. + +Signature: + +```typescript +get isClosed(): boolean; +``` diff --git a/docs/api/node-duckdb.duckdb.maximummemory.md b/docs/api/node-duckdb.duckdb.maximummemory.md new file mode 100644 index 0000000..ad05ab6 --- /dev/null +++ b/docs/api/node-duckdb.duckdb.maximummemory.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [maximumMemory](./node-duckdb.duckdb.maximummemory.md) + +## DuckDB.maximumMemory property + +Returns the maximum memory limit for the database. + +Signature: + +```typescript +get maximumMemory(): number; +``` diff --git a/docs/api/node-duckdb.duckdb.md b/docs/api/node-duckdb.duckdb.md new file mode 100644 index 0000000..5f9f571 --- /dev/null +++ b/docs/api/node-duckdb.duckdb.md @@ -0,0 +1,40 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) + +## DuckDB class + +The DuckDB class represents a DuckDB database instance. + +Signature: + +```typescript +export declare class DuckDB +``` + +## Constructors + +| Constructor | Modifiers | Description | +| -------------------------------------------------------------- | --------- | --------------------------------------- | +| [(constructor)(config)](./node-duckdb.duckdb._constructor_.md) | | Represents a native instance of DuckDB. | + +## Properties + +| Property | Modifiers | Type | Description | +| ---------------------------------------------------------------------- | --------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| [accessMode](./node-duckdb.duckdb.accessmode.md) | | [AccessMode](./node-duckdb.accessmode.md) | Returns the [access mode](./node-duckdb.accessmode.md) used by the database. | +| [checkPointWALSize](./node-duckdb.duckdb.checkpointwalsize.md) | | number | Returns the checkpoint write ahead log size used by the database. | +| [collation](./node-duckdb.duckdb.collation.md) | | string | Returns the collation used by the database. | +| [defaultNullOrder](./node-duckdb.duckdb.defaultnullorder.md) | | [OrderByNullType](./node-duckdb.orderbynulltype.md) | Returns the default [sort order for null values](./node-duckdb.orderbynulltype.md). | +| [defaultOrderType](./node-duckdb.duckdb.defaultordertype.md) | | [OrderType](./node-duckdb.ordertype.md) | Returns the default [sort order](./node-duckdb.ordertype.md). | +| [enableCopy](./node-duckdb.duckdb.enablecopy.md) | | boolean | Returns true of copying is enabled, false otherwise. | +| [isClosed](./node-duckdb.duckdb.isclosed.md) | | boolean | Returns true if the underlying database has been closed, false otherwise. | +| [maximumMemory](./node-duckdb.duckdb.maximummemory.md) | | number | Returns the maximum memory limit for the database. | +| [temporaryDirectory](./node-duckdb.duckdb.temporarydirectory.md) | | string | Returns the temporary directory location for the database. | +| [useTemporaryDirectory](./node-duckdb.duckdb.usetemporarydirectory.md) | | boolean | Returns true if the database uses a temporary directory for storing data that does not fit into memory, false otherwise. | + +## Methods + +| Method | Modifiers | Description | +| ---------------------------------------- | --------- | ---------------------------------------------------------------------------------------- | +| [close()](./node-duckdb.duckdb.close.md) | | Closes the underlying duckdb database, frees associated memory and renders it unusuable. | diff --git a/docs/api/node-duckdb.duckdb.temporarydirectory.md b/docs/api/node-duckdb.duckdb.temporarydirectory.md new file mode 100644 index 0000000..3da5d6b --- /dev/null +++ b/docs/api/node-duckdb.duckdb.temporarydirectory.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [temporaryDirectory](./node-duckdb.duckdb.temporarydirectory.md) + +## DuckDB.temporaryDirectory property + +Returns the temporary directory location for the database. + +Signature: + +```typescript +get temporaryDirectory(): string; +``` diff --git a/docs/api/node-duckdb.duckdb.usetemporarydirectory.md b/docs/api/node-duckdb.duckdb.usetemporarydirectory.md new file mode 100644 index 0000000..f9597bb --- /dev/null +++ b/docs/api/node-duckdb.duckdb.usetemporarydirectory.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [DuckDB](./node-duckdb.duckdb.md) > [useTemporaryDirectory](./node-duckdb.duckdb.usetemporarydirectory.md) + +## DuckDB.useTemporaryDirectory property + +Returns true if the database uses a temporary directory for storing data that does not fit into memory, false otherwise. + +Signature: + +```typescript +get useTemporaryDirectory(): boolean; +``` diff --git a/docs/api/node-duckdb.iduckdbconfig.md b/docs/api/node-duckdb.iduckdbconfig.md new file mode 100644 index 0000000..569675d --- /dev/null +++ b/docs/api/node-duckdb.iduckdbconfig.md @@ -0,0 +1,20 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBConfig](./node-duckdb.iduckdbconfig.md) + +## IDuckDBConfig interface + +Configuration object for DuckDB + +Signature: + +```typescript +export interface IDuckDBConfig +``` + +## Properties + +| Property | Type | Description | +| -------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| [options?](./node-duckdb.iduckdbconfig.options.md) | [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) | (Optional) | +| [path?](./node-duckdb.iduckdbconfig.path.md) | string | (Optional) Path to the database file. If undefined, in-memory database is created | diff --git a/docs/api/node-duckdb.iduckdbconfig.options.md b/docs/api/node-duckdb.iduckdbconfig.options.md new file mode 100644 index 0000000..1fea208 --- /dev/null +++ b/docs/api/node-duckdb.iduckdbconfig.options.md @@ -0,0 +1,11 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBConfig](./node-duckdb.iduckdbconfig.md) > [options](./node-duckdb.iduckdbconfig.options.md) + +## IDuckDBConfig.options property + +Signature: + +```typescript +options?: IDuckDBOptionsConfig; +``` diff --git a/docs/api/node-duckdb.iduckdbconfig.path.md b/docs/api/node-duckdb.iduckdbconfig.path.md new file mode 100644 index 0000000..bb9dafe --- /dev/null +++ b/docs/api/node-duckdb.iduckdbconfig.path.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBConfig](./node-duckdb.iduckdbconfig.md) > [path](./node-duckdb.iduckdbconfig.path.md) + +## IDuckDBConfig.path property + +Path to the database file. If undefined, in-memory database is created + +Signature: + +```typescript +path?: string; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.accessmode.md b/docs/api/node-duckdb.iduckdboptionsconfig.accessmode.md new file mode 100644 index 0000000..f1d23e8 --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.accessmode.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [accessMode](./node-duckdb.iduckdboptionsconfig.accessmode.md) + +## IDuckDBOptionsConfig.accessMode property + +Access Mode + +Signature: + +```typescript +accessMode?: AccessMode; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.checkpointwalsize.md b/docs/api/node-duckdb.iduckdboptionsconfig.checkpointwalsize.md new file mode 100644 index 0000000..0aae849 --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.checkpointwalsize.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [checkPointWALSize](./node-duckdb.iduckdboptionsconfig.checkpointwalsize.md) + +## IDuckDBOptionsConfig.checkPointWALSize property + +Checkpoint Write Ahead Log Size (in bytes) + +Signature: + +```typescript +checkPointWALSize?: number; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.collation.md b/docs/api/node-duckdb.iduckdboptionsconfig.collation.md new file mode 100644 index 0000000..c76189d --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.collation.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [collation](./node-duckdb.iduckdboptionsconfig.collation.md) + +## IDuckDBOptionsConfig.collation property + +Collation + +Signature: + +```typescript +collation?: string; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.defaultnullorder.md b/docs/api/node-duckdb.iduckdboptionsconfig.defaultnullorder.md new file mode 100644 index 0000000..0ab3d4b --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.defaultnullorder.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [defaultNullOrder](./node-duckdb.iduckdboptionsconfig.defaultnullorder.md) + +## IDuckDBOptionsConfig.defaultNullOrder property + +Default order for Null values + +Signature: + +```typescript +defaultNullOrder?: OrderByNullType; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.defaultordertype.md b/docs/api/node-duckdb.iduckdboptionsconfig.defaultordertype.md new file mode 100644 index 0000000..694f4d4 --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.defaultordertype.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [defaultOrderType](./node-duckdb.iduckdboptionsconfig.defaultordertype.md) + +## IDuckDBOptionsConfig.defaultOrderType property + +Default Order + +Signature: + +```typescript +defaultOrderType?: OrderType; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.enablecopy.md b/docs/api/node-duckdb.iduckdboptionsconfig.enablecopy.md new file mode 100644 index 0000000..b56fc43 --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.enablecopy.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [enableCopy](./node-duckdb.iduckdboptionsconfig.enablecopy.md) + +## IDuckDBOptionsConfig.enableCopy property + +Enable Copy + +Signature: + +```typescript +enableCopy?: boolean; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.maximummemory.md b/docs/api/node-duckdb.iduckdboptionsconfig.maximummemory.md new file mode 100644 index 0000000..92977b8 --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.maximummemory.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [maximumMemory](./node-duckdb.iduckdboptionsconfig.maximummemory.md) + +## IDuckDBOptionsConfig.maximumMemory property + +Maximum memory limit for the databse (in bytes) + +Signature: + +```typescript +maximumMemory?: number; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.md b/docs/api/node-duckdb.iduckdboptionsconfig.md new file mode 100644 index 0000000..2205121 --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.md @@ -0,0 +1,28 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) + +## IDuckDBOptionsConfig interface + +Options object type for the DuckDB class + +Signature: + +```typescript +export interface IDuckDBOptionsConfig +``` + +## Properties + +| Property | Type | Description | +| ------------------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| [accessMode?](./node-duckdb.iduckdboptionsconfig.accessmode.md) | [AccessMode](./node-duckdb.accessmode.md) | (Optional) Access Mode | +| [checkPointWALSize?](./node-duckdb.iduckdboptionsconfig.checkpointwalsize.md) | number | (Optional) Checkpoint Write Ahead Log Size (in bytes) | +| [collation?](./node-duckdb.iduckdboptionsconfig.collation.md) | string | (Optional) Collation | +| [defaultNullOrder?](./node-duckdb.iduckdboptionsconfig.defaultnullorder.md) | [OrderByNullType](./node-duckdb.orderbynulltype.md) | (Optional) Default order for Null values | +| [defaultOrderType?](./node-duckdb.iduckdboptionsconfig.defaultordertype.md) | [OrderType](./node-duckdb.ordertype.md) | (Optional) Default Order | +| [enableCopy?](./node-duckdb.iduckdboptionsconfig.enablecopy.md) | boolean | (Optional) Enable Copy | +| [maximumMemory?](./node-duckdb.iduckdboptionsconfig.maximummemory.md) | number | (Optional) Maximum memory limit for the databse (in bytes) | +| [temporaryDirectory?](./node-duckdb.iduckdboptionsconfig.temporarydirectory.md) | string | (Optional) Location of the temporary directory | +| [useDirectIO?](./node-duckdb.iduckdboptionsconfig.usedirectio.md) | boolean | (Optional) Whether to use Direct IO | +| [useTemporaryDirectory?](./node-duckdb.iduckdboptionsconfig.usetemporarydirectory.md) | boolean | (Optional) Whether to use temporary directory to store data that doesn't fit in memory | diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.temporarydirectory.md b/docs/api/node-duckdb.iduckdboptionsconfig.temporarydirectory.md new file mode 100644 index 0000000..b904098 --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.temporarydirectory.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [temporaryDirectory](./node-duckdb.iduckdboptionsconfig.temporarydirectory.md) + +## IDuckDBOptionsConfig.temporaryDirectory property + +Location of the temporary directory + +Signature: + +```typescript +temporaryDirectory?: string; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.usedirectio.md b/docs/api/node-duckdb.iduckdboptionsconfig.usedirectio.md new file mode 100644 index 0000000..b0539cf --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.usedirectio.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [useDirectIO](./node-duckdb.iduckdboptionsconfig.usedirectio.md) + +## IDuckDBOptionsConfig.useDirectIO property + +Whether to use Direct IO + +Signature: + +```typescript +useDirectIO?: boolean; +``` diff --git a/docs/api/node-duckdb.iduckdboptionsconfig.usetemporarydirectory.md b/docs/api/node-duckdb.iduckdboptionsconfig.usetemporarydirectory.md new file mode 100644 index 0000000..18780f9 --- /dev/null +++ b/docs/api/node-duckdb.iduckdboptionsconfig.usetemporarydirectory.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) > [useTemporaryDirectory](./node-duckdb.iduckdboptionsconfig.usetemporarydirectory.md) + +## IDuckDBOptionsConfig.useTemporaryDirectory property + +Whether to use temporary directory to store data that doesn't fit in memory + +Signature: + +```typescript +useTemporaryDirectory?: boolean; +``` diff --git a/docs/api/node-duckdb.iexecuteoptions.forcematerialized.md b/docs/api/node-duckdb.iexecuteoptions.forcematerialized.md new file mode 100644 index 0000000..70f8211 --- /dev/null +++ b/docs/api/node-duckdb.iexecuteoptions.forcematerialized.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IExecuteOptions](./node-duckdb.iexecuteoptions.md) > [forceMaterialized](./node-duckdb.iexecuteoptions.forcematerialized.md) + +## IExecuteOptions.forceMaterialized property + +Materialized means that the whole result is loaded into memory, as opposed to streaming which means there is a pointer to the next row and rows are retrieved one by one. If falsy, DuckDB will \*attempt\* to not load the whole result set into memory at once. + +Signature: + +```typescript +forceMaterialized?: boolean; +``` diff --git a/docs/api/node-duckdb.iexecuteoptions.md b/docs/api/node-duckdb.iexecuteoptions.md new file mode 100644 index 0000000..7b8484e --- /dev/null +++ b/docs/api/node-duckdb.iexecuteoptions.md @@ -0,0 +1,20 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IExecuteOptions](./node-duckdb.iexecuteoptions.md) + +## IExecuteOptions interface + +Options for connection.execute + +Signature: + +```typescript +export interface IExecuteOptions +``` + +## Properties + +| Property | Type | Description | +| ------------------------------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [forceMaterialized?](./node-duckdb.iexecuteoptions.forcematerialized.md) | boolean | (Optional) Materialized means that the whole result is loaded into memory, as opposed to streaming which means there is a pointer to the next row and rows are retrieved one by one. If falsy, DuckDB will \*attempt\* to not load the whole result set into memory at once. | +| [rowResultFormat?](./node-duckdb.iexecuteoptions.rowresultformat.md) | [RowResultFormat](./node-duckdb.rowresultformat.md) | (Optional) Row format | diff --git a/docs/api/node-duckdb.iexecuteoptions.rowresultformat.md b/docs/api/node-duckdb.iexecuteoptions.rowresultformat.md new file mode 100644 index 0000000..7d304fe --- /dev/null +++ b/docs/api/node-duckdb.iexecuteoptions.rowresultformat.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [IExecuteOptions](./node-duckdb.iexecuteoptions.md) > [rowResultFormat](./node-duckdb.iexecuteoptions.rowresultformat.md) + +## IExecuteOptions.rowResultFormat property + +Row format + +Signature: + +```typescript +rowResultFormat?: RowResultFormat; +``` diff --git a/docs/api/node-duckdb.md b/docs/api/node-duckdb.md new file mode 100644 index 0000000..49c4732 --- /dev/null +++ b/docs/api/node-duckdb.md @@ -0,0 +1,74 @@ + + +[Node-DuckDB API](./node-duckdb.md) + +## Node-DuckDB API + +Node-DuckDB is a thin wrapper on top of [DuckDB](https://duckdb.org/). + +Using it involves: + +1. Creating a [DuckDB](./node-duckdb.duckdb.md) object + +2. Creating a [Connection](./node-duckdb.connection.md) object to the DuckDB object + +3. Calling [Connection.execute](./node-duckdb.connection.execute.md) or [Connection.executeIterator](./node-duckdb.connection.executeiterator.md) on the Connection object + +## Example + +Do some simple querying and print the result + +``` +import { Connection, DuckDB } from "node-duckdb"; + +async function queryDatabaseWithIterator() { + // create new database in memory + const db = new DuckDB(); + // create a new connection to the database + const connection = new Connection(db); + + // perform some queries + 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;"); + + // fetch and print result + console.log(result.fetchAllRows()); + + // release resources + connection.close(); + db.close(); +} + +queryDatabaseWithIterator(); + +``` + +For more examples see [here](https://github.com/deepcrawl/node-duckdb/tree/feature/ODIN-423-welcome-page/examples). + +## Classes + +| Class | Description | +| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [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 + +| Enumeration | Description | +| --------------------------------------------------- | ---------------------------------------------------- | +| [AccessMode](./node-duckdb.accessmode.md) | Access mode specifier | +| [OrderByNullType](./node-duckdb.orderbynulltype.md) | Null order specifier | +| [OrderType](./node-duckdb.ordertype.md) | Default sort order specifier | +| [ResultType](./node-duckdb.resulttype.md) | Specifier for how DuckDB attempts to load the result | +| [RowResultFormat](./node-duckdb.rowresultformat.md) | Result format specifier for rows | + +## Interfaces + +| Interface | Description | +| ------------------------------------------------------------- | ---------------------------------------- | +| [IDuckDBConfig](./node-duckdb.iduckdbconfig.md) | Configuration object for DuckDB | +| [IDuckDBOptionsConfig](./node-duckdb.iduckdboptionsconfig.md) | Options object type for the DuckDB class | +| [IExecuteOptions](./node-duckdb.iexecuteoptions.md) | Options for connection.execute | diff --git a/docs/api/node-duckdb.orderbynulltype.md b/docs/api/node-duckdb.orderbynulltype.md new file mode 100644 index 0000000..a26b9d3 --- /dev/null +++ b/docs/api/node-duckdb.orderbynulltype.md @@ -0,0 +1,22 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [OrderByNullType](./node-duckdb.orderbynulltype.md) + +## OrderByNullType enum + +Null order specifier + +Signature: + +```typescript +export declare enum OrderByNullType +``` + +## Enumeration Members + +| Member | Value | Description | +| ---------- | -------------- | ----------- | +| Default | 1 | | +| Invalid | 0 | | +| NullsFirst | 2 | | +| NullsLast | 3 | | diff --git a/docs/api/node-duckdb.ordertype.md b/docs/api/node-duckdb.ordertype.md new file mode 100644 index 0000000..87b5851 --- /dev/null +++ b/docs/api/node-duckdb.ordertype.md @@ -0,0 +1,22 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [OrderType](./node-duckdb.ordertype.md) + +## OrderType enum + +Default sort order specifier + +Signature: + +```typescript +export declare enum OrderType +``` + +## Enumeration Members + +| Member | Value | Description | +| ---------- | -------------- | ----------- | +| Ascending | 2 | | +| Default | 1 | | +| Descending | 3 | | +| Invalid | 0 | | diff --git a/docs/api/node-duckdb.resultiterator.close.md b/docs/api/node-duckdb.resultiterator.close.md new file mode 100644 index 0000000..ac64ffe --- /dev/null +++ b/docs/api/node-duckdb.resultiterator.close.md @@ -0,0 +1,21 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultIterator](./node-duckdb.resultiterator.md) > [close](./node-duckdb.resultiterator.close.md) + +## ResultIterator.close() method + +Close the ResultIterator + +Signature: + +```typescript +close(): void; +``` + +Returns: + +void + +## Remarks + +[Connection.close](./node-duckdb.connection.close.md) automatically closes all associated ResultIterators. diff --git a/docs/api/node-duckdb.resultiterator.describe.md b/docs/api/node-duckdb.resultiterator.describe.md new file mode 100644 index 0000000..e60ee63 --- /dev/null +++ b/docs/api/node-duckdb.resultiterator.describe.md @@ -0,0 +1,17 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultIterator](./node-duckdb.resultiterator.md) > [describe](./node-duckdb.resultiterator.describe.md) + +## ResultIterator.describe() method + +Describe the result set schema. + +Signature: + +```typescript +describe(): string[][]; +``` + +Returns: + +string\[\]\[\] diff --git a/docs/api/node-duckdb.resultiterator.fetchallrows.md b/docs/api/node-duckdb.resultiterator.fetchallrows.md new file mode 100644 index 0000000..76b3d55 --- /dev/null +++ b/docs/api/node-duckdb.resultiterator.fetchallrows.md @@ -0,0 +1,21 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultIterator](./node-duckdb.resultiterator.md) > [fetchAllRows](./node-duckdb.resultiterator.fetchallrows.md) + +## ResultIterator.fetchAllRows() method + +Fetch all rows + +Signature: + +```typescript +fetchAllRows(): T[]; +``` + +Returns: + +T\[\] + +## Remarks + +Note, this may produce a `heap out of bounds` error in case when there is too much data. Either use the [fetchRow](./node-duckdb.resultiterator.fetchrow.md) or the [Connection.execute](./node-duckdb.connection.execute.md) method when there is a lot of data. diff --git a/docs/api/node-duckdb.resultiterator.fetchrow.md b/docs/api/node-duckdb.resultiterator.fetchrow.md new file mode 100644 index 0000000..9cd56c7 --- /dev/null +++ b/docs/api/node-duckdb.resultiterator.fetchrow.md @@ -0,0 +1,21 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultIterator](./node-duckdb.resultiterator.md) > [fetchRow](./node-duckdb.resultiterator.fetchrow.md) + +## ResultIterator.fetchRow() method + +Fetch the next row + +Signature: + +```typescript +fetchRow(): T; +``` + +Returns: + +T + +## Remarks + +First call returns the first row, when no more rows left `null` is returned. diff --git a/docs/api/node-duckdb.resultiterator.isclosed.md b/docs/api/node-duckdb.resultiterator.isclosed.md new file mode 100644 index 0000000..c4a4198 --- /dev/null +++ b/docs/api/node-duckdb.resultiterator.isclosed.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultIterator](./node-duckdb.resultiterator.md) > [isClosed](./node-duckdb.resultiterator.isclosed.md) + +## ResultIterator.isClosed property + +Returns true if ResultIterator is closed, false otherwise. + +Signature: + +```typescript +get isClosed(): boolean; +``` diff --git a/docs/api/node-duckdb.resultiterator.md b/docs/api/node-duckdb.resultiterator.md new file mode 100644 index 0000000..1511883 --- /dev/null +++ b/docs/api/node-duckdb.resultiterator.md @@ -0,0 +1,33 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultIterator](./node-duckdb.resultiterator.md) + +## ResultIterator class + +ResultIterator represents the result set of a DuckDB query. Instances of this class are returned by the [Connection.executeIterator](./node-duckdb.connection.executeiterator.md). + +Signature: + +```typescript +export declare class ResultIterator +``` + +## 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. + +## Properties + +| Property | Modifiers | Type | Description | +| ---------------------------------------------------- | --------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [isClosed](./node-duckdb.resultiterator.isclosed.md) | | boolean | Returns true if ResultIterator is closed, false otherwise. | +| [type](./node-duckdb.resultiterator.type.md) | | [ResultType](./node-duckdb.resulttype.md) | Get the [ResultType](./node-duckdb.resulttype.md) of the ResultIterator. This is specified by the [options](./node-duckdb.iexecuteoptions.forcematerialized.md) argument on [executeIterator](./node-duckdb.connection.executeiterator.md). | + +## 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 | diff --git a/docs/api/node-duckdb.resultiterator.type.md b/docs/api/node-duckdb.resultiterator.type.md new file mode 100644 index 0000000..d69279a --- /dev/null +++ b/docs/api/node-duckdb.resultiterator.type.md @@ -0,0 +1,13 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultIterator](./node-duckdb.resultiterator.md) > [type](./node-duckdb.resultiterator.type.md) + +## ResultIterator.type property + +Get the [ResultType](./node-duckdb.resulttype.md) of the ResultIterator. This is specified by the [options](./node-duckdb.iexecuteoptions.forcematerialized.md) argument on [executeIterator](./node-duckdb.connection.executeiterator.md). + +Signature: + +```typescript +get type(): ResultType; +``` diff --git a/docs/api/node-duckdb.resultstream.md b/docs/api/node-duckdb.resultstream.md new file mode 100644 index 0000000..d206280 --- /dev/null +++ b/docs/api/node-duckdb.resultstream.md @@ -0,0 +1,19 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultStream](./node-duckdb.resultstream.md) + +## ResultStream class + +This is a Readable stream that wrapps the ResultIterator. Instances of this class are returned by [Connection.execute](./node-duckdb.connection.execute.md). + +Signature: + +```typescript +export declare class ResultStream extends Readable +``` + +Extends: Readable + +## 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 `ResultStream` class. diff --git a/docs/api/node-duckdb.resulttype.md b/docs/api/node-duckdb.resulttype.md new file mode 100644 index 0000000..9b8cbc5 --- /dev/null +++ b/docs/api/node-duckdb.resulttype.md @@ -0,0 +1,20 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [ResultType](./node-duckdb.resulttype.md) + +## ResultType enum + +Specifier for how DuckDB attempts to load the result + +Signature: + +```typescript +export declare enum ResultType +``` + +## Enumeration Members + +| Member | Value | Description | +| ------------ | ------------------------------------- | -------------------------------------------------------------------------- | +| Materialized | "Materialized" | Load the whole result set into memory | +| Streaming | "Streaming" | Keep pointer to the first row, don't load the whole result set all at once | diff --git a/docs/api/node-duckdb.rowresultformat.md b/docs/api/node-duckdb.rowresultformat.md new file mode 100644 index 0000000..e810633 --- /dev/null +++ b/docs/api/node-duckdb.rowresultformat.md @@ -0,0 +1,20 @@ + + +[Node-DuckDB API](./node-duckdb.md) > [RowResultFormat](./node-duckdb.rowresultformat.md) + +## RowResultFormat enum + +Result format specifier for rows + +Signature: + +```typescript +export declare enum RowResultFormat +``` + +## Enumeration Members + +| Member | Value | Description | +| ------ | -------------- | --------------------------------------------------- | +| Array | 1 | Array, e.g. \["Bob", 23\] | +| Object | 0 | Object, e.g. {name: "Bob", age: 23} | diff --git a/docs/replace.sh b/docs/replace.sh new file mode 100755 index 0000000..d43417d --- /dev/null +++ b/docs/replace.sh @@ -0,0 +1,4 @@ +#!/bin/sh +cd docs/api +sed -i '' -- 's/\[Home\](.\/index\.md) > \[node-duckdb\]/[Node-DuckDB API]/g' * +sed -i '' -- 's/## node-duckdb package/## Node-DuckDB API/g' node-duckdb.md diff --git a/examples/src/stream-example.ts b/examples/src/stream-example.ts index 425291e..95e6904 100644 --- a/examples/src/stream-example.ts +++ b/examples/src/stream-example.ts @@ -1,6 +1,6 @@ import { Connection, DuckDB, RowResultFormat } from "node-duckdb"; import { createWriteStream } from "fs"; -import {Transform} from "stream"; +import { Transform } from "stream"; class ArrayToCsvTransform extends Transform { diff --git a/package.json b/package.json index 7213481..deceebd 100644 --- a/package.json +++ b/package.json @@ -11,13 +11,18 @@ "async", "stream" ], + "homepage": "https://github.com/deepcrawl/node-duckdb#readme", "repository": { "type": "git", - "url": "ssh://git@github.com/deepcrawl/node-duckdb.git", - "directory": "node-duckdb" + "url": "https://github.com/deepcrawl/node-duckdb.git" }, "license": "MIT", "author": "DeepCrawl", + "contributors": [ + "Dan Forsberg (https://github.com/dforsber)", + "Pieter Raubenheimer (https://github.com/jupiter)", + "Rostislav Provodenko (https://github.com/rostislavdeepcrawl)" + ], "main": "dist/index.js", "types": "dist/index.d.ts", "binary": { @@ -37,6 +42,7 @@ "download-duckdb": "rm -rf duckdb && curl -L https://github.com/cwida/duckdb/archive/v0.2.2.tar.gz > duckdb.tar.gz && tar xf duckdb.tar.gz && mv duckdb-0.2.2 duckdb && rm duckdb.tar.gz", "eslint:check": "eslint --ext .js,.json,.ts ./", "eslint:fix": "eslint --fix --ext .js,.json,.ts ./", + "generate-doc": "yarn build:ts && rm -rf temp etc && mkdir etc && yarn api-extractor run --local --verbose && yarn api-documenter markdown -i temp -o docs/api && ./docs/replace.sh", "install": "prebuild-install --verbose -d -r napi || (yarn download-duckdb && yarn build:duckdb && yarn prebuild:current-target)", "lint:check": "yarn prettier:check && yarn eslint:check && yarn clang:check", "lint:fix": "yarn prettier:fix && yarn eslint:fix && yarn clang:fix", @@ -51,12 +57,14 @@ "test": "yarn build:ts && jest --runInBand --testTimeout=60000" }, "dependencies": { + "@microsoft/api-extractor": "^7.12.0", "cmake-js": "^6.1.0", "node-addon-api": "^3.0.2", "prebuild-install": "^6.0.0", "rimraf": "^3.0.2" }, "devDependencies": { + "@microsoft/api-documenter": "^7.11.3", "@types/jest": "^26.0.14", "@typescript-eslint/eslint-plugin": "^4.3.0", "@zerollup/ts-transform-paths": "^1.7.18", diff --git a/src/addon-types/duckdb-config.ts b/src/addon-types/duckdb-config.ts index 6a4c880..08f3c7c 100644 --- a/src/addon-types/duckdb-config.ts +++ b/src/addon-types/duckdb-config.ts @@ -1,48 +1,116 @@ +/** + * Access mode specifier + * @public + */ export enum AccessMode { Undefined = 0, Automatic = 1, ReadOnly = 2, ReadWrite = 3, } - +/** + * Default sort order specifier + * @public + */ export enum OrderType { Invalid = 0, Default = 1, Ascending = 2, Descending = 3, } - +/** + * Null order specifier + * @public + */ export enum OrderByNullType { Invalid = 0, Default = 1, NullsFirst = 2, NullsLast = 3, } - +/** + * Result format specifier for rows + * @public + */ export enum RowResultFormat { + /** + * Object, e.g. \{name: "Bob", age: 23\} + */ Object = 0, + /** + * Array, e.g. ["Bob", 23] + */ Array = 1, } - +/** + * Options object type for the DuckDB class + * @public + */ export interface IDuckDBOptionsConfig { + /** + * Access Mode + */ accessMode?: AccessMode; + /** + * Checkpoint Write Ahead Log Size (in bytes) + */ checkPointWALSize?: number; + /** + * Whether to use Direct IO + */ useDirectIO?: boolean; + /** + * Maximum memory limit for the databse (in bytes) + */ maximumMemory?: number; + /** + * Whether to use temporary directory to store data that doesn't fit in memory + */ useTemporaryDirectory?: boolean; + /** + * Location of the temporary directory + */ temporaryDirectory?: string; + /** + * Collation + */ collation?: string; + /** + * Default Order + */ defaultOrderType?: OrderType; + /** + * Default order for Null values + */ defaultNullOrder?: OrderByNullType; + /** + * Enable Copy + */ enableCopy?: boolean; } - +/** + * Configuration object for DuckDB + * @public + */ export interface IDuckDBConfig { + /** + * Path to the database file. If undefined, in-memory database is created + */ path?: string; options?: IDuckDBOptionsConfig; } - +/** + * Options for connection.execute + * @public + */ export interface IExecuteOptions { + /** + * Materialized means that the whole result is loaded into memory, as opposed to streaming which means there is a pointer to the next row and rows are retrieved one by one. + * If falsy, DuckDB will *attempt* to not load the whole result set into memory at once. + */ forceMaterialized?: boolean; + /** + * Row format + */ rowResultFormat?: RowResultFormat; } diff --git a/src/addon-types/result-type.ts b/src/addon-types/result-type.ts index ec68db7..3c3ad25 100644 --- a/src/addon-types/result-type.ts +++ b/src/addon-types/result-type.ts @@ -1,4 +1,14 @@ +/** + * Specifier for how DuckDB attempts to load the result + * @public + */ export enum ResultType { + /** + * Load the whole result set into memory + */ Materialized = "Materialized", + /** + * Keep pointer to the first row, don't load the whole result set all at once + */ Streaming = "Streaming", } diff --git a/src/addon/connection.ts b/src/addon/connection.ts index 0fdc159..dcedd63 100644 --- a/src/addon/connection.ts +++ b/src/addon/connection.ts @@ -4,19 +4,120 @@ import {DuckDB} from "./duckdb"; import { ResultIterator } from "./result-iterator"; import { IExecuteOptions } from "@addon-types"; +/** + * 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: + * ``` + * 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. + * @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: + * ``` + * import { Connection, DuckDB, RowResultFormat } from "node-duckdb"; + * import { createWriteStream } from "fs"; + * import { Transform } from "stream"; + * class ArrayToCsvTransform extends Transform { + * constructor() { + * super({objectMode: true}) + * } + * _transform(chunk: any[], _encoding: string, callback: any) { + * this.push(chunk.join(",") + '\n'); + * callback(); + * } + * } + * + * async function outputToFileAsCsv() { + * const db = new DuckDB(); + * const connection = new Connection(db); + * await connection.execute("CREATE TABLE people(id INTEGER, name VARCHAR);"); + * await connection.execute("INSERT INTO people VALUES (1, 'Mark'), (2, 'Hannes'), (3, 'Bob');"); + * const resultStream = await connection.execute("SELECT * FROM people;", {rowResultFormat: RowResultFormat.Array}); + * const transformToCsvStream = new ArrayToCsvTransform(); + * const writeStream = createWriteStream("my-people-output"); + * resultStream.pipe(transformToCsvStream).pipe(writeStream); + * } + * outputToFileAsCsv(); + * ``` + */ public async execute(command: string, options?: IExecuteOptions): Promise> { const resultIteratorBinding = await this.connectionBinding.execute(command, options); return new ResultStream(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: + * ``` + * import { Connection, DuckDB, RowResultFormat } from "node-duckdb"; + * async function queryDatabaseWithIterator() { + * const db = new DuckDB(); + * const connection = new Connection(db); + * 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 + * console.log(result.fetchRow()); + * // print the rest of the rows + * console.log(result.fetchAllRows()); + * const result2 = await connection.executeIterator("SELECT * FROM people;", {rowResultFormat: RowResultFormat.Array}); + * console.log(result2.fetchAllRows()); + * connection.close(); + * db.close(); + * } + * queryDatabaseWithIterator(); + * ``` + * + * @example + * Providing generics type: + * ``` + * const result = await connection.executeIterator(`SELECT CAST(1 AS TINYINT)`, { + * rowResultFormat: RowResultFormat.Array, + * }); + * expect(result.fetchRow()).toMatchObject([1]); + * ``` + */ public async executeIterator(command: string, options?: IExecuteOptions): Promise> { return new ResultIterator(await this.connectionBinding.execute(command, options)); } + /** + * Close the connection (also closes all {@link ResultStream | ResultStream} 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()`. + */ public close(): void { return this.connectionBinding.close(); } + /** + * If the connection is closed returns true, otherwise false. + */ public get isClosed(): boolean { return this.connectionBinding.isClosed; } diff --git a/src/addon/duckdb.ts b/src/addon/duckdb.ts index b00aba6..8d74d73 100644 --- a/src/addon/duckdb.ts +++ b/src/addon/duckdb.ts @@ -1,44 +1,127 @@ import { IDuckDBConfig } from "@addon-types"; import { DuckDBBinding, DuckDBClass } from "../addon-bindings"; +import { AccessMode, OrderType, OrderByNullType } from "@addon-types"; +/** + * The DuckDB class represents a DuckDB database instance. + * @public + */ export class DuckDB { private duckdb: DuckDBClass; + /** + * Represents a native instance of DuckDB. + * @param config - optional configuration object of type {@link IDuckDBConfig | IDuckDBConfig}. + * + * + * @example + * Initializing a duckdb database in memory: + * ``` + * import { DuckDB } from "node-duckdb"; + * const db = new DuckDB(); + * ``` + * + * @example + * Initializing a duckdb database from file: + * ``` + * import { DuckDB } from "node-duckdb"; + * const db = new DuckDB({ path: join(__dirname, "./mydb") }); + * ``` + * + * @example + * Initializing a duckdb database from file and setting some additional options: + * ``` + * import { DuckDB, OrderType } from "node-duckdb"; + * const db = new DuckDB({ path: join(__dirname, "./mydb"), options: { defaultOrderType: OrderType.Descending, temporaryDirectory: false } }); + * ``` + * + * @public + */ constructor(config: IDuckDBConfig = {}) { this.duckdb = new DuckDBBinding(config); } + /** + * Closes the underlying duckdb database, frees associated memory and renders it unusuable. + * @remarks + * Even though GC will automatically destroy the Database 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()`. + * @public + */ public close(): void { return this.duckdb.close(); } + /** + * Returns underlying binding instance. + * @internal + */ public get db() { return this.duckdb; } + /** + * Returns true if the underlying database has been closed, false otherwise. + * @public + */ public get isClosed(): boolean { return this.duckdb.isClosed; } + /** + * Returns the {@link AccessMode | access mode} used by the database. + * @public + */ public get accessMode() { return this.duckdb.accessMode; } + /** + * Returns the checkpoint write ahead log size used by the database. + * @public + */ public get checkPointWALSize() { return this.duckdb.checkPointWALSize; } + /** + * Returns the maximum memory limit for the database. + * @public + */ public get maximumMemory() { return this.duckdb.maximumMemory; } + /** + * Returns true if the database uses a temporary directory for storing data that does not fit into memory, false otherwise. + * @public + */ public get useTemporaryDirectory() { return this.duckdb.useTemporaryDirectory; } + /** + * Returns the temporary directory location for the database. + * @public + */ public get temporaryDirectory() { return this.duckdb.temporaryDirectory; } + /** + * Returns the collation used by the database. + * @public + */ public get collation() { return this.duckdb.collation; } + /** + * Returns the default {@link OrderType | sort order}. + * @public + */ public get defaultOrderType() { return this.duckdb.defaultOrderType; } + /** + * Returns the default {@link OrderByNullType | sort order for null values}. + * @public + */ public get defaultNullOrder() { return this.duckdb.defaultNullOrder; } + /** + * Returns true of copying is enabled, false otherwise. + * @public + */ public get enableCopy() { return this.duckdb.enableCopy; } diff --git a/src/addon/result-iterator.ts b/src/addon/result-iterator.ts index b37865c..bb018cb 100644 --- a/src/addon/result-iterator.ts +++ b/src/addon/result-iterator.ts @@ -1,11 +1,32 @@ import { ResultType } from "@addon-types"; import { ResultIteratorClass } from "../addon-bindings"; +/** + * ResultIterator represents the result set of a DuckDB query. Instances of this class are returned by the {@link Connection.executeIterator | Connection.executeIterator}. + * + * @public + */ export class ResultIterator { + /** + * + * @internal + */ constructor(private resultInterator: ResultIteratorClass) {} + /** + * Fetch the next row + * + * @remarks + * First call returns the first row, when no more rows left `null` is returned. + */ public fetchRow(): T { return this.resultInterator.fetchRow(); } + /** + * Fetch all rows + * + * @remarks + * Note, this may produce a `heap out of bounds` error in case when there is too much data. Either use the {@link ResultIterator.fetchRow | fetchRow} or the {@link Connection.execute | Connection.execute} method when there is a lot of data. + */ public fetchAllRows(): T[] { const allRows: T[] = []; for (let element = this.fetchRow(); element !== null; element = this.fetchRow()) { @@ -13,15 +34,29 @@ export class ResultIterator { } return allRows; } + /** + * Describe the result set schema. + */ public describe(): string[][] { return this.resultInterator.describe(); } + /** + * Close the ResultIterator + * @remarks + * {@link Connection.close | Connection.close} automatically closes all associated ResultIterators. + */ public close(): void { return this.resultInterator.close(); } + /** + * Get the {@link ResultType | ResultType} of the ResultIterator. This is specified by the {@link IExecuteOptions.forceMaterialized | options} argument on {@link Connection.executeIterator | executeIterator}. + */ public get type(): ResultType { return this.resultInterator.type; } + /** + * Returns true if ResultIterator is closed, false otherwise. + */ public get isClosed(): boolean { return this.resultInterator.isClosed; } diff --git a/src/addon/result-stream.ts b/src/addon/result-stream.ts index a4e0e7e..41e6994 100644 --- a/src/addon/result-stream.ts +++ b/src/addon/result-stream.ts @@ -1,12 +1,21 @@ import { Readable } from "stream"; import { ResultIterator } from "./result-iterator"; - +/** + * This is a Readable stream that wrapps the ResultIterator. Instances of this class are returned by {@link Connection.execute | Connection.execute}. + * @public + */ export class ResultStream extends Readable { + /** + * @internal + */ constructor(private resultIterator: ResultIterator) { super({ objectMode: true }); } + /** + * @internal + */ public _read(): void { try { const element = this.resultIterator.fetchRow(); @@ -18,7 +27,10 @@ export class ResultStream extends Readable { this.destroy(e); } } - + /** + * + * @internal + */ public _destroy(error: Error | null, callback: (error?: Error | null) => void): void { this.close(); callback(error); diff --git a/src/index.ts b/src/index.ts index 45fe433..d0c5136 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,2 +1,43 @@ +/** + * Node-DuckDB is a thin wrapper on top of {@link https://duckdb.org/ | DuckDB}. + * + * Using it involves: + * + * 1. Creating a {@link node-duckdb#DuckDB | DuckDB} object + * + * 2. Creating a {@link node-duckdb#Connection | Connection} object to the DuckDB object + * + * 3. Calling {@link node-duckdb#Connection.execute | Connection.execute} or {@link node-duckdb#Connection.executeIterator | Connection.executeIterator} on the Connection object + * + * @packageDocumentation + * + * @example + * Do some simple querying and print the result + * ``` + * import { Connection, DuckDB } from "node-duckdb"; + * + * async function queryDatabaseWithIterator() { + * // create new database in memory + * const db = new DuckDB(); + * // create a new connection to the database + * const connection = new Connection(db); + * + * // perform some queries + * 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;"); + * + * // fetch and print result + * console.log(result.fetchAllRows()); + + * // release resources + * connection.close(); + * db.close(); + * } + * + * queryDatabaseWithIterator(); + * ``` + * For more examples see {@link https://github.com/deepcrawl/node-duckdb/tree/feature/ODIN-423-welcome-page/examples | here}. + */ export { DuckDB, Connection, ResultIterator, ResultStream } from "./addon"; -export { ResultType, RowResultFormat } from "./addon-types"; +export * from "./addon-types"; diff --git a/tsconfig.json b/tsconfig.json index a082b4c..e0a8cd6 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -19,7 +19,7 @@ "declaration": true, /* Generates corresponding '.d.ts' file. */ "declarationMap": true , /* Generates a sourcemap for each corresponding '.d.ts' file. */ "composite": false, /* Enable project compilation */ - "removeComments": true, /* Do not emit comments to output. */ + "removeComments": false, /* Do not emit comments to output. */ "importHelpers": false, /* Import emit helpers from 'tslib'. */ /* Strict Type-Checking Options */ @@ -33,7 +33,7 @@ "alwaysStrict": true, /* Parse in strict mode and emit "use strict" for each source file. */ /* Additional Checks */ - "noUnusedLocals": true, /* Report errors on unused locals. */ + "noUnusedLocals": false, /* Report errors on unused locals. */ "noUnusedParameters": true, /* Report errors on unused parameters. */ "noImplicitReturns": true, /* Report error when not all code paths in function return a value. */ "noFallthroughCasesInSwitch": true, /* Report errors for fallthrough cases in switch statement. */ diff --git a/yarn.lock b/yarn.lock index bedae48..601d494 100644 --- a/yarn.lock +++ b/yarn.lock @@ -527,6 +527,49 @@ "@types/yargs" "^15.0.0" chalk "^4.0.0" +"@microsoft/api-documenter@^7.11.3": + version "7.11.3" + resolved "https://registry.yarnpkg.com/@microsoft/api-documenter/-/api-documenter-7.11.3.tgz#35ac2eaac9ab5cd31ab53b858937863601bcbc7c" + integrity sha512-tXdd+zWqufKDbbocIgMRB1AyRj0HiAI+gTIvCyAtJX9KOGFYreTt2kFPzFssPBMeNycq58zXl0fXRr+vA7WnNA== + dependencies: + "@microsoft/api-extractor-model" "7.12.0" + "@microsoft/tsdoc" "0.12.19" + "@rushstack/node-core-library" "3.35.1" + "@rushstack/ts-command-line" "4.7.7" + colors "~1.2.1" + js-yaml "~3.13.1" + resolve "~1.17.0" + +"@microsoft/api-extractor-model@7.12.0": + version "7.12.0" + resolved "https://registry.yarnpkg.com/@microsoft/api-extractor-model/-/api-extractor-model-7.12.0.tgz#ad5589c166b31dad3c8669b46b050f8bc4056f1b" + integrity sha512-TxoAbL/lauS3k/brBWVsiQTnyHBwHrAGJhTuiD0tWS/eu4dLNULchcSQfcOaFS91OgDEz4lMMbClgChFuo+53Q== + dependencies: + "@microsoft/tsdoc" "0.12.19" + "@rushstack/node-core-library" "3.35.1" + +"@microsoft/api-extractor@^7.12.0": + version "7.12.0" + resolved "https://registry.yarnpkg.com/@microsoft/api-extractor/-/api-extractor-7.12.0.tgz#3ab602cebaa18d357afc67471abba484d8dc20d4" + integrity sha512-YDd7AUkIayPLooMasDyV4vle1TLUQhFp2v/tGdRU+WAVbnyVUDXXa20WEfbPEZ4QVlgN+77EX6f2K6GyKd713A== + dependencies: + "@microsoft/api-extractor-model" "7.12.0" + "@microsoft/tsdoc" "0.12.19" + "@rushstack/node-core-library" "3.35.1" + "@rushstack/rig-package" "0.2.8" + "@rushstack/ts-command-line" "4.7.7" + colors "~1.2.1" + lodash "~4.17.15" + resolve "~1.17.0" + semver "~7.3.0" + source-map "~0.6.1" + typescript "~4.0.5" + +"@microsoft/tsdoc@0.12.19": + version "0.12.19" + resolved "https://registry.yarnpkg.com/@microsoft/tsdoc/-/tsdoc-0.12.19.tgz#2173ccb92469aaf62031fa9499d21b16d07f9b57" + integrity sha512-IpgPxHrNxZiMNUSXqR1l/gePKPkfAmIKoDRP9hp7OwjU29ZR8WCJsOJ8iBKgw0Qk+pFwR+8Y1cy8ImLY6e9m4A== + "@nodelib/fs.scandir@2.1.3": version "2.1.3" resolved "https://registry.yarnpkg.com/@nodelib/fs.scandir/-/fs.scandir-2.1.3.tgz#3a582bdb53804c6ba6d146579c46e52130cf4a3b" @@ -548,6 +591,40 @@ "@nodelib/fs.scandir" "2.1.3" fastq "^1.6.0" +"@rushstack/node-core-library@3.35.1": + version "3.35.1" + resolved "https://registry.yarnpkg.com/@rushstack/node-core-library/-/node-core-library-3.35.1.tgz#f228f010c6ec139c2f363a49dde8faed9a7167fe" + integrity sha512-ZwnXp2loZyVUgrZ+fEKKF/EHl0ikcy6SCsd34ewYXoEAs0XWIy2VS9bemrfaFtd2VzJ/G/ZbP3xHkqRnUPKJ4Q== + dependencies: + "@types/node" "10.17.13" + colors "~1.2.1" + fs-extra "~7.0.1" + import-lazy "~4.0.0" + jju "~1.4.0" + resolve "~1.17.0" + semver "~7.3.0" + timsort "~0.3.0" + z-schema "~3.18.3" + +"@rushstack/rig-package@0.2.8": + version "0.2.8" + resolved "https://registry.yarnpkg.com/@rushstack/rig-package/-/rig-package-0.2.8.tgz#9ac26f56b3917bfa36f91bfe037e2c3a53977a6c" + integrity sha512-Ltjeg1a5Sx7XTW9oBxmcfhHseBLnH7I/8d6tAtjx5s0r7F6WmNVJdxVmt86qNfXcFRsiGNrzLqjMwlcX3GyldQ== + dependencies: + "@types/node" "10.17.13" + resolve "~1.17.0" + strip-json-comments "~3.1.1" + +"@rushstack/ts-command-line@4.7.7": + version "4.7.7" + resolved "https://registry.yarnpkg.com/@rushstack/ts-command-line/-/ts-command-line-4.7.7.tgz#3a983de1895a931e879ecdc8037251af00c4e78b" + integrity sha512-COSDys0WTVCORKam2hsTL32As4fHAf1RqC6FKS98hgR0Z90nh1JX8fGNkvSdxaZ6dOuNTJj3txh+SpWoHJoZJA== + dependencies: + "@types/argparse" "1.0.38" + argparse "~1.0.9" + colors "~1.2.1" + string-argv "~0.3.1" + "@sindresorhus/is@^0.14.0": version "0.14.0" resolved "https://registry.yarnpkg.com/@sindresorhus/is/-/is-0.14.0.tgz#9fb3a3cf3132328151f353de4632e01e52102bea" @@ -574,6 +651,11 @@ dependencies: defer-to-connect "^1.0.1" +"@types/argparse@1.0.38": + version "1.0.38" + resolved "https://registry.yarnpkg.com/@types/argparse/-/argparse-1.0.38.tgz#a81fd8606d481f873a3800c6ebae4f1d768a56a9" + integrity sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA== + "@types/babel__core@^7.0.0", "@types/babel__core@^7.1.7": version "7.1.9" resolved "https://registry.yarnpkg.com/@types/babel__core/-/babel__core-7.1.9.tgz#77e59d438522a6fb898fa43dc3455c6e72f3963d" @@ -675,6 +757,11 @@ resolved "https://registry.yarnpkg.com/@types/node/-/node-14.0.27.tgz#a151873af5a5e851b51b3b065c9e63390a9e0eb1" integrity sha512-kVrqXhbclHNHGu9ztnAwSncIgJv/FaxmzXJvGXNdcCpV1b8u1/Mi6z6m0vwy0LzKeXFTPLH0NzwmoJ3fNCIq0g== +"@types/node@10.17.13": + version "10.17.13" + resolved "https://registry.yarnpkg.com/@types/node/-/node-10.17.13.tgz#ccebcdb990bd6139cd16e84c39dc2fb1023ca90c" + integrity sha512-pMCcqU2zT4TjqYFrWtYHKal7Sl30Ims6ulZ4UFXxI4xbtQqK/qqKwkDoBFCfooRqqmRu9vY3xaJRwxSh673aYg== + "@types/normalize-package-data@^2.4.0": version "2.4.0" resolved "https://registry.yarnpkg.com/@types/normalize-package-data/-/normalize-package-data-2.4.0.tgz#e486d0d97396d79beedd0a6e33f4534ff6b4973e" @@ -1010,7 +1097,7 @@ are-we-there-yet@~1.1.2: delegates "^1.0.0" readable-stream "^2.0.6" -argparse@^1.0.7: +argparse@^1.0.7, argparse@~1.0.9: version "1.0.10" resolved "https://registry.yarnpkg.com/argparse/-/argparse-1.0.10.tgz#bcd6791ea5ae09725e17e5ad988134cd40b3d911" integrity sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg== @@ -1607,6 +1694,11 @@ color-name@~1.1.4: resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2" integrity sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA== +colors@~1.2.1: + version "1.2.5" + resolved "https://registry.yarnpkg.com/colors/-/colors-1.2.5.tgz#89c7ad9a374bc030df8013241f68136ed8835afc" + integrity sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg== + combined-stream@^1.0.6, combined-stream@~1.0.6: version "1.0.8" resolved "https://registry.yarnpkg.com/combined-stream/-/combined-stream-1.0.8.tgz#c3d45a8b34fd730631a110a8a2520682b31d5a7f" @@ -1621,7 +1713,7 @@ commander@2.9.x: dependencies: graceful-readlink ">= 1.0.0" -commander@^2.9.0: +commander@^2.7.1, commander@^2.9.0: version "2.20.3" resolved "https://registry.yarnpkg.com/commander/-/commander-2.20.3.tgz#fd485e84c03eb4881c20722ba48035e8531aeb33" integrity sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ== @@ -2625,6 +2717,15 @@ fs-extra@^5.0.0: jsonfile "^4.0.0" universalify "^0.1.0" +fs-extra@~7.0.1: + version "7.0.1" + resolved "https://registry.yarnpkg.com/fs-extra/-/fs-extra-7.0.1.tgz#4f189c44aa123b895f722804f55ea23eadc348e9" + integrity sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw== + dependencies: + graceful-fs "^4.1.2" + jsonfile "^4.0.0" + universalify "^0.1.0" + fs-minipass@^1.2.5: version "1.2.7" resolved "https://registry.yarnpkg.com/fs-minipass/-/fs-minipass-1.2.7.tgz#ccff8570841e7fe4265693da88936c55aed7f7c7" @@ -3038,6 +3139,11 @@ import-lazy@^2.1.0: resolved "https://registry.yarnpkg.com/import-lazy/-/import-lazy-2.1.0.tgz#05698e3d45c88e8d7e9d92cb0584e77f096f3e43" integrity sha1-BWmOPUXIjo1+nZLLBYTnfwlvPkM= +import-lazy@~4.0.0: + version "4.0.0" + resolved "https://registry.yarnpkg.com/import-lazy/-/import-lazy-4.0.0.tgz#e8eb627483a0a43da3c03f3e35548be5cb0cc153" + integrity sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw== + import-local@^3.0.2: version "3.0.2" resolved "https://registry.yarnpkg.com/import-local/-/import-local-3.0.2.tgz#a8cfd0431d1de4a2199703d003e3e62364fa6db6" @@ -3862,6 +3968,11 @@ jest@^26.2.2: import-local "^3.0.2" jest-cli "^26.2.2" +jju@~1.4.0: + version "1.4.0" + resolved "https://registry.yarnpkg.com/jju/-/jju-1.4.0.tgz#a3abe2718af241a2b2904f84a625970f389ae32a" + integrity sha1-o6vicYryQaKykE+EpiWXDzia4yo= + js-tokens@^4.0.0: version "4.0.0" resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499" @@ -3875,6 +3986,14 @@ js-yaml@^3.13.1: argparse "^1.0.7" esprima "^4.0.0" +js-yaml@~3.13.1: + version "3.13.1" + resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.13.1.tgz#aff151b30bfdfa8e49e05da22e7415e9dfa37847" + integrity sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw== + dependencies: + argparse "^1.0.7" + esprima "^4.0.0" + jsbn@~0.1.0: version "0.1.1" resolved "https://registry.yarnpkg.com/jsbn/-/jsbn-0.1.1.tgz#a5e654c2e5a2deb5f201d96cefbca80c0ef2f513" @@ -4116,6 +4235,16 @@ lodash.camelcase@4.3.0: resolved "https://registry.yarnpkg.com/lodash.camelcase/-/lodash.camelcase-4.3.0.tgz#b28aa6288a2b9fc651035c7711f65ab6190331a6" integrity sha1-soqmKIorn8ZRA1x3EfZathkDMaY= +lodash.get@^4.0.0: + version "4.4.2" + resolved "https://registry.yarnpkg.com/lodash.get/-/lodash.get-4.4.2.tgz#2d177f652fa31e939b4438d5341499dfa3825e99" + integrity sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk= + +lodash.isequal@^4.0.0: + version "4.5.0" + resolved "https://registry.yarnpkg.com/lodash.isequal/-/lodash.isequal-4.5.0.tgz#415c4478f2bcc30120c22ce10ed3226f7d3e18e0" + integrity sha1-QVxEePK8wwEgwizhDtMib30+GOA= + lodash.kebabcase@4.1.1: version "4.1.1" resolved "https://registry.yarnpkg.com/lodash.kebabcase/-/lodash.kebabcase-4.1.1.tgz#8489b1cb0d29ff88195cceca448ff6d6cc295c36" @@ -4156,7 +4285,7 @@ lodash.upperfirst@4.3.1: resolved "https://registry.yarnpkg.com/lodash.upperfirst/-/lodash.upperfirst-4.3.1.tgz#1365edf431480481ef0d1c68957a5ed99d49f7ce" integrity sha1-E2Xt9DFIBIHvDRxolXpe2Z1J984= -lodash@^4, lodash@^4.17.14, lodash@^4.17.15: +lodash@^4, lodash@^4.17.14, lodash@^4.17.15, lodash@~4.17.15: version "4.17.20" resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.20.tgz#b44a9b6297bcb698f1c51a3545a2b3b368d59c52" integrity sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA== @@ -4176,6 +4305,13 @@ lowercase-keys@^2.0.0: resolved "https://registry.yarnpkg.com/lowercase-keys/-/lowercase-keys-2.0.0.tgz#2603e78b7b4b0006cbca2fbcc8a3202558ac9479" integrity sha512-tqNXrS78oMOE73NMxK4EMLQsQowWf8jKooH9g7xPavRT706R6bkQJ6DY2Te7QukaZsulxa30wQ7bk0pm4XiHmA== +lru-cache@^6.0.0: + version "6.0.0" + resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-6.0.0.tgz#6d6fe6570ebd96aaf90fcad1dafa3b2566db3a94" + integrity sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA== + dependencies: + yallist "^4.0.0" + make-dir@^3.0.0: version "3.1.0" resolved "https://registry.yarnpkg.com/make-dir/-/make-dir-3.1.0.tgz#415e967046b3a7f1d185277d84aa58203726a13f" @@ -5331,7 +5467,7 @@ resolve@^1.1.6: is-core-module "^2.1.0" path-parse "^1.0.6" -resolve@^1.10.0, resolve@^1.10.1, resolve@^1.13.1, resolve@^1.17.0, resolve@^1.3.2: +resolve@^1.10.0, resolve@^1.10.1, resolve@^1.13.1, resolve@^1.17.0, resolve@^1.3.2, resolve@~1.17.0: version "1.17.0" resolved "https://registry.yarnpkg.com/resolve/-/resolve-1.17.0.tgz#b25941b54968231cc2d1bb76a79cb7f2c0bf8444" integrity sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w== @@ -5472,6 +5608,13 @@ semver@~5.3.0: resolved "https://registry.yarnpkg.com/semver/-/semver-5.3.0.tgz#9b2ce5d3de02d17c6012ad326aa6b4d0cf54f94f" integrity sha1-myzl094C0XxgEq0yaqa00M9U+U8= +semver@~7.3.0: + version "7.3.4" + resolved "https://registry.yarnpkg.com/semver/-/semver-7.3.4.tgz#27aaa7d2e4ca76452f98d3add093a72c943edc97" + integrity sha512-tCfb2WLjqFAtXn4KEdxIhalnRtoKFN7nAwj0B3ZXCbQloV2tq5eDbcTmT68JJD3nRJq24/XgxtQKFIpQdtvmVw== + dependencies: + lru-cache "^6.0.0" + set-blocking@^2.0.0, set-blocking@~2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/set-blocking/-/set-blocking-2.0.0.tgz#045f9782d011ae9a6803ddd382b24392b3d890f7" @@ -5752,6 +5895,11 @@ stealthy-require@^1.1.1: resolved "https://registry.yarnpkg.com/stealthy-require/-/stealthy-require-1.1.1.tgz#35b09875b4ff49f26a777e509b3090a3226bf24b" integrity sha1-NbCYdbT/SfJqd35QmzCQoyJr8ks= +string-argv@~0.3.1: + version "0.3.1" + resolved "https://registry.yarnpkg.com/string-argv/-/string-argv-0.3.1.tgz#95e2fbec0427ae19184935f816d74aaa4c5c19da" + integrity sha512-a1uQGz7IyVy9YwhqjZIZu1c8JO8dNIe20xBmSS6qu9kv++k3JGzCVmprbNN5Kn+BgzD5E7YYwg1CcjuJMRNsvg== + string-length@^4.0.1: version "4.0.1" resolved "https://registry.yarnpkg.com/string-length/-/string-length-4.0.1.tgz#4a973bf31ef77c4edbceadd6af2611996985f8a1" @@ -5878,7 +6026,7 @@ strip-final-newline@^2.0.0: resolved "https://registry.yarnpkg.com/strip-final-newline/-/strip-final-newline-2.0.0.tgz#89b852fb2fcbe936f6f4b3187afb0a12c1ab58ad" integrity sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA== -strip-json-comments@^3.1.0, strip-json-comments@^3.1.1: +strip-json-comments@^3.1.0, strip-json-comments@^3.1.1, strip-json-comments@~3.1.1: version "3.1.1" resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-3.1.1.tgz#31f1281b3832630434831c310c01cccda8cbe006" integrity sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig== @@ -6008,6 +6156,11 @@ through2@~0.6.3: readable-stream ">=1.0.33-1 <1.1.0-0" xtend ">=4.0.0 <4.1.0-0" +timsort@~0.3.0: + version "0.3.0" + resolved "https://registry.yarnpkg.com/timsort/-/timsort-0.3.0.tgz#405411a8e7e6339fe64db9a234de11dc31e02bd4" + integrity sha1-QFQRqOfmM5/mTbmiNN4R3DHgK9Q= + tmpl@1.0.x: version "1.0.4" resolved "https://registry.yarnpkg.com/tmpl/-/tmpl-1.0.4.tgz#23640dd7b42d00433911140820e5cf440e521dd1" @@ -6199,6 +6352,11 @@ typescript@^4.0.3: resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.0.3.tgz#153bbd468ef07725c1df9c77e8b453f8d36abba5" integrity sha512-tEu6DGxGgRJPb/mVPIZ48e69xCn2yRmCgYmDugAVwmJ6o+0u1RI18eO7E7WBTLYLaEVVOhwQmcdhQHweux/WPg== +typescript@~4.0.5: + version "4.0.5" + resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.0.5.tgz#ae9dddfd1069f1cb5beb3ef3b2170dd7c1332389" + integrity sha512-ywmr/VrTVCmNTJ6iV2LwIrfG1P+lv6luD8sUJs+2eI9NLGigaN+nUQc13iHqisq7bra9lnmUSYqbJvegraBOPQ== + undefsafe@^2.0.2: version "2.0.3" resolved "https://registry.yarnpkg.com/undefsafe/-/undefsafe-2.0.3.tgz#6b166e7094ad46313b2202da7ecc2cd7cc6e7aae" @@ -6346,6 +6504,11 @@ validate-npm-package-license@^3.0.1: spdx-correct "^3.0.0" spdx-expression-parse "^3.0.0" +validator@^8.0.0: + version "8.2.0" + resolved "https://registry.yarnpkg.com/validator/-/validator-8.2.0.tgz#3c1237290e37092355344fef78c231249dab77b9" + integrity sha512-Yw5wW34fSv5spzTXNkokD6S6/Oq92d8q/t14TqsS3fAiA1RYnxSFSIZ+CY3n6PGGRCq5HhJTSepQvFUS2QUDxA== + verror@1.10.0: version "1.10.0" resolved "https://registry.yarnpkg.com/verror/-/verror-1.10.0.tgz#3a105ca17053af55d6e270c1f8288682e18da400" @@ -6534,6 +6697,11 @@ yallist@^3.0.0, yallist@^3.0.3: resolved "https://registry.yarnpkg.com/yallist/-/yallist-3.1.1.tgz#dbb7daf9bfd8bac9ab45ebf602b8cbad0d5d08fd" integrity sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g== +yallist@^4.0.0: + version "4.0.0" + resolved "https://registry.yarnpkg.com/yallist/-/yallist-4.0.0.tgz#9bb92790d9c0effec63be73519e11a35019a3a72" + integrity sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A== + yargs-parser@^18.1.2: version "18.1.3" resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-18.1.3.tgz#be68c4975c6b2abf469236b0c870362fab09a7b0" @@ -6571,3 +6739,14 @@ yargs@^3.6.0: string-width "^1.0.1" window-size "^0.1.4" y18n "^3.2.0" + +z-schema@~3.18.3: + version "3.18.4" + resolved "https://registry.yarnpkg.com/z-schema/-/z-schema-3.18.4.tgz#ea8132b279533ee60be2485a02f7e3e42541a9a2" + integrity sha512-DUOKC/IhbkdLKKiV89gw9DUauTV8U/8yJl1sjf6MtDmzevLKOF2duNJ495S3MFVjqZarr+qNGCPbkg4mu4PpLw== + dependencies: + lodash.get "^4.0.0" + lodash.isequal "^4.0.0" + validator "^8.0.0" + optionalDependencies: + commander "^2.7.1"