@molecule/api-database 1.1.0 → 1.1.1

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-15T12:34:32.789Z
+Generated: 2026-10-16T00:26:28.689Z
 -->
 
 # @molecule/api-database
@@ -61,73 +61,183 @@ npm install @molecule/api-database @molecule/api-bond @molecule/api-i18n
 
 ### Interfaces
 
-#### `DatabaseConfig`
+#### `WhereCondition`
 
-Database connection options (host, port, credentials, pool size, timeouts, SSL).
+Filter condition for queries.
 
 ```typescript
-interface DatabaseConfig {
+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
+}
+```
+
+#### `OrderBy`
+
+Column sort order (field name and ascending/descending direction).
+
+```typescript
+interface OrderBy {
+  field: string
+  direction: 'asc' | 'desc'
+}
+```
+
+#### `FindManyOptions`
+
+Options for findMany queries.
+
+```typescript
+interface FindManyOptions {
+  where?: WhereCondition[]
+  orderBy?: OrderBy[]
+  limit?: number
+  offset?: number
+  select?: string[]
+}
+```
+
+#### `MutationResult`
+
+Result of a mutation operation.
+
+```typescript
+interface MutationResult<T = Record<string, unknown>> {
+  /** The affected/returned row, if any. */
+  data: T | null
+  /** Number of rows affected. */
+  affected: number
+}
+```
+
+#### `DataStore`
+
+Abstract data store interface.
+
+Provides database-agnostic CRUD methods. Each database bond
+implements these using its native query language.
+
+```typescript
+interface DataStore {
   /**
-   * Database host.
+   * Find a single record by its primary key.
    */
-  host?: string
+  findById<T = Record<string, unknown>>(table: string, id: string | number): Promise<T | null>
 
   /**
-   * Database port.
+   * Find a single record matching conditions.
    */
-  port?: number
+  findOne<T = Record<string, unknown>>(table: string, where: WhereCondition[]): Promise<T | null>
 
   /**
-   * Database name.
+   * Find many records with filtering, sorting, and pagination.
    */
-  database?: string
+  findMany<T = Record<string, unknown>>(table: string, options?: FindManyOptions): Promise<T[]>
 
   /**
-   * Database user.
+   * Count records matching conditions.
    */
-  user?: string
+  count(table: string, where?: WhereCondition[]): Promise<number>
 
   /**
-   * Database password.
+   * Insert a new record. Returns the inserted row.
    */
-  password?: string
+  create<T = Record<string, unknown>>(
+    table: string,
+    data: Record<string, unknown>,
+  ): Promise<MutationResult<T>>
 
   /**
-   * Connection string (alternative to individual fields).
+   * Update a record by primary key. Returns the updated row.
    */
-  connectionString?: string
+  updateById<T = Record<string, unknown>>(
+    table: string,
+    id: string | number,
+    data: Record<string, unknown>,
+  ): Promise<MutationResult<T>>
 
   /**
-   * Maximum number of connections in the pool.
+   * Update records matching conditions.
    */
-  max?: number
+  updateMany(
+    table: string,
+    where: WhereCondition[],
+    data: Record<string, unknown>,
+  ): Promise<MutationResult>
 
   /**
-   * Minimum number of connections in the pool.
+   * Delete a record by primary key.
    */
-  min?: number
+  deleteById(table: string, id: string | number): Promise<MutationResult>
 
   /**
-   * Connection timeout in milliseconds.
+   * Delete records matching conditions.
    */
-  connectionTimeoutMillis?: number
+  deleteMany(table: string, where: WhereCondition[]): Promise<MutationResult>
+}
+```
+
+#### `QueryResult`
+
+Query result with rows and metadata.
 
+```typescript
+interface QueryResult<T = Record<string, unknown>> {
   /**
-   * Idle timeout in milliseconds.
+   * Array of rows returned by the query.
    */
-  idleTimeoutMillis?: number
+  rows: T[]
 
   /**
-   * Enable SSL.
+   * Number of rows affected (for INSERT, UPDATE, DELETE).
    */
-  ssl?:
-    | boolean
-    | {
-        rejectUnauthorized?: boolean
-        ca?: string
-        key?: string
-        cert?: string
-      }
+  rowCount: number | null
+
+  /**
+   * Column metadata (optional, provider-dependent).
+   */
+  fields?: Array<{
+    name: string
+    dataTypeID?: number
+  }>
 }
 ```
 
