@molecule/api-database-duckdb 0.0.0-stage → 0.0.1-stage

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-database-duckdb` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-database-duckdb is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,wGAAwG;QACtG,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/capabilities.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DuckDB's SQL capability declaration — what the bond can and cannot reproduce
+ * from the PostgreSQL-dialect setup library.
+ *
+ * `@molecule/api-database` defines the contract (`SqlCapabilities`); the same
+ * data is mirrored into this package's `mlcl/registry.json` entry so the CLI can
+ * run the preflight without installing the bond. Verified against
+ * `@duckdb/node-api` 2.0.0-r.1 (the real engine, not a doc page):
+ *
+ * - a foreign key with `ON DELETE CASCADE` / `SET NULL` / `SET DEFAULT` fails at
+ *   parse time with `FOREIGN KEY constraints cannot use CASCADE, SET NULL or SET
+ *   DEFAULT`, and DuckDB has no triggers, so the action cannot be reproduced;
+ * - `CREATE INDEX ... WHERE ...` fails with `Creating partial indexes is not
+ *   supported currently`, while a plain (non-unique) index covers every row
+ *   without changing results and a UNIQUE partial index is reproducible with a
+ *   `CASE WHEN` expression index.
+ *
+ * @module
+ */
+import type { SqlCapabilities } from '@molecule/api-database';
+/**
+ * What the DuckDB bond supports from PostgreSQL-dialect migrations.
+ *
+ * `fk-referential-action` is deliberately `unsupported`: applying the setup
+ * library with the action dropped would make a parent delete fail while child
+ * rows exist, where PostgreSQL cascades — a silently changed delete, which this
+ * bond refuses rather than reproduces inexactly.
+ */
+export declare const sqlCapabilities: SqlCapabilities;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,eAsB7B,CAAA"}

package/dist/capabilities.js

@@ -0,0 +1,48 @@
+/**
+ * DuckDB's SQL capability declaration — what the bond can and cannot reproduce
+ * from the PostgreSQL-dialect setup library.
+ *
+ * `@molecule/api-database` defines the contract (`SqlCapabilities`); the same
+ * data is mirrored into this package's `mlcl/registry.json` entry so the CLI can
+ * run the preflight without installing the bond. Verified against
+ * `@duckdb/node-api` 2.0.0-r.1 (the real engine, not a doc page):
+ *
+ * - a foreign key with `ON DELETE CASCADE` / `SET NULL` / `SET DEFAULT` fails at
+ *   parse time with `FOREIGN KEY constraints cannot use CASCADE, SET NULL or SET
+ *   DEFAULT`, and DuckDB has no triggers, so the action cannot be reproduced;
+ * - `CREATE INDEX ... WHERE ...` fails with `Creating partial indexes is not
+ *   supported currently`, while a plain (non-unique) index covers every row
+ *   without changing results and a UNIQUE partial index is reproducible with a
+ *   `CASE WHEN` expression index.
+ *
+ * @module
+ */
+/**
+ * What the DuckDB bond supports from PostgreSQL-dialect migrations.
+ *
+ * `fk-referential-action` is deliberately `unsupported`: applying the setup
+ * library with the action dropped would make a parent delete fail while child
+ * rows exist, where PostgreSQL cascades — a silently changed delete, which this
+ * bond refuses rather than reproduces inexactly.
+ */
+export const sqlCapabilities = {
+    'fk-referential-action': {
+        support: 'unsupported',
+        note: 'DuckDB rejects ON DELETE and ON UPDATE CASCADE, SET NULL and SET DEFAULT at ' +
+            'parse time and has no triggers, so a cascading or nulling delete cannot be ' +
+            'reproduced. Select a database provider that enforces referential actions, or ' +
+            'remove the resource whose schema needs them.',
+    },
+    'partial-index': {
+        support: 'translated',
+        note: 'Applied as a full index on the same columns. The WHERE clause only narrows ' +
+            'which rows the index covers, so query results are identical without it.',
+    },
+    'unique-partial-index': {
+        support: 'translated',
+        note: 'Applied as a UNIQUE index over CASE WHEN <predicate> THEN <column> END for each ' +
+            'indexed column. Rows outside the predicate get NULL keys, which DuckDB keeps ' +
+            'distinct, so exactly the rows PostgreSQL would constrain are constrained.',
+    },
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAoB;IAC9C,uBAAuB,EAAE;QACvB,OAAO,EAAE,aAAa;QACtB,IAAI,EACF,8EAA8E;YAC9E,6EAA6E;YAC7E,+EAA+E;YAC/E,8CAA8C;KACjD;IACD,eAAe,EAAE;QACf,OAAO,EAAE,YAAY;QACrB,IAAI,EACF,6EAA6E;YAC7E,yEAAyE;KAC5E;IACD,sBAAsB,EAAE;QACtB,OAAO,EAAE,YAAY;QACrB,IAAI,EACF,kFAAkF;YAClF,+EAA+E;YAC/E,2EAA2E;KAC9E;CACF,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * DuckDB database provider for molecule.dev — an embedded analytical SQL
+ * engine that queries Parquet, CSV and JSON files in-process.
+ *
+ * Provides DatabasePool and DataStore implementations backed by
+ * `@duckdb/node-api` (DuckDB 2.0). DuckDB is the SQLite shape, but
+ * columnar/OLAP: it is the right bond for analytics over files
+ * (`SELECT * FROM read_parquet('events.parquet')`), aggregations and ad-hoc
+ * slices — not for a high-write-rate OLTP app (that is the postgresql bond's
+ * job).
+ *
+ * DuckDB cannot reproduce a foreign key's `ON DELETE`/`ON UPDATE` `CASCADE`,
+ * `SET NULL` or `SET DEFAULT` action, and this bond refuses to silently drop
+ * it: a resource whose setup SQL needs one is refused by the generator's
+ * compatibility preflight ({@link sqlCapabilities}) before an app is built.
+ *
+ * @example
+ * ```typescript
+ * import { setPool, setStore } from '@molecule/api-database'
+ * import { pool, store } from '@molecule/api-database-duckdb'
+ *
+ * setPool(pool)
+ * setStore(store)
+ * ```
+ *
+ * @remarks
+ * Configure via the `DUCKDB_PATH` environment variable (default:
+ * `./data/app.duckdb`; `:memory:` for a database that lives only for the
+ * process's lifetime).
+ * - **`pool.query(text, values)` takes Postgres-style `$1, $2` placeholders —
+ *   or `?` — natively, with no translation.** With VALUES a string must be
+ *   ONE statement (the client prepares it); without values a multi-statement
+ *   string runs in full and the LAST statement's result is returned.
+ *   `rowCount` follows node-postgres: rows returned for a SELECT or
+ *   `…RETURNING` statement, rows changed for plain INSERT/UPDATE/DELETE,
+ *   `null` for DDL.
+ * - **One process per file, in read-write mode.** DuckDB holds a file lock:
+ *   the dev server and a CLI must never open the same `.duckdb` file
+ *   read-write at the same time (`Could not set lock on file`). This pool
+ *   shares one instance per file inside the process (`fromCache`) and
+ *   serializes every statement on ONE connection behind a FIFO queue, the
+ *   sqlite bond's model — a `transaction()` holds the queue for its whole
+ *   `BEGIN` → … → `COMMIT`/`ROLLBACK` lifetime. A second PROCESS wanting
+ *   concurrent reads should open `readOnly: true`.
+ * - **Resource defaults differ from DuckDB's own.** DuckDB defaults to 80% of
+ *   RAM for `memory_limit` and one thread per core — enough to eat a shared
+ *   host. This bond defaults to `memory_limit: '1GB'` and `threads: 4`,
+ *   overridable via `DUCKDB_MEMORY_LIMIT` / `DUCKDB_THREADS` or the
+ *   `memoryLimit`/`threads` config fields.
+ * - **Files are the point:** `read_parquet`, `read_csv`, `read_json` and the
+ *   `'file.parquet'` shorthand all work through `pool.query()` as plain SQL.
+ *   They read relative to the API process's working directory.
+ * - **JSON columns read as JSON TEXT through raw `query()`** — DuckDB's
+ *   `JSON` type is an alias over VARCHAR, so the type is invisible in result
+ *   metadata. The DataStore CRUD helpers (`create`, `findMany`, …) parse
+ *   JSON-typed columns for you; in raw SQL use `data -> 'key'` /
+ *   `json_extract` or accept the string.
+ * - **`COUNT(*)` and BIGINT come back as JS numbers** when they fit
+ *   `Number.MAX_SAFE_INTEGER` (raw DuckDB returns `bigint`, which
+ *   `JSON.stringify` throws on); a larger value becomes its decimal string,
+ *   matching node-postgres.
+ * - **Schema changes are `*.sql` files in the app's `api/migrations/`**,
+ *   applied in lexical order on startup by `createMigrator`. Postgres-dialect
+ *   DDL applies after a translation that keeps behaviour: `jsonb` → `json`,
+ *   index `USING <method>` dropped, and a partial index applied as a full index
+ *   or (UNIQUE) as a `CASE WHEN` expression index. `gen_random_uuid()`,
+ *   `now()`, `ADD/DROP COLUMN IF [NOT] EXISTS`, `::` casts and `uuid`/
+ *   `timestamptz`/`bytea`/`text[]` types are native. An `ON DELETE`/
+ *   `ON UPDATE` referential action throws `UnsupportedSqlFeatureError` —
+ *   DuckDB cannot reproduce it; each file runs once (recorded in
+ *   `_molecule_migrations`) and in one transaction.
+ * - **2.0 file format is a one-way break:** versions before DuckDB 2.0 cannot
+ *   read files this bond creates (2.0 still reads 1.x files). The engine is
+ *   OLAP — bulk scans and aggregations are its home; an app doing many small
+ *   row transactions belongs on the postgresql bond.
+ * - `pool.end()` closes the pool's connection; a FILE-backed instance is
+ *   process-lifetime by design (the client's instance cache has no eviction).
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './capabilities.js';
+export * from './instances.js';
+export * from './lifecycle.js';
+export * from './migrator.js';
+export * from './pool.js';
+export * from './queue.js';
+export * from './secrets.js';
+export * from './store.js';
+export * from './types.js';
+export * from './utilities.js';
+import type { DatabasePool } from '@molecule/api-database';
+/**
+ * The DuckDB connection pool instance.
+ */
+export declare const pool: DatabasePool;
+/**
+ * Whether the lazy default pool has been created.
+ *
+ * Readiness and shutdown wiring must not FORCE a connection.
+ *
+ * @returns `true` once the default pool exists.
+ */
+export declare const defaultPoolCreated: () => boolean;
+/**
+ * Close the lazy default pool, if it was created.
+ *
+ * @returns Resolves once the pool has ended.
+ */
+export declare const closeDefaultPool: () => Promise<void>;
+/**
+ * Default DataStore proxy backed by the lazily-initialized default pool.
+ */
+export declare const store: import("@molecule/api-database").DataStore;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAE9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAsB1D;;GAEG;AACH,eAAO,MAAM,IAAI,EAAE,YAQjB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,QAAO,OAAyB,CAAA;AAE/D;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAa,OAAO,CAAC,IAAI,CAIrD,CAAA;AAOD;;GAEG;AACH,eAAO,MAAM,KAAK,4CAUhB,CAAA"}

package/dist/index.js

@@ -0,0 +1,169 @@
+/**
+ * DuckDB database provider for molecule.dev — an embedded analytical SQL
+ * engine that queries Parquet, CSV and JSON files in-process.
+ *
+ * Provides DatabasePool and DataStore implementations backed by
+ * `@duckdb/node-api` (DuckDB 2.0). DuckDB is the SQLite shape, but
+ * columnar/OLAP: it is the right bond for analytics over files
+ * (`SELECT * FROM read_parquet('events.parquet')`), aggregations and ad-hoc
+ * slices — not for a high-write-rate OLTP app (that is the postgresql bond's
+ * job).
+ *
+ * DuckDB cannot reproduce a foreign key's `ON DELETE`/`ON UPDATE` `CASCADE`,
+ * `SET NULL` or `SET DEFAULT` action, and this bond refuses to silently drop
+ * it: a resource whose setup SQL needs one is refused by the generator's
+ * compatibility preflight ({@link sqlCapabilities}) before an app is built.
+ *
+ * @example
+ * ```typescript
+ * import { setPool, setStore } from '@molecule/api-database'
+ * import { pool, store } from '@molecule/api-database-duckdb'
+ *
+ * setPool(pool)
+ * setStore(store)
+ * ```
+ *
+ * @remarks
+ * Configure via the `DUCKDB_PATH` environment variable (default:
+ * `./data/app.duckdb`; `:memory:` for a database that lives only for the
+ * process's lifetime).
+ * - **`pool.query(text, values)` takes Postgres-style `$1, $2` placeholders —
+ *   or `?` — natively, with no translation.** With VALUES a string must be
+ *   ONE statement (the client prepares it); without values a multi-statement
+ *   string runs in full and the LAST statement's result is returned.
+ *   `rowCount` follows node-postgres: rows returned for a SELECT or
+ *   `…RETURNING` statement, rows changed for plain INSERT/UPDATE/DELETE,
+ *   `null` for DDL.
+ * - **One process per file, in read-write mode.** DuckDB holds a file lock:
+ *   the dev server and a CLI must never open the same `.duckdb` file
+ *   read-write at the same time (`Could not set lock on file`). This pool
+ *   shares one instance per file inside the process (`fromCache`) and
+ *   serializes every statement on ONE connection behind a FIFO queue, the
+ *   sqlite bond's model — a `transaction()` holds the queue for its whole
+ *   `BEGIN` → … → `COMMIT`/`ROLLBACK` lifetime. A second PROCESS wanting
+ *   concurrent reads should open `readOnly: true`.
+ * - **Resource defaults differ from DuckDB's own.** DuckDB defaults to 80% of
+ *   RAM for `memory_limit` and one thread per core — enough to eat a shared
+ *   host. This bond defaults to `memory_limit: '1GB'` and `threads: 4`,
+ *   overridable via `DUCKDB_MEMORY_LIMIT` / `DUCKDB_THREADS` or the
+ *   `memoryLimit`/`threads` config fields.
+ * - **Files are the point:** `read_parquet`, `read_csv`, `read_json` and the
+ *   `'file.parquet'` shorthand all work through `pool.query()` as plain SQL.
+ *   They read relative to the API process's working directory.
+ * - **JSON columns read as JSON TEXT through raw `query()`** — DuckDB's
+ *   `JSON` type is an alias over VARCHAR, so the type is invisible in result
+ *   metadata. The DataStore CRUD helpers (`create`, `findMany`, …) parse
+ *   JSON-typed columns for you; in raw SQL use `data -> 'key'` /
+ *   `json_extract` or accept the string.
+ * - **`COUNT(*)` and BIGINT come back as JS numbers** when they fit
+ *   `Number.MAX_SAFE_INTEGER` (raw DuckDB returns `bigint`, which
+ *   `JSON.stringify` throws on); a larger value becomes its decimal string,
+ *   matching node-postgres.
+ * - **Schema changes are `*.sql` files in the app's `api/migrations/`**,
+ *   applied in lexical order on startup by `createMigrator`. Postgres-dialect
+ *   DDL applies after a translation that keeps behaviour: `jsonb` → `json`,
+ *   index `USING <method>` dropped, and a partial index applied as a full index
+ *   or (UNIQUE) as a `CASE WHEN` expression index. `gen_random_uuid()`,
+ *   `now()`, `ADD/DROP COLUMN IF [NOT] EXISTS`, `::` casts and `uuid`/
+ *   `timestamptz`/`bytea`/`text[]` types are native. An `ON DELETE`/
+ *   `ON UPDATE` referential action throws `UnsupportedSqlFeatureError` —
+ *   DuckDB cannot reproduce it; each file runs once (recorded in
+ *   `_molecule_migrations`) and in one transaction.
+ * - **2.0 file format is a one-way break:** versions before DuckDB 2.0 cannot
+ *   read files this bond creates (2.0 still reads 1.x files). The engine is
+ *   OLAP — bulk scans and aggregations are its home; an app doing many small
+ *   row transactions belongs on the postgresql bond.
+ * - `pool.end()` closes the pool's connection; a FILE-backed instance is
+ *   process-lifetime by design (the client's instance cache has no eviction).
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './capabilities.js';
+export * from './instances.js';
+export * from './lifecycle.js';
+export * from './migrator.js';
+export * from './pool.js';
+export * from './queue.js';
+export * from './secrets.js';
+export * from './store.js';
+export * from './types.js';
+export * from './utilities.js';
+import { registerLifecycleIntegration } from './lifecycle.js';
+import { createPool } from './pool.js';
+import { createStore } from './store.js';
+/**
+ * Lazily-initialized default pool.
+ */
+let _pool = null;
+/**
+ * Returns the lazily-initialized default pool, creating it on first call.
+ * @returns The singleton DatabasePool instance.
+ */
+function getPoolInstance() {
+    if (!_pool) {
+        _pool = createPool();
+    }
+    return _pool;
+}
+/**
+ * The DuckDB connection pool instance.
+ */
+export const pool = new Proxy({}, {
+    get(_, prop, receiver) {
+        return Reflect.get(getPoolInstance(), prop, receiver);
+    },
+    // set trap: methods run with `this` bound to the proxy — without it, instance-state writes land on the dummy target and are lost (see api-push-notifications-web-push)
+    set(_, prop, value) {
+        return Reflect.set(getPoolInstance(), prop, value);
+    },
+});
+/**
+ * Whether the lazy default pool has been created.
+ *
+ * Readiness and shutdown wiring must not FORCE a connection.
+ *
+ * @returns `true` once the default pool exists.
+ */
+export const defaultPoolCreated = () => _pool !== null;
+/**
+ * Close the lazy default pool, if it was created.
+ *
+ * @returns Resolves once the pool has ended.
+ */
+export const closeDefaultPool = async () => {
+    const current = _pool;
+    _pool = null;
+    if (current)
+        await current.end();
+};
+/**
+ * Default DataStore instance backed by the default pool.
+ */
+let _store = null;
+/**
+ * Default DataStore proxy backed by the lazily-initialized default pool.
+ */
+export const store = new Proxy({}, {
+    get(_, prop, receiver) {
+        if (!_store)
+            _store = createStore(getPoolInstance());
+        return Reflect.get(_store, prop, receiver);
+    },
+    // set trap: methods run with `this` bound to the proxy — without it, instance-state writes land on the dummy target and are lost (see api-push-notifications-web-push)
+    set(_, prop, value) {
+        if (!_store)
+            _store = createStore(getPoolInstance());
+        return Reflect.set(_store, prop, value);
+    },
+});
+// Register the readiness probe and shutdown hook once, when this bond is
+// imported; the core queues them until a lifecycle provider is bonded.
+registerLifecycleIntegration({
+    ping: async () => {
+        await pool.query('SELECT 1');
+    },
+    close: closeDefaultPool,
+    created: defaultPoolCreated,
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAI9B,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAExC;;GAEG;AACH,IAAI,KAAK,GAAwB,IAAI,CAAA;AAErC;;;GAGG;AACH,SAAS,eAAe;IACtB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,UAAU,EAAE,CAAA;IACtB,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,IAAI,GAAiB,IAAI,KAAK,CAAC,EAAkB,EAAE;IAC9D,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ;QACnB,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;IACvD,CAAC;IACD,uKAAuK;IACvK,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK;QAChB,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;IACpD,CAAC;CACF,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAY,EAAE,CAAC,KAAK,KAAK,IAAI,CAAA;AAE/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,IAAmB,EAAE;IACxD,MAAM,OAAO,GAAG,KAAK,CAAA;IACrB,KAAK,GAAG,IAAI,CAAA;IACZ,IAAI,OAAO;QAAE,MAAM,OAAO,CAAC,GAAG,EAAE,CAAA;AAClC,CAAC,CAAA;AAED;;GAEG;AACH,IAAI,MAAM,GAA0C,IAAI,CAAA;AAExD;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAAoC,EAAE;IACnE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ;QACnB,IAAI,CAAC,MAAM;YAAE,MAAM,GAAG,WAAW,CAAC,eAAe,EAAE,CAAC,CAAA;QACpD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;IAC5C,CAAC;IACD,uKAAuK;IACvK,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK;QAChB,IAAI,CAAC,MAAM;YAAE,MAAM,GAAG,WAAW,CAAC,eAAe,EAAE,CAAC,CAAA;QACpD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;IACzC,CAAC;CACF,CAAC,CAAA;AAEF,yEAAyE;AACzE,uEAAuE;AACvE,4BAA4B,CAAC;IAC3B,IAAI,EAAE,KAAK,IAAI,EAAE;QACf,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;IAC9B,CAAC;IACD,KAAK,EAAE,gBAAgB;IACvB,OAAO,EAAE,kBAAkB;CAC5B,CAAC,CAAA"}

package/dist/instances.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Opens DuckDB instances and shares one instance per database file.
+ *
+ * @module
+ */
+import { DuckDBInstance } from '@duckdb/node-api';
+import { ConnectionLock } from './queue.js';
+import type { DuckdbConfig } from './types.js';
+/** The in-memory database path. */
+export declare const MEMORY_PATH = ":memory:";
+/** Default on-disk database path. */
+export declare const DEFAULT_DUCKDB_PATH = "./data/app.duckdb";
+/** Default `memory_limit`: DuckDB's own default is 80% of RAM — far too much on a shared host. */
+export declare const DEFAULT_MEMORY_LIMIT = "1GB";
+/** Default `threads`: DuckDB's own default is every core — oversubscribes a shared host. */
+export declare const DEFAULT_THREADS = 4;
+/**
+ * One opened database: the DuckDB instance, the lock over its single pooled
+ * connection, and how many pools currently use it.
+ */
+export interface DuckdbInstanceHandle {
+    /** The DuckDB instance. */
+    instance: DuckDBInstance;
+    /** FIFO lock over the pool's single connection. */
+    lock: ConnectionLock;
+    /** The resolved path (`':memory:'` for in-memory). */
+    path: string;
+    /** Pools currently using this instance. */
+    refs: number;
+}
+/**
+ * Resolve the effective instance options for a config: sane `memory_limit` and
+ * `threads` defaults (DuckDB's own defaults are 80% of RAM and every core,
+ * which let one in-process engine eat a shared VM whole), `access_mode` for
+ * `readOnly`, env overrides, then the caller's raw `config` map on top.
+ *
+ * @param config - Pool configuration.
+ * @returns The options for `DuckDBInstance.fromCache(path, options)`.
+ */
+export declare function instanceOptionsFor(config?: DuckdbConfig): Record<string, string>;
+/**
+ * Pick the database path from config, then `DUCKDB_PATH`, then the default.
+ *
+ * @param config - Pool configuration.
+ * @returns The path as given (not yet resolved).
+ */
+export declare function choosePath(config?: DuckdbConfig): string;
+/**
+ * Open (or join) the instance for a pool.
+ *
+ * A FILE path goes through `DuckDBInstance.fromCache`: the official answer to
+ * "two instances must never open the same file" — every pool in this process
+ * on one file shares one instance (and one write lock). In-memory databases
+ * are always PRIVATE (a shared `:memory:` cache entry would hand two test
+ * pools one database), so they use a fresh `create` and are closed when their
+ * last pool ends. File-backed cached instances are NEVER closed by this
+ * module: the client's cache has no eviction, and closing a cached instance
+ * would hand the next `fromCache` caller a dead one — they live for the
+ * process, which is also why a file path must not be reused across processes
+ * in read-write mode.
+ *
+ * @param config - Pool configuration.
+ * @returns The instance, with a reference taken for the caller.
+ */
+export declare function acquireInstance(config?: DuckdbConfig): Promise<DuckdbInstanceHandle>;
+/**
+ * Drop a pool's reference; close the instance when no pool uses it and it is
+ * one of this module's private in-memory instances.
+ *
+ * @param handle - The instance to release.
+ */
+export declare function releaseInstance(handle: DuckdbInstanceHandle): void;
+//# sourceMappingURL=instances.d.ts.map

package/dist/instances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../src/instances.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,mCAAmC;AACnC,eAAO,MAAM,WAAW,aAAa,CAAA;AAErC,qCAAqC;AACrC,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,QAAQ,CAAA;AAEzC,4FAA4F;AAC5F,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,QAAQ,EAAE,cAAc,CAAA;IACxB,mDAAmD;IACnD,IAAI,EAAE,cAAc,CAAA;IACpB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;CACb;AAaD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAchF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAKxD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuB1F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAMlE"}

package/dist/instances.js

@@ -0,0 +1,117 @@
+/**
+ * Opens DuckDB instances and shares one instance per database file.
+ *
+ * @module
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { DuckDBInstance } from '@duckdb/node-api';
+import { ConnectionLock } from './queue.js';
+/** The in-memory database path. */
+export const MEMORY_PATH = ':memory:';
+/** Default on-disk database path. */
+export const DEFAULT_DUCKDB_PATH = './data/app.duckdb';
+/** Default `memory_limit`: DuckDB's own default is 80% of RAM — far too much on a shared host. */
+export const DEFAULT_MEMORY_LIMIT = '1GB';
+/** Default `threads`: DuckDB's own default is every core — oversubscribes a shared host. */
+export const DEFAULT_THREADS = 4;
+/** In-memory instances, each private to the pool that opened it. */
+const memoryHandles = new Set();
+/**
+ * One lock per shared FILE instance: `fromCache` hands every pool on a path
+ * the SAME instance object, so the lock is keyed off that object — two pools
+ * on one file then share one queue (and cannot race each other's writes),
+ * while each `:memory:` pool owns its own lock via its private handle.
+ */
+const sharedLocks = new WeakMap();
+/**
+ * Resolve the effective instance options for a config: sane `memory_limit` and
+ * `threads` defaults (DuckDB's own defaults are 80% of RAM and every core,
+ * which let one in-process engine eat a shared VM whole), `access_mode` for
+ * `readOnly`, env overrides, then the caller's raw `config` map on top.
+ *
+ * @param config - Pool configuration.
+ * @returns The options for `DuckDBInstance.fromCache(path, options)`.
+ */
+export function instanceOptionsFor(config) {
+    const memoryLimit = config?.memoryLimit ?? process.env.DUCKDB_MEMORY_LIMIT ?? DEFAULT_MEMORY_LIMIT;
+    const threads = String(config?.threads ??
+        (process.env.DUCKDB_THREADS != null && process.env.DUCKDB_THREADS !== ''
+            ? process.env.DUCKDB_THREADS
+            : DEFAULT_THREADS));
+    return {
+        memory_limit: memoryLimit,
+        threads,
+        ...(config?.readOnly ? { access_mode: 'READ_ONLY' } : {}),
+        ...(config?.config ?? {}),
+    };
+}
+/**
+ * Pick the database path from config, then `DUCKDB_PATH`, then the default.
+ *
+ * @param config - Pool configuration.
+ * @returns The path as given (not yet resolved).
+ */
+export function choosePath(config) {
+    if (config?.path)
+        return config.path;
+    const fromEnv = process.env.DUCKDB_PATH;
+    if (fromEnv)
+        return fromEnv;
+    return DEFAULT_DUCKDB_PATH;
+}
+/**
+ * Open (or join) the instance for a pool.
+ *
+ * A FILE path goes through `DuckDBInstance.fromCache`: the official answer to
+ * "two instances must never open the same file" — every pool in this process
+ * on one file shares one instance (and one write lock). In-memory databases
+ * are always PRIVATE (a shared `:memory:` cache entry would hand two test
+ * pools one database), so they use a fresh `create` and are closed when their
+ * last pool ends. File-backed cached instances are NEVER closed by this
+ * module: the client's cache has no eviction, and closing a cached instance
+ * would hand the next `fromCache` caller a dead one — they live for the
+ * process, which is also why a file path must not be reused across processes
+ * in read-write mode.
+ *
+ * @param config - Pool configuration.
+ * @returns The instance, with a reference taken for the caller.
+ */
+export async function acquireInstance(config) {
+    const path = choosePath(config);
+    const options = instanceOptionsFor(config);
+    if (path === MEMORY_PATH) {
+        const instance = await DuckDBInstance.create(path, options);
+        const handle = { instance, lock: new ConnectionLock(), path, refs: 1 };
+        memoryHandles.add(handle);
+        return handle;
+    }
+    const dir = dirname(path);
+    if (dir && !existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const resolved = resolve(path);
+    const instance = await DuckDBInstance.fromCache(resolved, options);
+    let lock = sharedLocks.get(instance);
+    if (!lock) {
+        lock = new ConnectionLock();
+        sharedLocks.set(instance, lock);
+    }
+    return { instance, lock, path: resolved, refs: 1 };
+}
+/**
+ * Drop a pool's reference; close the instance when no pool uses it and it is
+ * one of this module's private in-memory instances.
+ *
+ * @param handle - The instance to release.
+ */
+export function releaseInstance(handle) {
+    handle.refs--;
+    if (handle.refs > 0)
+        return;
+    if (!memoryHandles.has(handle))
+        return;
+    memoryHandles.delete(handle);
+    handle.instance.closeSync();
+}
+//# sourceMappingURL=instances.js.map

package/dist/instances.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instances.js","sourceRoot":"","sources":["../src/instances.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Process-lifecycle integration for the DuckDB bond.
+ *
+ * Optional and dynamic — a project without `@molecule/api-process-lifecycle`
+ * imports this bond unchanged. With the package present, `/health/ready` runs
+ * a CRITICAL `SELECT 1` (a DuckDB file can be locked, removed, or its disk
+ * full after boot) and the ordered shutdown closes the pool.
+ *
+ * @module
+ */
+/**
+ * Register the database readiness check and shutdown hook with the bonded
+ * process-lifecycle provider.
+ *
+ * @param resources - The ping and close functions this bond owns.
+ */
+export declare function registerLifecycleIntegration(resources: {
+    ping: () => Promise<void>;
+    close: () => Promise<void>;
+    created: () => boolean;
+}): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE;IACtD,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,OAAO,EAAE,MAAM,OAAO,CAAA;CACvB,GAAG,IAAI,CAwBP"}