@duckdb/node-api 1.2.1-alpha.16 → 1.2.2-alpha.18

package/README.md

@@ -4,30 +4,33 @@ An API for using [DuckDB](https://duckdb.org/) in [Node](https://nodejs.org/).
 
 This is a high-level API meant for applications.
 It depends on low-level bindings that adhere closely to [DuckDB's C API](https://duckdb.org/docs/api/c/overview),
-available separately as [@duckdb/duckdb-bindings](https://www.npmjs.com/package/@duckdb/node-bindings).
+available separately as [@duckdb/node-bindings](https://www.npmjs.com/package/@duckdb/node-bindings).
 
 ## Features
 
-### Main differences from [duckdb-node](https://www.npmjs.com/package/duckdb)
-- Native support for Promises; no need for separate [duckdb-async](https://www.npmjs.com/package/duckdb-async) wrapper.
-- DuckDB-specific API; not based on the [SQLite Node API](https://www.npmjs.com/package/sqlite3).
-- Lossless & efficent support for values of all [DuckDB data types](https://duckdb.org/docs/sql/data_types/overview).
-- Wraps [released DuckDB binaries](https://github.com/duckdb/duckdb/releases) instead of rebuilding DuckDB.
-- Built on [DuckDB's C API](https://duckdb.org/docs/api/c/overview); exposes more functionality.
+### Main Differences from [duckdb-node](https://www.npmjs.com/package/duckdb)
+* Native support for Promises; no need for separate [duckdb-async](https://www.npmjs.com/package/duckdb-async) wrapper.
+* DuckDB-specific API; not based on the [SQLite Node API](https://www.npmjs.com/package/sqlite3).
+* Lossless & efficent support for values of all [DuckDB data types](https://duckdb.org/docs/sql/data_types/overview).
+* Wraps [released DuckDB binaries](https://github.com/duckdb/duckdb/releases) instead of rebuilding DuckDB.
+* Built on [DuckDB's C API](https://duckdb.org/docs/api/c/overview); exposes more functionality.
 
 ### Roadmap
 
 Some features are not yet complete:
-- Binding and appending the MAP and UNION data types
-- Appending default values row-by-row
-- User-defined types & functions
-- Profiling info
-- Table description
-- APIs for Arrow
+* Binding and appending the MAP and UNION data types
+* Appending default values row-by-row
+* User-defined types & functions
+* Profiling info
+* Table description
+* APIs for Arrow
+
+See the [issues list on GitHub](https://github.com/duckdb/duckdb-node-neo/issues)
+for the most up-to-date roadmap.
 
 ### Supported Platforms
 
-- Linux arm64 (experimental)
+- Linux arm64
 - Linux x64
 - Mac OS X (Darwin) arm64 (Apple Silicon)
 - Mac OS X (Darwin) x64 (Intel)
@@ -45,6 +48,17 @@ console.log(duckdb.version());
 console.log(duckdb.configurationOptionDescriptions());
 ```
 
+### Connect
+
+```ts
+import { DuckDBConnection } from '@duckdb/node-api';
+
+const connection = await DuckDBConnection.create();
+```
+
+This uses the default instance.
+For advanced usage, you can create instances explicitly.
+
 ### Create Instance
 
 ```ts
@@ -66,14 +80,33 @@ Read from and write to a database file, which is created if needed:
 const instance = await DuckDBInstance.create('my_duckdb.db');
 ```
 
-Set configuration options:
+Set [configuration options](https://duckdb.org/docs/stable/configuration/overview.html#configuration-reference):
 ```ts
 const instance = await DuckDBInstance.create('my_duckdb.db', {
   threads: '4'
 });
 ```
 
-### Connect
+### Instance Cache
+
+Multiple instances in the same process should not
+attach the same database.
+
+To prevent this, an instance cache can be used:
+```ts
+const instance = await DuckDBInstance.fromCache('my_duckdb.db');
+```
+
+This uses the default instance cache. For advanced usage, you can create
+instance caches explicitly:
+```ts
+import { DuckDBInstanceCache } from '@duckdb/node-api';
+
+const cache = new DuckDBInstanceCache();
+const instance = await cache.getOrCreateInstance('my_duckdb.db');
+```
+
+### Connect to Instance
 
 ```ts
 const connection = await instance.connect();
@@ -85,13 +118,13 @@ Connections will be disconnected automatically soon after their reference
 is dropped, but you can also disconnect explicitly if and when you want:
 
 ```ts
-connection.disconnect();
+connection.disconnectSync();
 ```
 
 or, equivalently:
 
 ```ts
-connection.close();
+connection.closeSync();
 ```
 
 ### Run SQL
@@ -150,6 +183,36 @@ const result = await connection.run('select $a, $b, $c', {
 });
 ```
 
+### Specifying Values
+
+Values of many data types are represented using one of the JS primitives
+`boolean`, `number`, `bigint`, or `string`.
+Also, any type can have `null` values.
+
+Values of some data types need to be constructed using special functions.
+These are:
+
+| Type | Function |
+| ---- | -------- |
+| `ARRAY` | `arrayValue` |
+| `BIT` | `bitValue` |
+| `BLOB` | `blobValue` |
+| `DATE` | `dateValue` |
+| `DECIMAL` | `decimalValue` |
+| `INTERVAL` | `intervalValue` |
+| `LIST` | `listValue` |
+| `MAP` | `mapValue` |
+| `STRUCT` | `structValue` |
+| `TIME` | `timeValue` |
+| `TIMETZ` | `timeTZValue` |
+| `TIMESTAMP` | `timestampValue` |
+| `TIMESTAMPTZ` | `timestampTZValue` |
+| `TIMESTAMP_S` | `timestampSecondsValue` |
+| `TIMESTAMP_MS` | `timestampMillisValue` |
+| `TIMESTAMP_NS` | `timestampNanosValue` |
+| `UNION` | `unionValue` |
+| `UUID` | `uuidValue` |
+
 ### Stream Results
 
 Streaming results evaluate lazily when rows are read.
@@ -221,13 +284,21 @@ const columnsObject = reader.getColumnsObject();
 // { i: [0, 1, 2], n: [10, 11, 12] }
 ```
 
-### Convert Result Data to JSON
+### Convert Result Data
+
+By default, data values that cannot be represented as JS built-ins
+are returned as specialized JS objects; see `Inspect Data Values` below.
 
-By default, data values that cannot be represented as JS primitives
-are returned as rich JS objects; see `Inspect Data Values` below.
+To retrieve data in a different form, such as JS built-ins or values that
+can be losslessly serialized to JSON, use the `JS` or `Json` forms of the
+above result data methods.
 
-To retrieve data in a form that can be losslessly serialized to JSON,
-use the `Json` forms of the above result data methods:
+Custom converters can be supplied as well. See the implementations of
+[JSDuckDBValueConverter](https://github.com/duckdb/duckdb-node-neo/blob/main/api/src/JSDuckDBValueConverter.ts)
+and [JsonDuckDBValueConverters](https://github.com/duckdb/duckdb-node-neo/blob/main/api/src/JsonDuckDBValueConverter.ts)
+for how to do this.
+
+Examples (using the `Json` forms):
 
 ```ts
 const reader = await connection.runAndReadAll(
@@ -375,6 +446,127 @@ const columnsObject = reader.getColumnsObjectJson();
 // }
 ```
 
+Column names and types can also be serialized to JSON:
+```ts
+const columnNamesAndTypes = reader.columnNamesAndTypesJson();
+// {
+//   "columnNames": [
+//     "int_array",
+//     "struct",
+//     "map",
+//     "union"
+//   ],
+//   "columnTypes": [
+//     {
+//       "typeId": 24,
+//       "valueType": {
+//         "typeId": 4
+//       }
+//     },
+//     {
+//       "typeId": 25,
+//       "entryNames": [
+//         "a",
+//         "b"
+//       ],
+//       "entryTypes": [
+//         {
+//           "typeId": 4
+//         },
+//         {
+//           "typeId": 17
+//         }
+//       ]
+//     },
+//     {
+//       "typeId": 26,
+//       "keyType": {
+//         "typeId": 17
+//       },
+//       "valueType": {
+//         "typeId": 17
+//       }
+//     },
+//     {
+//       "typeId": 28,
+//       "memberTags": [
+//         "name",
+//         "age"
+//       ],
+//       "memberTypes": [
+//         {
+//           "typeId": 17
+//         },
+//         {
+//           "typeId": 3
+//         }
+//       ]
+//     }
+//   ]
+// }
+
+const columnNameAndTypeObjects = reader.columnNameAndTypeObjectsJson();
+// [
+//   {
+//     "columnName": "int_array",
+//     "columnType": {
+//       "typeId": 24,
+//       "valueType": {
+//         "typeId": 4
+//       }
+//     }
+//   },
+//   {
+//     "columnName": "struct",
+//     "columnType": {
+//       "typeId": 25,
+//       "entryNames": [
+//         "a",
+//         "b"
+//       ],
+//       "entryTypes": [
+//         {
+//           "typeId": 4
+//         },
+//         {
+//           "typeId": 17
+//         }
+//       ]
+//     }
+//   },
+//   {
+//     "columnName": "map",
+//     "columnType": {
+//       "typeId": 26,
+//       "keyType": {
+//         "typeId": 17
+//       },
+//       "valueType": {
+//         "typeId": 17
+//       }
+//     }
+//   },
+//   {
+//     "columnName": "union",
+//     "columnType": {
+//       "typeId": 28,
+//       "memberTags": [
+//         "name",
+//         "age"
+//       ],
+//       "memberTypes": [
+//         {
+//           "typeId": 17
+//         },
+//         {
+//           "typeId": 3
+//         }
+//       ]
+//     }
+//   }
+// ]
+```
+
 ### Fetch Chunks
 
 Fetch all chunks:
@@ -409,11 +601,12 @@ Get chunk data:
 ```ts
 const rows = chunk.getRows();
 
-const rowObjects = chunk.getRowObjects();
+const rowObjects = chunk.getRowObjects(result.deduplicatedColumnNames());
 
 const columns = chunk.getColumns();
 
-const columnsObject = chunk.getColumnsObject();
+const columnsObject =
+  chunk.getColumnsObject(result.deduplicatedColumnNames());
 ```
 
 Get chunk data (one value at a time)
@@ -654,13 +847,13 @@ appender.appendInteger(123);
 appender.appendVarchar('mallard');
 appender.endRow();
 
-appender.flush();
+appender.flushSync();
 
 appender.appendInteger(17);
 appender.appendVarchar('goose');
 appender.endRow();
 
-appender.close(); // also flushes
+appender.closeSync(); // also flushes
 ```
 
 ### Append Data Chunk
@@ -685,9 +878,11 @@ chunk.setColumns([
 // ]);
 
 appender.appendDataChunk(chunk);
-appender.flush();
+appender.flushSync();
 ```
 
+See "Specifying Values" above for how to supply values to the appender.
+
 ### Extract Statements
 
 ```ts

package/lib/DuckDBAppender.d.ts

@@ -5,8 +5,8 @@ import { DuckDBArrayValue, DuckDBBitValue, DuckDBDateValue, DuckDBDecimalValue,
 export declare class DuckDBAppender {
     private readonly appender;
     constructor(appender: duckdb.Appender);
-    close(): void;
-    flush(): void;
+    closeSync(): void;
+    flushSync(): void;
     get columnCount(): number;
     columnType(columnIndex: number): DuckDBType;
     endRow(): void;

package/lib/DuckDBAppender.js

@@ -13,11 +13,11 @@ class DuckDBAppender {
     constructor(appender) {
         this.appender = appender;
     }
-    close() {
-        node_bindings_1.default.appender_close(this.appender);
+    closeSync() {
+        node_bindings_1.default.appender_close_sync(this.appender);
     }
-    flush() {
-        node_bindings_1.default.appender_flush(this.appender);
+    flushSync() {
+        node_bindings_1.default.appender_flush_sync(this.appender);
     }
     get columnCount() {
         return node_bindings_1.default.appender_column_count(this.appender);

package/lib/DuckDBConnection.d.ts

@@ -12,10 +12,10 @@ import { DuckDBValue } from './values';
 export declare class DuckDBConnection {
     private readonly connection;
     constructor(connection: duckdb.Connection);
-    static create(instance: DuckDBInstance): Promise<DuckDBConnection>;
-    /** Same as disconnect. */
-    close(): void;
-    disconnect(): void;
+    static create(instance?: DuckDBInstance): Promise<DuckDBConnection>;
+    /** Same as disconnectSync. */
+    closeSync(): void;
+    disconnectSync(): void;
     interrupt(): void;
     get progress(): duckdb.QueryProgress;
     run(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBMaterializedResult>;

package/lib/DuckDBConnection.js

@@ -7,6 +7,7 @@ exports.DuckDBConnection = void 0;
 const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
 const DuckDBAppender_1 = require("./DuckDBAppender");
 const DuckDBExtractedStatements_1 = require("./DuckDBExtractedStatements");
+const DuckDBInstance_1 = require("./DuckDBInstance");
 const DuckDBMaterializedResult_1 = require("./DuckDBMaterializedResult");
 const DuckDBPreparedStatement_1 = require("./DuckDBPreparedStatement");
 const DuckDBResultReader_1 = require("./DuckDBResultReader");
@@ -16,14 +17,17 @@ class DuckDBConnection {
         this.connection = connection;
     }
     static async create(instance) {
-        return instance.connect();
+        if (instance) {
+            return instance.connect();
+        }
+        return (await DuckDBInstance_1.DuckDBInstance.fromCache()).connect();
     }
-    /** Same as disconnect. */
-    close() {
-        return this.disconnect();
+    /** Same as disconnectSync. */
+    closeSync() {
+        return this.disconnectSync();
     }
-    disconnect() {
-        return node_bindings_1.default.disconnect(this.connection);
+    disconnectSync() {
+        return node_bindings_1.default.disconnect_sync(this.connection);
     }
     interrupt() {
         node_bindings_1.default.interrupt(this.connection);

package/lib/DuckDBDataChunk.d.ts

@@ -14,20 +14,28 @@ export declare class DuckDBDataChunk {
     set rowCount(count: number);
     getColumnVector(columnIndex: number): DuckDBVector;
     visitColumnValues(columnIndex: number, visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
+    appendColumnValues(columnIndex: number, values: DuckDBValue[]): void;
     getColumnValues(columnIndex: number): DuckDBValue[];
-    convertColumnValues<T>(columnIndex: number, converter: DuckDBValueConverter<T>): T[];
+    convertColumnValues<T>(columnIndex: number, converter: DuckDBValueConverter<T>): (T | null)[];
     setColumnValues(columnIndex: number, values: readonly DuckDBValue[]): void;
     visitColumns(visitColumn: (column: DuckDBValue[], columnIndex: number, type: DuckDBType) => void): void;
+    appendToColumns(columns: (DuckDBValue[] | undefined)[]): void;
     getColumns(): DuckDBValue[][];
-    convertColumns<T>(converter: DuckDBValueConverter<T>): T[][];
+    convertColumns<T>(converter: DuckDBValueConverter<T>): (T | null)[][];
     setColumns(columns: readonly (readonly DuckDBValue[])[]): void;
+    appendToColumnsObject(columnNames: readonly string[], columnsObject: Record<string, DuckDBValue[] | undefined>): void;
+    getColumnsObject(columnNames: readonly string[]): Record<string, DuckDBValue[]>;
     visitColumnMajor(visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
     visitRowValues(rowIndex: number, visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
+    appendRowValues(rowIndex: number, values: DuckDBValue[]): void;
     getRowValues(rowIndex: number): DuckDBValue[];
-    convertRowValues<T>(rowIndex: number, converter: DuckDBValueConverter<T>): T[];
+    convertRowValues<T>(rowIndex: number, converter: DuckDBValueConverter<T>): (T | null)[];
     visitRows(visitRow: (row: DuckDBValue[], rowIndex: number) => void): void;
+    appendToRows(rows: DuckDBValue[][]): void;
     getRows(): DuckDBValue[][];
-    convertRows<T>(converter: DuckDBValueConverter<T>): T[][];
+    convertRows<T>(converter: DuckDBValueConverter<T>): (T | null)[][];
     setRows(rows: readonly (readonly DuckDBValue[])[]): void;
+    appendToRowObjects(columnNames: readonly string[], rowObjects: Record<string, DuckDBValue>[]): void;
+    getRowObjects(columnNames: readonly string[]): Record<string, DuckDBValue>[];
     visitRowMajor(visitValue: (value: DuckDBValue, rowIndex: number, columnIndex: number, type: DuckDBType) => void): void;
 }

package/lib/DuckDBDataChunk.js

@@ -46,15 +46,17 @@ class DuckDBDataChunk {
             visitValue(vector.getItem(rowIndex), rowIndex, columnIndex, type);
         }
     }
+    appendColumnValues(columnIndex, values) {
+        this.visitColumnValues(columnIndex, (value) => values.push(value));
+    }
     getColumnValues(columnIndex) {
         const values = [];
-        this.visitColumnValues(columnIndex, (value) => values.push(value));
+        this.appendColumnValues(columnIndex, values);
         return values;
     }
     convertColumnValues(columnIndex, converter) {
         const convertedValues = [];
-        const type = this.getColumnVector(columnIndex).type;
-        this.visitColumnValues(columnIndex, (value) => convertedValues.push(converter.convertValue(value, type)));
+        this.visitColumnValues(columnIndex, (value, _r, _c, type) => convertedValues.push(converter(value, type, converter)));
         return convertedValues;
     }
     setColumnValues(columnIndex, values) {
@@ -73,6 +75,17 @@ class DuckDBDataChunk {
             visitColumn(this.getColumnValues(columnIndex), columnIndex, this.getColumnVector(columnIndex).type);
         }
     }
+    appendToColumns(columns) {
+        const columnCount = this.columnCount;
+        for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+            let column = columns[columnIndex];
+            if (!column) {
+                column = [];
+                columns[columnIndex] = column;
+            }
+            this.appendColumnValues(columnIndex, column);
+        }
+    }
     getColumns() {
         const columns = [];
         this.visitColumns((column) => columns.push(column));
@@ -94,6 +107,26 @@ class DuckDBDataChunk {
             this.setColumnValues(columnIndex, columns[columnIndex]);
         }
     }
+    appendToColumnsObject(columnNames, columnsObject) {
+        const columnCount = this.columnCount;
+        if (columnNames.length !== columnCount) {
+            throw new Error(`Provided number of column names (${columnNames.length}) does not match column count (${this.columnCount})`);
+        }
+        for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+            const columnName = columnNames[columnIndex];
+            let columnValues = columnsObject[columnName];
+            if (!columnValues) {
+                columnValues = [];
+                columnsObject[columnName] = columnValues;
+            }
+            this.appendColumnValues(columnIndex, columnValues);
+        }
+    }
+    getColumnsObject(columnNames) {
+        const columnsObject = {};
+        this.appendToColumnsObject(columnNames, columnsObject);
+        return columnsObject;
+    }
     visitColumnMajor(visitValue) {
         const columnCount = this.columnCount;
         for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
@@ -107,14 +140,17 @@ class DuckDBDataChunk {
             visitValue(vector.getItem(rowIndex), rowIndex, columnIndex, vector.type);
         }
     }
+    appendRowValues(rowIndex, values) {
+        this.visitRowValues(rowIndex, (value) => values.push(value));
+    }
     getRowValues(rowIndex) {
         const values = [];
-        this.visitRowValues(rowIndex, (value) => values.push(value));
+        this.appendRowValues(rowIndex, values);
         return values;
     }
     convertRowValues(rowIndex, converter) {
         const convertedValues = [];
-        this.visitRowValues(rowIndex, (value, _, columnIndex) => convertedValues.push(converter.convertValue(value, this.getColumnVector(columnIndex).type)));
+        this.visitRowValues(rowIndex, (value, _, columnIndex) => convertedValues.push(converter(value, this.getColumnVector(columnIndex).type, converter)));
         return convertedValues;
     }
     visitRows(visitRow) {
@@ -123,9 +159,12 @@ class DuckDBDataChunk {
             visitRow(this.getRowValues(rowIndex), rowIndex);
         }
     }
+    appendToRows(rows) {
+        this.visitRows((row) => rows.push(row));
+    }
     getRows() {
         const rows = [];
-        this.visitRows((row) => rows.push(row));
+        this.appendToRows(rows);
         return rows;
     }
     convertRows(converter) {
@@ -147,6 +186,25 @@ class DuckDBDataChunk {
             vector.flush();
         }
     }
+    appendToRowObjects(columnNames, rowObjects) {
+        const columnCount = this.columnCount;
+        if (columnNames.length !== columnCount) {
+            throw new Error(`Provided number of column names (${columnNames.length}) does not match column count (${this.columnCount})`);
+        }
+        const rowCount = this.rowCount;
+        for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+            let rowObject = {};
+            this.visitRowValues(rowIndex, (value, _, columnIndex) => {
+                rowObject[columnNames[columnIndex]] = value;
+            });
+            rowObjects.push(rowObject);
+        }
+    }
+    getRowObjects(columnNames) {
+        const rowObjects = [];
+        this.appendToRowObjects(columnNames, rowObjects);
+        return rowObjects;
+    }
     visitRowMajor(visitValue) {
         const rowCount = this.rowCount;
         const columnCount = this.columnCount;

package/lib/DuckDBInstance.d.ts

@@ -4,5 +4,7 @@ export declare class DuckDBInstance {
     private readonly db;
     constructor(db: duckdb.Database);
     static create(path?: string, options?: Record<string, string>): Promise<DuckDBInstance>;
+    static fromCache(path?: string, options?: Record<string, string>): Promise<DuckDBInstance>;
     connect(): Promise<DuckDBConnection>;
+    closeSync(): void;
 }

package/lib/DuckDBInstance.js

@@ -5,26 +5,26 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DuckDBInstance = void 0;
 const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const createConfig_1 = require("./createConfig");
 const DuckDBConnection_1 = require("./DuckDBConnection");
+const DuckDBInstanceCache_1 = require("./DuckDBInstanceCache");
 class DuckDBInstance {
     db;
     constructor(db) {
         this.db = db;
     }
     static async create(path, options) {
-        const config = node_bindings_1.default.create_config();
-        // Set the default duckdb_api value for the api. Can be overridden.
-        node_bindings_1.default.set_config(config, 'duckdb_api', 'node-neo-api');
-        if (options) {
-            for (const optionName in options) {
-                const optionValue = String(options[optionName]);
-                node_bindings_1.default.set_config(config, optionName, optionValue);
-            }
-        }
+        const config = (0, createConfig_1.createConfig)(options);
         return new DuckDBInstance(await node_bindings_1.default.open(path, config));
     }
+    static async fromCache(path, options) {
+        return DuckDBInstanceCache_1.DuckDBInstanceCache.singleton.getOrCreateInstance(path, options);
+    }
     async connect() {
         return new DuckDBConnection_1.DuckDBConnection(await node_bindings_1.default.connect(this.db));
     }
+    closeSync() {
+        node_bindings_1.default.close_sync(this.db);
+    }
 }
 exports.DuckDBInstance = DuckDBInstance;

package/lib/DuckDBInstanceCache.d.ts

@@ -0,0 +1,8 @@
+import { DuckDBInstance } from './DuckDBInstance';
+export declare class DuckDBInstanceCache {
+    private readonly cache;
+    constructor();
+    getOrCreateInstance(path?: string, options?: Record<string, string>): Promise<DuckDBInstance>;
+    private static singletonInstance;
+    static get singleton(): DuckDBInstanceCache;
+}

package/lib/DuckDBInstanceCache.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBInstanceCache = void 0;
+const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const DuckDBInstance_1 = require("./DuckDBInstance");
+const createConfig_1 = require("./createConfig");
+class DuckDBInstanceCache {
+    cache;
+    constructor() {
+        this.cache = node_bindings_1.default.create_instance_cache();
+    }
+    async getOrCreateInstance(path, options) {
+        const config = (0, createConfig_1.createConfig)(options);
+        const db = await node_bindings_1.default.get_or_create_from_cache(this.cache, path, config);
+        return new DuckDBInstance_1.DuckDBInstance(db);
+    }
+    static singletonInstance;
+    static get singleton() {
+        if (!DuckDBInstanceCache.singletonInstance) {
+            DuckDBInstanceCache.singletonInstance = new DuckDBInstanceCache();
+        }
+        return DuckDBInstanceCache.singletonInstance;
+    }
+}
+exports.DuckDBInstanceCache = DuckDBInstanceCache;