@@ -152,6 +262,24 @@ interface DatabaseConnection {
 }
 ```
 
+#### `DatabaseTransaction`
+
+Database transaction with commit and rollback (extends DatabaseConnection).
+
+```typescript
+interface DatabaseTransaction extends DatabaseConnection {
+  /**
+   * Commits the transaction.
+   */
+  commit(): Promise<void>
+
+  /**
+   * Rolls back the transaction.
+   */
+  rollback(): Promise<void>
+}
+```
+
 #### `DatabasePool`
 
 Database pool interface.
@@ -212,205 +340,121 @@ interface DatabaseProvider {
 }
 ```
 
-#### `DatabaseTransaction`
+#### `DatabaseConfig`
 
-Database transaction with commit and rollback (extends DatabaseConnection).
+Database connection options (host, port, credentials, pool size, timeouts, SSL).
 
 ```typescript
-interface DatabaseTransaction extends DatabaseConnection {
+interface DatabaseConfig {
   /**
-   * Commits the transaction.
+   * Database host.
    */
-  commit(): Promise<void>
+  host?: string
 
   /**
-   * Rolls back the transaction.
+   * Database port.
    */
-  rollback(): Promise<void>
-}
-```
-
-#### `DataStore`
-
-Abstract data store interface.
-
-Provides database-agnostic CRUD methods. Each database bond
-implements these using its native query language.
+  port?: number
 
-```typescript
-interface DataStore {
   /**
-   * Find a single record by its primary key.
+   * Database name.
    */
-  findById<T = Record<string, unknown>>(table: string, id: string | number): Promise<T | null>
+  database?: string
 
   /**
-   * Find a single record matching conditions.
+   * Database user.
    */
-  findOne<T = Record<string, unknown>>(table: string, where: WhereCondition[]): Promise<T | null>
+  user?: string
 
   /**
-   * Find many records with filtering, sorting, and pagination.
+   * Database password.
    */
-  findMany<T = Record<string, unknown>>(table: string, options?: FindManyOptions): Promise<T[]>
+  password?: string
 
   /**
-   * Count records matching conditions.
+   * Connection string (alternative to individual fields).
    */
-  count(table: string, where?: WhereCondition[]): Promise<number>
+  connectionString?: string
 
   /**
-   * Insert a new record. Returns the inserted row.
+   * Maximum number of connections in the pool.
    */
-  create<T = Record<string, unknown>>(
-    table: string,
-    data: Record<string, unknown>,
-  ): Promise<MutationResult<T>>
+  max?: number
 
   /**
-   * Update a record by primary key. Returns the updated row.
+   * Minimum number of connections in the pool.
    */
-  updateById<T = Record<string, unknown>>(
-    table: string,
-    id: string | number,
-    data: Record<string, unknown>,
-  ): Promise<MutationResult<T>>
+  min?: number
 
   /**
-   * Update records matching conditions.
+   * Connection timeout in milliseconds.
    */
-  updateMany(
-    table: string,
-    where: WhereCondition[],
-    data: Record<string, unknown>,
-  ): Promise<MutationResult>
+  connectionTimeoutMillis?: number
 
   /**
-   * Delete a record by primary key.
+   * Idle timeout in milliseconds.
    */
-  deleteById(table: string, id: string | number): Promise<MutationResult>
+  idleTimeoutMillis?: number
 
   /**
-   * Delete records matching conditions.
+   * Enable SSL.
    */
-  deleteMany(table: string, where: WhereCondition[]): Promise<MutationResult>
+  ssl?:
+    | boolean
+    | {
+        rejectUnauthorized?: boolean
+        ca?: string
+        key?: string
+        cert?: string
+      }
 }
 ```
 
-#### `FindManyOptions`
-
-Options for findMany queries.
-
-```typescript
-interface FindManyOptions {
-  where?: WhereCondition[]
-  orderBy?: OrderBy[]
-  limit?: number
-  offset?: number
-  select?: string[]
-}
-```
+### Functions
 
-#### `MutationResult`
+#### `setPool(pool)`
 
-Result of a mutation operation.
+Registers a database connection pool as the active singleton. Called by
+bond packages during application startup.
 
 ```typescript
-interface MutationResult<T = Record<string, unknown>> {
-  /** The affected/returned row, if any. */
-  data: T | null
-  /** Number of rows affected. */
-  affected: number
-}
+function setPool(pool: DatabasePool): void
 ```
 
-#### `OrderBy`
+- `pool` — The database pool implementation to bond.
 
-Column sort order (field name and ascending/descending direction).
+#### `getPool()`
+
+Retrieves the bonded database pool, throwing if none is configured.
 
 ```typescript
-interface OrderBy {
-  field: string
-  direction: 'asc' | 'desc'
-}
+function getPool(): DatabasePool
 ```
 
-#### `QueryResult`
-
-Query result with rows and metadata.
+**Returns:** The bonded database pool.
 
