@molecule/api-database 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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` 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 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,iGAAiG;QAC/F,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Database core interface for molecule.dev.
+ *
+ * Defines the standard interface for database providers, including both
+ * raw connection pools and the database-agnostic DataStore abstraction.
+ *
+ * @example
+ * ```typescript
+ * import { setStore, findById, findMany, create, updateById, deleteById } from '@molecule/api-database'
+ * import { store } from '@molecule/api-database-postgresql'
+ *
+ * // Wire the DataStore at app startup
+ * setStore(store)
+ *
+ * // CRUD operations — database-agnostic
+ * const user = await findById<User>('users', userId)
+ *
+ * const activeUsers = await findMany<User>('users', {
+ *   where: [
+ *     { field: 'status', operator: '=', value: 'active' },
+ *   ],
+ *   orderBy: [{ field: 'createdAt', direction: 'desc' }],
+ *   limit: 50,
+ * })
+ *
+ * await create('users', { id, username, email })
+ * await updateById('users', id, { name: 'New Name' })
+ * await deleteById('users', id)
+ * ```
+ *
+ * @remarks
+ * Data-access contract — the rules code generators most often get wrong:
+ *
+ * - **Scope EVERY query by owner — the #1 security rule.** A user must never read or write
+ *   another user's rows. Add `{ field: 'user_id', operator: '=', value: getUserId(res) }` to
+ *   every list/read `where`, and for a single-row route load the row and 404 if it isn't the
+ *   caller's (404, not 403 — don't leak existence). An unscoped `findById`/`updateById`/
+ *   `deleteById` on a client-supplied id is an IDOR (one user edits another's data). See the
+ *   `auth` skill.
+ * - **CRUD goes through the exported data functions** (`findById`, `findOne`,
+ *   `findMany`, `count`, `create`, `updateById`, `deleteById`). Filter with a
+ *   `where` ARRAY of `{ field, operator, value }`:
+ *   `findMany('plants', { where: [{ field: 'speciesId', operator: '=', value: id }], limit: 50 })`.
+ *   A bare key object — `findMany('plants', { speciesId: id })` — is NOT a valid
+ *   `FindManyOptions` and will not filter.
+ * - **Raw SQL: import the standalone `query(sql, values)` from this package** —
+ *   NOT `getStore().query()`. The DataStore has no `query`; raw parameterized
+ *   query lives on the pool/provider. The store also has NO `.exec()`,
+ *   `.prepare()`, `.run()`, `.get()`, or `.all()` — those are driver methods
+ *   (better-sqlite3 / pg) and calling them fails the type-check.
+ * - **Atomic multi-write = a MANUAL transaction on ONE connection; the store
+ *   helpers do NOT join it.** When several writes must be all-or-nothing (move
+ *   funds between two accounts, create an order AND decrement its stock, accept a
+ *   booking AND mark the slot taken), acquire a dedicated connection and drive
+ *   raw SQL on IT: `const conn = await connect()` then
+ *   `try { await conn.query('BEGIN'); …writes…; await conn.query('COMMIT') }`
+ *   `catch (e) { await conn.query('ROLLBACK').catch(() => {}); throw e }`
+ *   `finally { conn.release() }`. **The load-bearing gotcha:** the exported
+ *   `create`/`updateById`/`findMany`/`deleteById` run on the POOL's own
+ *   connection and commit INDEPENDENTLY — calling them between your `BEGIN` and
+ *   `COMMIT` does NOT enroll them in the transaction, so a mid-way failure leaves
+ *   those writes committed while the rest rolls back (a half-applied transfer).
+ *   Inside a transaction do every read AND write with `conn.query(sql, values)`
+ *   on that same `conn`, and ALWAYS `release()` in `finally` — a leaked
+ *   connection permanently drains the pool. Prefer this only for true multi-row
+ *   invariants; a single-row update is already atomic via `updateById`.
+ * - **Create tables only via timestamped `.sql` files in `migrations/`** (the
+ *   migration runner applies them on startup) — NEVER programmatically through
+ *   the store. Seed rows with `create()`.
+ * - **Every `id` is a UUID string** (the resource layer sets `id = id || uuid()`
+ *   on create). So every primary key AND foreign key is a UUID-string column:
+ *   `id TEXT PRIMARY KEY` (SQLite) / `id UUID PRIMARY KEY` (Postgres); FKs
+ *   likewise (`user_id TEXT` / `user_id UUID`). NEVER `INTEGER PRIMARY KEY
+ *   AUTOINCREMENT` or `SERIAL` — inserting a UUID string into an integer key
+ *   fails at runtime (`datatype mismatch`) and breaks every create endpoint.
+ * - **`like` vs `ilike` — pick by who controls the wildcards.** Both are
+ *   case-insensitive on every bond (identical results across postgresql/
+ *   mysql/sqlite — see the `WhereCondition['operator']` JSDoc for exactly how
+ *   each bond gets there). `like` passes `value` through as a raw SQL
+ *   pattern — YOU write the `%`/`_`; use it when you already built the
+ *   pattern (e.g. a fixed prefix search `'admin_%'`). `ilike` treats `value`
+ *   as a literal substring, escapes it, and wraps `%…%` for you — use it for
+ *   ANY human-typed search box (`{ operator: 'ilike', value: userInput }`),
+ *   never `like` with a caller-built `%${userInput}%` string.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './types.js';
+export * from './provider.js';
+export * from './store.js';
+export * from './store-provider.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AAGH,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAG1B,cAAc,eAAe,CAAA;AAG7B,cAAc,YAAY,CAAA;AAC1B,cAAc,qBAAqB,CAAA"}

package/dist/index.js

@@ -0,0 +1,96 @@
+/**
+ * Database core interface for molecule.dev.
+ *
+ * Defines the standard interface for database providers, including both
+ * raw connection pools and the database-agnostic DataStore abstraction.
+ *
+ * @example
+ * ```typescript
+ * import { setStore, findById, findMany, create, updateById, deleteById } from '@molecule/api-database'
+ * import { store } from '@molecule/api-database-postgresql'
+ *
+ * // Wire the DataStore at app startup
+ * setStore(store)
+ *
+ * // CRUD operations — database-agnostic
+ * const user = await findById<User>('users', userId)
+ *
+ * const activeUsers = await findMany<User>('users', {
+ *   where: [
+ *     { field: 'status', operator: '=', value: 'active' },
+ *   ],
+ *   orderBy: [{ field: 'createdAt', direction: 'desc' }],
+ *   limit: 50,
+ * })
+ *
+ * await create('users', { id, username, email })
+ * await updateById('users', id, { name: 'New Name' })
+ * await deleteById('users', id)
+ * ```
+ *
+ * @remarks
+ * Data-access contract — the rules code generators most often get wrong:
+ *
+ * - **Scope EVERY query by owner — the #1 security rule.** A user must never read or write
+ *   another user's rows. Add `{ field: 'user_id', operator: '=', value: getUserId(res) }` to
+ *   every list/read `where`, and for a single-row route load the row and 404 if it isn't the
+ *   caller's (404, not 403 — don't leak existence). An unscoped `findById`/`updateById`/
+ *   `deleteById` on a client-supplied id is an IDOR (one user edits another's data). See the
+ *   `auth` skill.
+ * - **CRUD goes through the exported data functions** (`findById`, `findOne`,
+ *   `findMany`, `count`, `create`, `updateById`, `deleteById`). Filter with a
+ *   `where` ARRAY of `{ field, operator, value }`:
+ *   `findMany('plants', { where: [{ field: 'speciesId', operator: '=', value: id }], limit: 50 })`.
+ *   A bare key object — `findMany('plants', { speciesId: id })` — is NOT a valid
+ *   `FindManyOptions` and will not filter.
+ * - **Raw SQL: import the standalone `query(sql, values)` from this package** —
+ *   NOT `getStore().query()`. The DataStore has no `query`; raw parameterized
+ *   query lives on the pool/provider. The store also has NO `.exec()`,
+ *   `.prepare()`, `.run()`, `.get()`, or `.all()` — those are driver methods
+ *   (better-sqlite3 / pg) and calling them fails the type-check.
+ * - **Atomic multi-write = a MANUAL transaction on ONE connection; the store
+ *   helpers do NOT join it.** When several writes must be all-or-nothing (move
+ *   funds between two accounts, create an order AND decrement its stock, accept a
+ *   booking AND mark the slot taken), acquire a dedicated connection and drive
+ *   raw SQL on IT: `const conn = await connect()` then
+ *   `try { await conn.query('BEGIN'); …writes…; await conn.query('COMMIT') }`
+ *   `catch (e) { await conn.query('ROLLBACK').catch(() => {}); throw e }`
+ *   `finally { conn.release() }`. **The load-bearing gotcha:** the exported
+ *   `create`/`updateById`/`findMany`/`deleteById` run on the POOL's own
+ *   connection and commit INDEPENDENTLY — calling them between your `BEGIN` and
+ *   `COMMIT` does NOT enroll them in the transaction, so a mid-way failure leaves
+ *   those writes committed while the rest rolls back (a half-applied transfer).
+ *   Inside a transaction do every read AND write with `conn.query(sql, values)`
+ *   on that same `conn`, and ALWAYS `release()` in `finally` — a leaked
+ *   connection permanently drains the pool. Prefer this only for true multi-row
+ *   invariants; a single-row update is already atomic via `updateById`.
+ * - **Create tables only via timestamped `.sql` files in `migrations/`** (the
+ *   migration runner applies them on startup) — NEVER programmatically through
+ *   the store. Seed rows with `create()`.
+ * - **Every `id` is a UUID string** (the resource layer sets `id = id || uuid()`
+ *   on create). So every primary key AND foreign key is a UUID-string column:
+ *   `id TEXT PRIMARY KEY` (SQLite) / `id UUID PRIMARY KEY` (Postgres); FKs
+ *   likewise (`user_id TEXT` / `user_id UUID`). NEVER `INTEGER PRIMARY KEY
+ *   AUTOINCREMENT` or `SERIAL` — inserting a UUID string into an integer key
+ *   fails at runtime (`datatype mismatch`) and breaks every create endpoint.
+ * - **`like` vs `ilike` — pick by who controls the wildcards.** Both are
+ *   case-insensitive on every bond (identical results across postgresql/
+ *   mysql/sqlite — see the `WhereCondition['operator']` JSDoc for exactly how
+ *   each bond gets there). `like` passes `value` through as a raw SQL
+ *   pattern — YOU write the `%`/`_`; use it when you already built the
+ *   pattern (e.g. a fixed prefix search `'admin_%'`). `ilike` treats `value`
+ *   as a literal substring, escapes it, and wraps `%…%` for you — use it for
+ *   ANY human-typed search box (`{ operator: 'ilike', value: userInput }`),
+ *   never `like` with a caller-built `%${userInput}%` string.
+ *
+ * @module
+ */
+// Type exports
+export * from './browser-guard.js';
+export * from './types.js';
+// Provider exports (raw query access)
+export * from './provider.js';
+// DataStore exports (abstract CRUD)
+export * from './store.js';
+export * from './store-provider.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AAEH,eAAe;AACf,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAE1B,sCAAsC;AACtC,cAAc,eAAe,CAAA;AAE7B,oCAAoC;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,qBAAqB,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Database pool bond accessor and convenience functions for raw SQL queries.
+ *
+ * Bond packages (e.g. `@molecule/api-database-postgresql`) call `setPool()` during setup.
+ * Application code uses `query()` for raw SQL, or the DataStore functions from
+ * `store-provider.ts` for database-agnostic CRUD.
+ *
+ * @module
+ */
+import type { DatabaseConnection, DatabasePool, QueryResult } from './types.js';
+/**
+ * Registers a database connection pool as the active singleton. Called by
+ * bond packages during application startup.
+ *
+ * @param pool - The database pool implementation to bond.
+ */
+export declare const setPool: (pool: DatabasePool) => void;
+/**
+ * Retrieves the bonded database pool, throwing if none is configured.
+ *
+ * @returns The bonded database pool.
+ * @throws {Error} If no database pool has been bonded.
+ */
+export declare const getPool: () => DatabasePool;
+/**
+ * Checks whether a database pool is currently bonded.
+ *
+ * @returns `true` if a database pool is bonded.
+ */
+export declare const hasPool: () => boolean;
+/**
+ * Executes a parameterized SQL query using the bonded pool.
+ *
+ * @param text - SQL query text with placeholders (`$1`, `$2`, etc.).
+ * @param values - Parameter values corresponding to the placeholders.
+ * @returns The query result containing `rows`, `rowCount`, and optional `fields`.
+ * @throws {Error} If no database pool has been bonded.
+ */
+export declare const query: <T = Record<string, unknown>>(text: string, values?: unknown[]) => Promise<QueryResult<T>>;
+/**
+ * Acquires a dedicated connection from the bonded pool. The connection must
+ * be released after use by calling `connection.release()`.
+ *
+ * @returns A database connection that must be released after use.
+ * @throws {Error} If no database pool has been bonded.
+ */
+export declare const connect: () => Promise<DatabaseConnection>;
+/**
+ * Closes all connections in the bonded pool. Call during graceful shutdown.
+ *
+ * @returns A promise that resolves when all connections have been closed.
+ * @throws {Error} If no database pool has been bonded.
+ */
+export declare const end: () => Promise<void>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAK/E;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,YAAY,KAAG,IAE5C,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,QAAO,YAW1B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,QAAO,OAE1B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrD,MAAM,MAAM,EACZ,SAAS,OAAO,EAAE,KACjB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAExB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,QAAa,OAAO,CAAC,kBAAkB,CAE1D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,GAAG,QAAa,OAAO,CAAC,IAAI,CAExC,CAAA"}

package/dist/provider.js

@@ -0,0 +1,77 @@
+/**
+ * Database pool bond accessor and convenience functions for raw SQL queries.
+ *
+ * Bond packages (e.g. `@molecule/api-database-postgresql`) call `setPool()` during setup.
+ * Application code uses `query()` for raw SQL, or the DataStore functions from
+ * `store-provider.ts` for database-agnostic CRUD.
+ *
+ * @module
+ */
+import { bond, expectBond, isBonded, require as bondRequire } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const BOND_TYPE = 'database';
+expectBond(BOND_TYPE);
+/**
+ * Registers a database connection pool as the active singleton. Called by
+ * bond packages during application startup.
+ *
+ * @param pool - The database pool implementation to bond.
+ */
+export const setPool = (pool) => {
+    bond(BOND_TYPE, pool);
+};
+/**
+ * Retrieves the bonded database pool, throwing if none is configured.
+ *
+ * @returns The bonded database pool.
+ * @throws {Error} If no database pool has been bonded.
+ */
+export const getPool = () => {
+    try {
+        return bondRequire(BOND_TYPE);
+    }
+    catch (error) {
+        throw new Error(t('database.error.noProvider', undefined, {
+            defaultValue: 'Database pool not configured. Call setPool() first.',
+        }), { cause: error });
+    }
+};
+/**
+ * Checks whether a database pool is currently bonded.
+ *
+ * @returns `true` if a database pool is bonded.
+ */
+export const hasPool = () => {
+    return isBonded(BOND_TYPE);
+};
+/**
+ * Executes a parameterized SQL query using the bonded pool.
+ *
+ * @param text - SQL query text with placeholders (`$1`, `$2`, etc.).
+ * @param values - Parameter values corresponding to the placeholders.
+ * @returns The query result containing `rows`, `rowCount`, and optional `fields`.
+ * @throws {Error} If no database pool has been bonded.
+ */
+export const query = async (text, values) => {
+    return getPool().query(text, values);
+};
+/**
+ * Acquires a dedicated connection from the bonded pool. The connection must
+ * be released after use by calling `connection.release()`.
+ *
+ * @returns A database connection that must be released after use.
+ * @throws {Error} If no database pool has been bonded.
+ */
+export const connect = async () => {
+    return getPool().connect();
+};
+/**
+ * Closes all connections in the bonded pool. Call during graceful shutdown.
+ *
+ * @returns A promise that resolves when all connections have been closed.
+ * @throws {Error} If no database pool has been bonded.
+ */
+export const end = async () => {
+    return getPool().end();
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACvF,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAItC,MAAM,SAAS,GAAG,UAAU,CAAA;AAC5B,UAAU,CAAC,SAAS,CAAC,CAAA;AAErB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAkB,EAAQ,EAAE;IAClD,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;AACvB,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,GAAiB,EAAE;IACxC,IAAI,CAAC;QACH,OAAO,WAAW,CAAe,SAAS,CAAC,CAAA;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,2BAA2B,EAAE,SAAS,EAAE;YACxC,YAAY,EAAE,qDAAqD;SACpE,CAAC,EACF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,GAAY,EAAE;IACnC,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC5B,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,EACxB,IAAY,EACZ,MAAkB,EACO,EAAE;IAC3B,OAAO,OAAO,EAAE,CAAC,KAAK,CAAI,IAAI,EAAE,MAAM,CAAC,CAAA;AACzC,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,IAAiC,EAAE;IAC7D,OAAO,OAAO,EAAE,CAAC,OAAO,EAAE,CAAA;AAC5B,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,KAAK,IAAmB,EAAE;IAC3C,OAAO,OAAO,EAAE,CAAC,GAAG,EAAE,CAAA;AACxB,CAAC,CAAA"}

package/dist/store-provider.d.ts

@@ -0,0 +1,119 @@
+/**
+ * DataStore bond accessor and convenience functions for database-agnostic CRUD.
+ *
+ * These functions delegate to the bonded `DataStore` implementation, allowing
+ * resource handlers and application code to perform CRUD operations without
+ * knowing which database engine is in use.
+ *
+ * @module
+ */
+import type { DataStore, FindManyOptions, MutationResult, WhereCondition } from './store.js';
+/**
+ * Registers a DataStore implementation as the active singleton. Called by
+ * bond packages during application startup.
+ *
+ * @param store - The DataStore implementation to bond.
+ */
+export declare const setStore: (store: DataStore) => void;
+/**
+ * Retrieves the bonded DataStore, throwing if none is configured.
+ *
+ * @returns The bonded DataStore implementation.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const getStore: () => DataStore;
+/**
+ * Checks whether a DataStore is currently bonded.
+ *
+ * @returns `true` if a DataStore is bonded.
+ */
+export declare const hasStore: () => boolean;
+/**
+ * Finds a single record by its primary key (`id` column).
+ *
+ * @param table - The database table name.
+ * @param id - The primary key value to look up.
+ * @returns The matching record cast to `T`, or `null` if not found.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const findById: <T = Record<string, unknown>>(table: string, id: string | number) => Promise<T | null>;
+/**
+ * Finds a single record matching the given filter conditions. Returns the
+ * first match if multiple rows satisfy the conditions.
+ *
+ * @param table - The database table name.
+ * @param where - Array of filter conditions to match against.
+ * @returns The matching record cast to `T`, or `null` if none found.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const findOne: <T = Record<string, unknown>>(table: string, where: WhereCondition[]) => Promise<T | null>;
+/**
+ * Finds multiple records with optional filtering, sorting, pagination,
+ * and column selection.
+ *
+ * @param table - The database table name.
+ * @param options - Query options including `where`, `orderBy`, `limit`, `offset`, and `select`.
+ * @returns Array of matching records cast to `T`.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const findMany: <T = Record<string, unknown>>(table: string, options?: FindManyOptions) => Promise<T[]>;
+/**
+ * Counts records matching the given filter conditions, or all records
+ * if no conditions are specified.
+ *
+ * @param table - The database table name.
+ * @param where - Optional filter conditions.
+ * @returns The number of matching records.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const count: (table: string, where?: WhereCondition[]) => Promise<number>;
+/**
+ * Inserts a new record into the table. Returns the inserted row and
+ * the number of affected rows (always 1 on success).
+ *
+ * @param table - The database table name.
+ * @param data - The column values to insert as key-value pairs.
+ * @returns A `MutationResult` with the inserted row and affected count.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const create: <T = Record<string, unknown>>(table: string, data: Record<string, unknown>) => Promise<MutationResult<T>>;
+/**
+ * Updates a record identified by its primary key. Returns the updated row
+ * and the number of affected rows.
+ *
+ * @param table - The database table name.
+ * @param id - The primary key value of the record to update.
+ * @param data - The column values to update as key-value pairs.
+ * @returns A `MutationResult` with the updated row and affected count.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const updateById: <T = Record<string, unknown>>(table: string, id: string | number, data: Record<string, unknown>) => Promise<MutationResult<T>>;
+/**
+ * Updates all records matching the given filter conditions.
+ *
+ * @param table - The database table name.
+ * @param where - Filter conditions to select records to update.
+ * @param data - The column values to update as key-value pairs.
+ * @returns A `MutationResult` with the affected count.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const updateMany: (table: string, where: WhereCondition[], data: Record<string, unknown>) => Promise<MutationResult>;
+/**
+ * Deletes a record identified by its primary key.
+ *
+ * @param table - The database table name.
+ * @param id - The primary key value of the record to delete.
+ * @returns A `MutationResult` with the affected count (1 if deleted, 0 if not found).
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const deleteById: (table: string, id: string | number) => Promise<MutationResult>;
+/**
+ * Deletes all records matching the given filter conditions.
+ *
+ * @param table - The database table name.
+ * @param where - Filter conditions to select records to delete.
+ * @returns A `MutationResult` with the number of deleted rows.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export declare const deleteMany: (table: string, where: WhereCondition[]) => Promise<MutationResult>;
+//# sourceMappingURL=store-provider.d.ts.map

package/dist/store-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-provider.d.ts","sourceRoot":"","sources":["../src/store-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAK5F;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,SAAS,KAAG,IAE3C,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAO,SAe3B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,QAAO,OAE3B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxD,OAAO,MAAM,EACb,IAAI,MAAM,GAAG,MAAM,KAClB,OAAO,CAAC,CAAC,GAAG,IAAI,CAElB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvD,OAAO,MAAM,EACb,OAAO,cAAc,EAAE,KACtB,OAAO,CAAC,CAAC,GAAG,IAAI,CAElB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxD,OAAO,MAAM,EACb,UAAU,eAAe,KACxB,OAAO,CAAC,CAAC,EAAE,CAEb,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,GAAU,OAAO,MAAM,EAAE,QAAQ,cAAc,EAAE,KAAG,OAAO,CAAC,MAAM,CAEnF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,OAAO,MAAM,EACb,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAE3B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAU,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,OAAO,MAAM,EACb,IAAI,MAAM,GAAG,MAAM,EACnB,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAE3B,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,MAAM,EACb,OAAO,cAAc,EAAE,EACvB,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,cAAc,CAExB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAU,OAAO,MAAM,EAAE,IAAI,MAAM,GAAG,MAAM,KAAG,OAAO,CAAC,cAAc,CAE3F,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,MAAM,EACb,OAAO,cAAc,EAAE,KACtB,OAAO,CAAC,cAAc,CAExB,CAAA"}

package/dist/store-provider.js

@@ -0,0 +1,157 @@
+/**
+ * DataStore bond accessor and convenience functions for database-agnostic CRUD.
+ *
+ * These functions delegate to the bonded `DataStore` implementation, allowing
+ * resource handlers and application code to perform CRUD operations without
+ * knowing which database engine is in use.
+ *
+ * @module
+ */
+import { bond, expectBond, isBonded, require as bondRequire } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const BOND_TYPE = 'datastore';
+expectBond(BOND_TYPE);
+/**
+ * Registers a DataStore implementation as the active singleton. Called by
+ * bond packages during application startup.
+ *
+ * @param store - The DataStore implementation to bond.
+ */
+export const setStore = (store) => {
+    bond(BOND_TYPE, store);
+};
+/**
+ * Retrieves the bonded DataStore, throwing if none is configured.
+ *
+ * @returns The bonded DataStore implementation.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const getStore = () => {
+    try {
+        return bondRequire(BOND_TYPE);
+    }
+    catch (error) {
+        // Same actionable shape as getPool(): the generic bond error suggests
+        // `bond('datastore', provider)`, but the API this package documents is
+        // `setStore(store)` — point the caller at the actual fix. The locale key
+        // already existed in @molecule/api-locales-database; it was never wired.
+        throw new Error(t('database.error.storeNotConfigured', undefined, {
+            defaultValue: 'DataStore not configured. Call setStore() first.',
+        }), { cause: error });
+    }
+};
+/**
+ * Checks whether a DataStore is currently bonded.
+ *
+ * @returns `true` if a DataStore is bonded.
+ */
+export const hasStore = () => {
+    return isBonded(BOND_TYPE);
+};
+/**
+ * Finds a single record by its primary key (`id` column).
+ *
+ * @param table - The database table name.
+ * @param id - The primary key value to look up.
+ * @returns The matching record cast to `T`, or `null` if not found.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const findById = async (table, id) => {
+    return getStore().findById(table, id);
+};
+/**
+ * Finds a single record matching the given filter conditions. Returns the
+ * first match if multiple rows satisfy the conditions.
+ *
+ * @param table - The database table name.
+ * @param where - Array of filter conditions to match against.
+ * @returns The matching record cast to `T`, or `null` if none found.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const findOne = async (table, where) => {
+    return getStore().findOne(table, where);
+};
+/**
+ * Finds multiple records with optional filtering, sorting, pagination,
+ * and column selection.
+ *
+ * @param table - The database table name.
+ * @param options - Query options including `where`, `orderBy`, `limit`, `offset`, and `select`.
+ * @returns Array of matching records cast to `T`.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const findMany = async (table, options) => {
+    return getStore().findMany(table, options);
+};
+/**
+ * Counts records matching the given filter conditions, or all records
+ * if no conditions are specified.
+ *
+ * @param table - The database table name.
+ * @param where - Optional filter conditions.
+ * @returns The number of matching records.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const count = async (table, where) => {
+    return getStore().count(table, where);
+};
+/**
+ * Inserts a new record into the table. Returns the inserted row and
+ * the number of affected rows (always 1 on success).
+ *
+ * @param table - The database table name.
+ * @param data - The column values to insert as key-value pairs.
+ * @returns A `MutationResult` with the inserted row and affected count.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const create = async (table, data) => {
+    return getStore().create(table, data);
+};
+/**
+ * Updates a record identified by its primary key. Returns the updated row
+ * and the number of affected rows.
+ *
+ * @param table - The database table name.
+ * @param id - The primary key value of the record to update.
+ * @param data - The column values to update as key-value pairs.
+ * @returns A `MutationResult` with the updated row and affected count.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const updateById = async (table, id, data) => {
+    return getStore().updateById(table, id, data);
+};
+/**
+ * Updates all records matching the given filter conditions.
+ *
+ * @param table - The database table name.
+ * @param where - Filter conditions to select records to update.
+ * @param data - The column values to update as key-value pairs.
+ * @returns A `MutationResult` with the affected count.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const updateMany = async (table, where, data) => {
+    return getStore().updateMany(table, where, data);
+};
+/**
+ * Deletes a record identified by its primary key.
+ *
+ * @param table - The database table name.
+ * @param id - The primary key value of the record to delete.
+ * @returns A `MutationResult` with the affected count (1 if deleted, 0 if not found).
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const deleteById = async (table, id) => {
+    return getStore().deleteById(table, id);
+};
+/**
+ * Deletes all records matching the given filter conditions.
+ *
+ * @param table - The database table name.
+ * @param where - Filter conditions to select records to delete.
+ * @returns A `MutationResult` with the number of deleted rows.
+ * @throws {Error} If no DataStore has been bonded.
+ */
+export const deleteMany = async (table, where) => {
+    return getStore().deleteMany(table, where);
+};
+//# sourceMappingURL=store-provider.js.map

package/dist/store-provider.js.map

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

package/dist/store.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Abstract data store interface.
+ *
+ * Database-agnostic CRUD operations. Each database bond
+ * (PostgreSQL, MongoDB, DynamoDB, etc.) implements these
+ * methods using its native query language.
+ *
+ * For complex queries not covered by this interface,
+ * use the raw DatabasePool.query() method instead.
+ *
+ * @module
+ */
+/**
+ * Filter condition for queries.
+ */
+export interface WhereCondition {
+    field: string;
+    operator: '=' | '!=' | '>' | '<' | '>=' | '<=' | 'in' | 'not_in'
+    /**
+     * Case-insensitive SQL pattern match. `value` is used AS-IS as the raw
+     * LIKE pattern: `%` matches any run of characters, `_` matches any
+     * single character, and the CALLER is responsible for escaping any
+     * literal `%` / `_` / `\` they don't want treated as wildcards. All
+     * three first-party bonds (postgresql, mysql, sqlite) implement `like`
+     * case-INSENSITIVELY — postgres via `ILIKE`, mysql/sqlite via
+     * `LOWER()` on both sides — specifically so this operator has
+     * IDENTICAL results across every bond regardless of column collation
+     * or `PRAGMA case_sensitive_like`. Prior to this contract the postgres
+     * bond escaped the value (making `like` an exact-match operator there
+     * only) while sqlite/mysql passed it through raw — the same `{
+     * operator: 'like', value: `%${search}%` }` filter silently matched
+     * nothing on postgres and worked everywhere else. For human-typed
+     * search input where the value should be a literal substring (not a
+     * pattern the caller controls), use `ilike` instead — it escapes
+     * wildcards and wraps `%…%` for you, so it is injection-safe for
+     * arbitrary user text.
+     */
+     | 'like'
+    /**
+     * Case-insensitive substring match. The value is treated as a
+     * literal substring (LIKE wildcards in the value are escaped) and
+     * the bond wraps it with `%…%` to perform a contains-style match.
+     * Use this for human-typed search input where case shouldn't matter.
+     */
+     | 'ilike' | 'is_null' | 'is_not_null';
+    value?: unknown;
+}
+/**
+ * Column sort order (field name and ascending/descending direction).
+ */
+export interface OrderBy {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/**
+ * Options for findMany queries.
+ */
+export interface FindManyOptions {
+    where?: WhereCondition[];
+    orderBy?: OrderBy[];
+    limit?: number;
+    offset?: number;
+    select?: string[];
+}
+/**
+ * Result of a mutation operation.
+ */
+export interface MutationResult<T = Record<string, unknown>> {
+    /** The affected/returned row, if any. */
+    data: T | null;
+    /** Number of rows affected. */
+    affected: number;
+}
+/**
+ * Abstract data store interface.
+ *
+ * Provides database-agnostic CRUD methods. Each database bond
+ * implements these using its native query language.
+ */
+export interface DataStore {
+    /**
+     * Find a single record by its primary key.
+     */
+    findById<T = Record<string, unknown>>(table: string, id: string | number): Promise<T | null>;
+    /**
+     * Find a single record matching conditions.
+     */
+    findOne<T = Record<string, unknown>>(table: string, where: WhereCondition[]): Promise<T | null>;
+    /**
+     * Find many records with filtering, sorting, and pagination.
+     */
+    findMany<T = Record<string, unknown>>(table: string, options?: FindManyOptions): Promise<T[]>;
+    /**
+     * Count records matching conditions.
+     */
+    count(table: string, where?: WhereCondition[]): Promise<number>;
+    /**
+     * Insert a new record. Returns the inserted row.
+     */
+    create<T = Record<string, unknown>>(table: string, data: Record<string, unknown>): Promise<MutationResult<T>>;
+    /**
+     * Update a record by primary key. Returns the updated row.
+     */
+    updateById<T = Record<string, unknown>>(table: string, id: string | number, data: Record<string, unknown>): Promise<MutationResult<T>>;
+    /**
+     * Update records matching conditions.
+     */
+    updateMany(table: string, where: WhereCondition[], data: Record<string, unknown>): Promise<MutationResult>;
+    /**
+     * Delete a record by primary key.
+     */
+    deleteById(table: string, id: string | number): Promise<MutationResult>;
+    /**
+     * Delete records matching conditions.
+     */
+    deleteMany(table: string, where: WhereCondition[]): Promise<MutationResult>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

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

package/dist/store.js

@@ -0,0 +1,14 @@
+/**
+ * Abstract data store interface.
+ *
+ * Database-agnostic CRUD operations. Each database bond
+ * (PostgreSQL, MongoDB, DynamoDB, etc.) implements these
+ * methods using its native query language.
+ *
+ * For complex queries not covered by this interface,
+ * use the raw DatabasePool.query() method instead.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Type definitions for database core interface.
+ *
+ * @module
+ */
+/**
+ * Query result with rows and metadata.
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+    /**
+     * Array of rows returned by the query.
+     */
+    rows: T[];
+    /**
+     * Number of rows affected (for INSERT, UPDATE, DELETE).
+     */
+    rowCount: number | null;
+    /**
+     * Column metadata (optional, provider-dependent).
+     */
+    fields?: Array<{
+        name: string;
+        dataTypeID?: number;
+    }>;
+}
+/**
+ * Database connection interface.
+ */
+export interface DatabaseConnection {
+    /**
+     * Executes a parameterized query.
+     *
+     * @param text - SQL query text with placeholders ($1, $2, etc.)
+     * @param values - Parameter values
+     */
+    query<T = Record<string, unknown>>(text: string, values?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Releases the connection back to the pool.
+     */
+    release(): void;
+}
+/**
+ * Database transaction with commit and rollback (extends DatabaseConnection).
+ */
+export interface DatabaseTransaction extends DatabaseConnection {
+    /**
+     * Commits the transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rolls back the transaction.
+     */
+    rollback(): Promise<void>;
+}
+/**
+ * Database pool interface.
+ *
+ * All database providers must implement this interface.
+ */
+export interface DatabasePool {
+    /**
+     * Executes a parameterized query using a pool connection.
+     *
+     * @param text - SQL query text with placeholders ($1, $2, etc.)
+     * @param values - Parameter values
+     */
+    query<T = Record<string, unknown>>(text: string, values?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Acquires a connection from the pool.
+     */
+    connect(): Promise<DatabaseConnection>;
+    /**
+     * Begins a transaction.
+     */
+    transaction?(): Promise<DatabaseTransaction>;
+    /**
+     * Closes all connections in the pool.
+     */
+    end(): Promise<void>;
+    /**
+     * Returns pool statistics (optional).
+     */
+    stats?(): {
+        total: number;
+        idle: number;
+        waiting: number;
+    };
+}
+/**
+ * Database provider interface.
+ */
+export interface DatabaseProvider {
+    /**
+     * The connection pool.
+     */
+    pool: DatabasePool;
+    /**
+     * Creates a new pool with the given configuration.
+     */
+    createPool?(config: DatabaseConfig): DatabasePool;
+}
+/**
+ * Database connection options (host, port, credentials, pool size, timeouts, SSL).
+ */
+export interface DatabaseConfig {
+    /**
+     * Database host.
+     */
+    host?: string;
+    /**
+     * Database port.
+     */
+    port?: number;
+    /**
+     * Database name.
+     */
+    database?: string;
+    /**
+     * Database user.
+     */
+    user?: string;
+    /**
+     * Database password.
+     */
+    password?: string;
+    /**
+     * Connection string (alternative to individual fields).
+     */
+    connectionString?: string;
+    /**
+     * Maximum number of connections in the pool.
+     */
+    max?: number;
+    /**
+     * Minimum number of connections in the pool.
+     */
+    min?: number;
+    /**
+     * Connection timeout in milliseconds.
+     */
+    connectionTimeoutMillis?: number;
+    /**
+     * Idle timeout in milliseconds.
+     */
+    idleTimeoutMillis?: number;
+    /**
+     * Enable SSL.
+     */
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+        ca?: string;
+        key?: string;
+        cert?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD;;OAEG;IACH,IAAI,EAAE,CAAC,EAAE,CAAA;IAET;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEvB;;OAEG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,CAAC,CAAA;CACH;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IAE7F;;OAEG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvB;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IAE7F;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAEtC;;OAEG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAE5C;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpB;;OAEG;IACH,KAAK,CAAC,IAAI;QACR,KAAK,EAAE,MAAM,CAAA;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,IAAI,EAAE,YAAY,CAAA;IAElB;;OAEG;IACH,UAAU,CAAC,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAAA;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAEhC;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;OAEG;IACH,GAAG,CAAC,EACA,OAAO,GACP;QACE,kBAAkB,CAAC,EAAE,OAAO,CAAA;QAC5B,EAAE,CAAC,EAAE,MAAM,CAAA;QACX,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,IAAI,CAAC,EAAE,MAAM,CAAA;KACd,CAAA;CACN"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for database core interface.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@molecule/api-database",
+  "version": "1.0.0",
+  "description": "Database core interface for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "database",
+    "sql",
+    "postgresql",
+    "mysql"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/core/database"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/core/database",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}