-```typescript
-interface QueryResult<T = Record<string, unknown>> {
-  /**
-   * Array of rows returned by the query.
-   */
-  rows: T[]
+#### `hasPool()`
 
-  /**
-   * Number of rows affected (for INSERT, UPDATE, DELETE).
-   */
-  rowCount: number | null
+Checks whether a database pool is currently bonded.
 
-  /**
-   * Column metadata (optional, provider-dependent).
-   */
-  fields?: Array<{
-    name: string
-    dataTypeID?: number
-  }>
-}
+```typescript
+function hasPool(): boolean
 ```
 
-#### `WhereCondition`
+**Returns:** `true` if a database pool is bonded.
 
-Filter condition for queries.
+#### `query(text, values)`
+
+Executes a parameterized SQL query using the bonded pool.
 
 ```typescript
-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
-}
+function query(text: string, values?: unknown[]): Promise<QueryResult<T>>
 ```
 
-### Functions
+- `text` — SQL query text with placeholders (`$1`, `$2`, etc.).
+- `values` — Parameter values corresponding to the placeholders.
+
+**Returns:** The query result containing `rows`, `rowCount`, and optional `fields`.
 
 #### `connect()`
 
@@ -423,75 +467,46 @@ function connect(): Promise<DatabaseConnection>
 
 **Returns:** A database connection that must be released after use.
 
-#### `count(table, where)`
-
-Counts records matching the given filter conditions, or all records
-if no conditions are specified.
-
-```typescript
-function count(table: string, where?: WhereCondition[]): Promise<number>
-```
-
-- `table` — The database table name.
-- `where` — Optional filter conditions.
-
-**Returns:** The number of matching records.
-
-#### `create(table, data)`
+#### `end()`
 
-Inserts a new record into the table. Returns the inserted row and
-the number of affected rows (always 1 on success).
+Closes all connections in the bonded pool. Call during graceful shutdown.
 
 ```typescript
-function create(table: string, data: Record<string, unknown>): Promise<MutationResult<T>>
+function end(): Promise<void>
 ```
 
-- `table` — The database table name.
-- `data` — The column values to insert as key-value pairs.
-
-**Returns:** A `MutationResult` with the inserted row and affected count.
+**Returns:** A promise that resolves when all connections have been closed.
 
-#### `deleteById(table, id)`
+#### `setStore(store)`
 
-Deletes a record identified by its primary key.
+Registers a DataStore implementation as the active singleton. Called by
+bond packages during application startup.
 
 ```typescript
-function deleteById(
-  table: string,
-  id: string | number,
-): Promise<MutationResult<Record<string, unknown>>>
+function setStore(store: DataStore): void
 ```
 
-- `table` — The database table name.
-- `id` — The primary key value of the record to delete.
-
-**Returns:** A `MutationResult` with the affected count (1 if deleted, 0 if not found).
+- `store` — The DataStore implementation to bond.
 
-#### `deleteMany(table, where)`
+#### `getStore()`
 
-Deletes all records matching the given filter conditions.
+Retrieves the bonded DataStore, throwing if none is configured.
 
 ```typescript
-function deleteMany(
-  table: string,
-  where: WhereCondition[],
-): Promise<MutationResult<Record<string, unknown>>>
+function getStore(): DataStore
 ```
 
-- `table` — The database table name.
-- `where` — Filter conditions to select records to delete.
-
-**Returns:** A `MutationResult` with the number of deleted rows.
+**Returns:** The bonded DataStore implementation.
 
-#### `end()`
+#### `hasStore()`
 
-Closes all connections in the bonded pool. Call during graceful shutdown.
+Checks whether a DataStore is currently bonded.
 
 ```typescript
-function end(): Promise<void>
+function hasStore(): boolean
 ```
 
-**Returns:** A promise that resolves when all connections have been closed.
+**Returns:** `true` if a DataStore is bonded.
 
 #### `findById(table, id)`
 
@@ -506,20 +521,6 @@ function findById(table: string, id: string | number): Promise<T | null>
 
 **Returns:** The matching record cast to `T`, or `null` if not found.
 
-#### `findMany(table, options)`
-
-Finds multiple records with optional filtering, sorting, pagination,
-and column selection.
-
-```typescript
-function findMany(table: string, options?: FindManyOptions): Promise<T[]>
-```
-
-- `table` — The database table name.
-- `options` — Query options including `where`, `orderBy`, `limit`, `offset`, and `select`.
-
-**Returns:** Array of matching records cast to `T`.
-
 #### `findOne(table, where)`
 
 Finds a single record matching the given filter conditions. Returns the
@@ -534,92 +535,47 @@ function findOne(table: string, where: WhereCondition[]): Promise<T | null>
 
 **Returns:** The matching record cast to `T`, or `null` if none found.
 
-#### `getActiveTransaction()`
-
-The transaction opened by the enclosing `withTransaction()` call, if any.
-Bond pools call this from `query()` and send the statement to the active
-transaction when it is one they opened.
-
-```typescript
-function getActiveTransaction(): DatabaseTransaction | undefined
-```
-
-**Returns:** The active transaction, or `undefined` outside `withTransaction()`.
-
-#### `getPool()`
-
-Retrieves the bonded database pool, throwing if none is configured.
-
-```typescript
-function getPool(): DatabasePool
-```
-
-**Returns:** The bonded database pool.
-
-#### `getStore()`
-
-Retrieves the bonded DataStore, throwing if none is configured.
-
-```typescript
-function getStore(): DataStore
-```
-
-**Returns:** The bonded DataStore implementation.
-
-#### `hasPool()`
+#### `findMany(table, options)`
 
-Checks whether a database pool is currently bonded.
+Finds multiple records with optional filtering, sorting, pagination,
+and column selection.
 
 ```typescript
-function hasPool(): boolean
+function findMany(table: string, options?: FindManyOptions): Promise<T[]>
 ```
 
-**Returns:** `true` if a database pool is bonded.
-
-#### `hasStore()`
-
-Checks whether a DataStore is currently bonded.
-
-```typescript
-function hasStore(): boolean
-```
+- `table` — The database table name.
+- `options` — Query options including `where`, `orderBy`, `limit`, `offset`, and `select`.
 
-**Returns:** `true` if a DataStore is bonded.
+**Returns:** Array of matching records cast to `T`.
 
-#### `query(text, values)`
+#### `count(table, where)`
 
-Executes a parameterized SQL query using the bonded pool.
+Counts records matching the given filter conditions, or all records
+if no conditions are specified.
 
 ```typescript
-function query(text: string, values?: unknown[]): Promise<QueryResult<T>>
+function count(table: string, where?: WhereCondition[]): Promise<number>
 ```
 
-- `text` — SQL query text with placeholders (`$1`, `$2`, etc.).
-- `values` — Parameter values corresponding to the placeholders.
+- `table` — The database table name.
+- `where` — Optional filter conditions.
 
-**Returns:** The query result containing `rows`, `rowCount`, and optional `fields`.
+**Returns:** The number of matching records.
 
-#### `setPool(pool)`
+#### `create(table, data)`
 
-Registers a database connection pool as the active singleton. Called by
-bond packages during application startup.
+Inserts a new record into the table. Returns the inserted row and
+the number of affected rows (always 1 on success).
 
 ```typescript
-function setPool(pool: DatabasePool): void
+function create(table: string, data: Record<string, unknown>): Promise<MutationResult<T>>
 ```
 
-- `pool` — The database pool implementation to bond.
-
-#### `setStore(store)`
-
-Registers a DataStore implementation as the active singleton. Called by
-bond packages during application startup.
-
-```typescript
-function setStore(store: DataStore): void
-```
+- `table` — The database table name.
+- `data` — The column values to insert as key-value pairs.
 
-- `store` — The DataStore implementation to bond.
+**Returns:** A `MutationResult` with the inserted row and affected count.
 
 #### `updateById(table, id, data)`
 
@@ -658,6 +614,50 @@ function updateMany(
 
 **Returns:** A `MutationResult` with the affected count.
 
+#### `deleteById(table, id)`
+
+Deletes a record identified by its primary key.
+
+```typescript
+function deleteById(
+  table: string,
+  id: string | number,
+): Promise<MutationResult<Record<string, unknown>>>
+```
+
+- `table` — The database table name.
+- `id` — The primary key value of the record to delete.
+
+**Returns:** A `MutationResult` with the affected count (1 if deleted, 0 if not found).
+
+#### `deleteMany(table, where)`
+
+Deletes all records matching the given filter conditions.
+
+```typescript
+function deleteMany(
+  table: string,
+  where: WhereCondition[],
+): Promise<MutationResult<Record<string, unknown>>>
+```
+
+- `table` — The database table name.
+- `where` — Filter conditions to select records to delete.
+
+**Returns:** A `MutationResult` with the number of deleted rows.
+
+#### `getActiveTransaction()`
+
+The transaction opened by the enclosing `withTransaction()` call, if any.
+Bond pools call this from `query()` and send the statement to the active
+transaction when it is one they opened.
+
+```typescript
+function getActiveTransaction(): DatabaseTransaction | undefined
+```
+
+**Returns:** The active transaction, or `undefined` outside `withTransaction()`.
+
 #### `withTransaction(fn)`
 
 Runs `fn` inside one database transaction: commits when it resolves, rolls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-database",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Database core interface for molecule.dev",
   "type": "module",
   "main": "dist/index.js",