@starbemtech/star-db-query-builder 1.3.0 → 1.4.0

package/.claude/skills/star-db-query-builder/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: star-db-query-builder
+description: >
+  Use this skill whenever writing, reviewing, or debugging code that uses
+  `@starbemtech/star-db-query-builder` (Starbem's internal Postgres/MySQL query
+  builder) — importing it, calling initDb/findFirst/findMany/findManyCursor/
+  insert/insertMany/update/updateMany/upsert/deleteOne/deleteMany/joins/rawQuery/
+  withTransaction, or adding a new backend service endpoint that needs a
+  database query. Also use it when asked to "use the query builder", "add a
+  query with star-db-query-builder", or when a file already imports from
+  `@starbemtech/star-db-query-builder`. DO NOT use for Prisma/Knex/TypeORM code,
+  and do not use it to modify the library's own source (that's a repo working
+  directly in `libs/star-db-query-builder` — see its AGENTS.md instead).
+---
+
+# star-db-query-builder usage
+
+Function-based SQL query builder for Postgres (`pg`) and MySQL (`mysql2`). No ORM. You write against a typed function API; the library builds parameterized SQL for you. This skill exists so agents write **correct** calls on the first try instead of guessing an API shape that doesn't exist.
+
+Full reference: `docs/methods/*.md` and `README.md` in the library repo (`starbem/star-db-query-builder`). This skill is the fast-path summary — when in doubt on an edge case, read the actual doc file for that method rather than guessing.
+
+## Setup
+
+```ts
+import { initDb, getDbClient } from '@starbemtech/star-db-query-builder'
+
+await initDb({
+  type: 'pg', // or 'mysql' — NOT 'postgres', that string throws "Unsupported database type"
+  options: { host, port, user, password, database },
+  // optional: name (for multiple named connections), retryOptions, queryTimeout,
+  // installUnaccentExtension (pg only)
+})
+
+const dbClient = getDbClient() // or getDbClient('name') for a named connection
+```
+
+Every query function below takes `dbClient` explicitly — it is not implicit/global per call.
+
+## Core functions
+
+```ts
+findFirst({ tableName, dbClient, where?, select?, orderBy?, groupBy? })      // -> T | null, always LIMIT 1
+findMany({ tableName, dbClient, where?, select?, orderBy?, groupBy?, limit?, offset?, unaccent? })  // -> T[]
+findManyCursor({ tableName, dbClient, cursorField, cursor?, limit, direction?, where?, select? })   // -> { data, nextCursor }
+insert({ tableName, dbClient, data, returning? })          // single row, all column names auto-quoted
+insertMany({ tableName, dbClient, data: T[], returning? })  // batch insert, every item must share the same keys
+update({ tableName, dbClient, id, data })                   // SET col = literal value only, see gotcha below
+updateMany({ tableName, dbClient, where, data })
+upsert({ tableName, dbClient, data, conflictFields, updateFields?, returning? })
+deleteOne({ tableName, dbClient, id, permanently? })         // soft delete by default (sets status = 'deleted'), permanently=true for hard delete
+deleteMany({ tableName, dbClient, ids, field? })             // field defaults to 'id'
+joins({ tableName, dbClient, joins: [...], where?, select?, orderBy?, groupBy?, limit?, offset? })
+rawQuery({ dbClient, sql, params? })                         // escape hatch — you write the SQL, still parameterized
+withTransaction(dbClient, async (txClient) => { ... })       // auto commit/rollback
+```
+
+## Gotchas that will produce wrong or broken code if ignored
+
+1. **`update()`/`updateMany()` do NOT support arithmetic updates.** `data: { stock: { operator: '-', value: qty } }` is not interpreted — it is not a supported shape at all. If you need `stock = stock - qty`, read the current value first (`findFirst`), compute in JS, then pass the literal result:
+   ```ts
+   const row = await findFirst({ tableName: 'products', dbClient, where: { id: { operator: '=', value: productId } } })
+   await update({ tableName: 'products', dbClient, id: productId, data: { stock: row.stock - qty } })
+   ```
+   Do this inside `withTransaction` if it must be atomic against concurrent writes — the library does not do this for you.
+
+2. **`joins()` has no `having` parameter.** `QueryParams<T>` doesn't declare one, so `joins({ ..., having: {...} })` is a TypeScript type error, not a runtime no-op. For HAVING, use `rawQuery`.
+
+3. **`JOINS` inside a `Conditions<T>` `where` object is NOT a SQL JOIN.** It's a nested AND-group of conditions, unfortunately named. If you want an actual SQL join, use the `joins()` function, not a `JOINS` key inside `where`.
+
+4. **`upsert()` on MySQL does not put `conflictFields` in the generated SQL.** MySQL's `ON DUPLICATE KEY UPDATE` relies entirely on the table's real unique/PK constraint — `conflictFields` is only used to re-select the row afterward (MySQL has no `RETURNING`). The function does not create or verify that the constraint exists. Before using `upsert`, confirm the target table actually has a unique constraint or PK on the fields you're passing as `conflictFields` — otherwise MySQL will just insert duplicates.
+
+5. **Table/column/field names go through strict identifier validation** (`assertValidIdentifier` for `tableName`, `join.table`, `deleteMany.field`, `data` keys in `insert`/`insertMany`/`upsert`/`update`/`updateMany`, and `where` field names; a looser `assertSafeSqlFragment` for `select`/`groupBy`/`orderBy.field`/`join.on`/`where` `NOT EXISTS` subqueries that still allows real SQL expressions like `COUNT(*) as count`). Never build these strings by concatenating unsanitized user input yourself and passing them in expecting the library to catch it silently — it throws on invalid identifiers, so validate/allowlist at your own layer too if the name comes from user input.
+
+6. **`findManyCursor()` is a separate function, not a `findMany()` option.** Its return shape is `{ data, nextCursor }`, not a bare array — don't destructure it like `findMany`'s return.
+
+7. **Values are always parameterized — never string-interpolate a value into `where`/`data`.** The library already does this correctly for you; the mistake to avoid is bypassing it via `rawQuery` with interpolated strings instead of `params`.
+
+8. **Every `where` condition must be `{ operator, value }` — a plain value throws, it is not silently ignored.** `where: { status: 'active' }` throws `Invalid where condition for "status"`; use `where: { status: { operator: '=', value: 'active' } }`. This matters most on `updateMany`/`deleteMany`: getting the shape wrong used to silently drop the condition and run the write against every row in the table — now it throws instead, but write your conditions correctly rather than relying on the error.
+
+9. **`IN`/`NOT IN`/`BETWEEN` cap at 10,000 values in `value`**, throwing a descriptive error past that — chunk the list instead of forwarding an unbounded array (e.g. raw search results) as a single condition. `BETWEEN` additionally requires exactly 2 values.
+
+## Where conditions (`Conditions<T>`)
+
+Every condition is `{ operator, value }` — there is no `{ EQUALS: x }` / `{ IN: [...] }` shorthand, that shape does not exist in the code:
+
+```ts
+where: {
+  id: { operator: '=', value: someId },
+  status: { operator: 'IN', value: ['active', 'pending'] },
+  createdAt: { operator: 'BETWEEN', value: [start, end] },
+  name: { operator: 'ILIKE', value: '%term%' },   // add unaccent: true on findMany/joins to also strip accents (pg only)
+  deletedAt: { operator: 'IS NULL', value: null },
+  OR: [
+    { email: { operator: '=', value: a } },
+    { email: { operator: '=', value: b } },
+  ],
+}
+```
+
+Valid `operator` values: `=`, `!=`, `>`, `<`, `>=`, `<=`, `LIKE`, `NOT LIKE`, `ILIKE`, `IN`, `NOT IN`, `BETWEEN`, `IS NULL`, `IS NOT NULL`, `NOT EXISTS`.
+
+## Common mistake to avoid: don't invent methods
+
+If a method/param you want to use isn't in the list above, check `docs/methods/` and `README.md` in the library repo before assuming it exists. This library's docs have previously drifted from the implementation (phantom params, unsupported shapes) — when unsure, prefer reading `src/core/repository.ts` in the library repo over trusting an example that "looks right."

package/CHANGELOG.md

@@ -5,63 +5,98 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.1.0] - 2024-12-19
+Entries below are generated from the real commit history for each tagged release. See each release on GitHub for the full commit list: https://github.com/starbem/star-db-query-builder/releases
 
-### Added
+## [Unreleased]
 
-- **Multi-Connection Support**: Support for multiple simultaneous connections
-- **TypeScript Support**: Complete typing with TypeScript 5.8+
-- **Auto Retry Mechanism**: Automatic retry system for transient errors
-- **Monitoring System**: Event system for monitoring and logging
-- **Batch Operations**: Optimized batch operations (insertMany, updateMany)
-- **Unaccent Support**: Support for PostgreSQL unaccent extension
-- **Complex Query Builder**: Fluent interface for complex queries
-- **Transaction Support**: Transaction support
-- **Connection Pooling**: Efficient connection management
+## [1.4.0] - 2026-09-04
 
-### Features
+- `fix`: `createWhereClause` no longer throws `RangeError: Maximum call stack size exceeded` on a large `IN`/`NOT IN`/`BETWEEN` condition — `values.push(...value)` (spreading the array into a function call) replaced with a plain loop. Fixes #21 (item 1) / #22.
+- `fix`: `IN`/`NOT IN`/`BETWEEN` condition arrays are now capped at 10,000 values with a descriptive error, instead of silently building a query with tens of thousands of bind parameters. Fixes #21 (item 2).
+- `fix`: `update()`/`deleteOne()` now include the table name in the `ID is required` error instead of a bare generic message. Fixes #21 (item 3).
+- `fix`: `createLimitClause`/`createOffsetClause` now validate `limit`/`offset` are positive/non-negative integers instead of interpolating whatever the caller passes into the SQL string — a non-numeric value (e.g. forwarded from an unvalidated HTTP query param) previously went straight into `LIMIT`/`OFFSET`.
+- `fix`: a `where` condition using a plain value (e.g. `{ status: 'active' }` instead of `{ status: { operator: '=', value: 'active' } }`) now throws instead of being silently dropped from the generated WHERE clause — the silent-drop behavior meant `updateMany`/`deleteMany` calls that intended to scope a write could end up running against every row in the table. `updateMany` additionally refuses to run if `where` produces an empty WHERE clause.
+- `fix`: an `operator` passed in lowercase or mixed case (e.g. `'ilike'`, supported pre-1.4.0 since operators used to be interpolated as-is) is now normalized before the whitelist check instead of being rejected — a regression introduced by the P0/#21 sanitization work in this same release.
+- `fix`: `BETWEEN` now rejects a `value` array that isn't exactly 2 items, and `NOT EXISTS` now rejects a non-string `value`, instead of building malformed SQL.
+- `fix`: `insert`/`insertMany`/`upsert` now reject `data` containing `id` or `updated_at` instead of silently duplicating them in the generated column list (previously produced e.g. `INSERT INTO t ("id", "id", ...)`, a database error with no clear cause).
+- `fix`: `upsert`'s `updateFields` now accepts `updated_at` — the function always refreshes it itself regardless of `data`, so rejecting it as "not present in data" (introduced in the prior sanitization pass) was an inconsistent contract.
+- `fix`: `deleteMany`/`insertMany` now validate the total bind-parameter count against the same 65535 driver limit `createWhereClause`'s `IN`/`BETWEEN` guard already enforced, instead of only guarding one of the code paths that can build an oversized query.
+- `fix`: `createWhereClause` no longer silently drops the `AND` group when `OR` is also present in the same `where` object — both are now rendered.
 
-- **PostgreSQL Client**: Complete PostgreSQL client with extensions
-- **MySQL Client**: Complete MySQL client for MySQL 5.7+
-- **Generic Repository**: Generic and type-safe CRUD methods
-- **Query Utils**: Utilities for building SQL queries
-- **Error Handling**: Robust error handling
-- **Performance Optimization**: Performance optimizations for batch operations
+- `fix`: `findFirst` now adds `LIMIT 1` to the generated query instead of fetching every matching row and taking the first in JS.
+- `fix`: `update()` no longer concatenates `id` directly into the SQL string — parameterized for both pg and mysql (was a real SQL injection vector).
+- `fix`: `update()`/`updateMany()` now validate and quote every column name in `data` (`assertValidIdentifier` + `quoteIdentifier`), matching `insert`/`upsert`. Previously these column names were interpolated into the SQL string unvalidated.
+- `fix`: `createWhereClause` now validates `where` field names (`assertValidIdentifier`), restricts `operator` to a runtime whitelist, and validates `NOT EXISTS` subquery fragments (`assertSafeSqlFragment`) — previously all three were interpolated into the SQL string unvalidated.
+- `fix`: `upsert()` no longer duplicates `updated_at` in the generated `SET`/`ON CONFLICT DO UPDATE` clause when it's also named in `updateFields`.
+- `fix`: `upsert()` now rejects `updateFields`/`conflictFields` entries that aren't a key of `data`, instead of silently resolving to the column's table default (pg) or building a `WHERE col = NULL` re-select (mysql).
+- `fix`: `findManyCursor()` returns `nextCursor: null` (not `undefined`) when `select` omits `cursorField` from the returned rows, matching its declared `string | number | null` return type.
+- `feat`: `upsert()` — `ON CONFLICT ... DO UPDATE` (pg) / `ON DUPLICATE KEY UPDATE` (mysql).
+- `feat`: `findManyCursor()` — keyset/cursor pagination (`WHERE cursorField > cursor` + `LIMIT limit+1`, no `OFFSET`).
+- `feat`: `closeDb`, `closeAllDbClients`, `resetDbClients` for connection pool lifecycle management.
+- `feat`: configurable query timeout (`queryTimeout`) for `initDb` and the MySQL client.
+- Identifier sanitization added across the query builder (`assertValidIdentifier`, `assertSafeSqlFragment`) to prevent injection via table/column/field names, now covering every code path.
+- `insert`/`insertMany` now quote every column name for pg/mysql instead of a single hardcoded special case — fixes reserved-word columns (`order`, `group`, `user`, etc.). Surface-level SQL output change, runtime-equivalent.
+- `docs/` and `README.md` audited against the real implementation and corrected (removed a phantom `having` param on `joins()`, fixed `update`/`updateMany` examples that used an unsupported `{operator, value}` shape, fixed the `JOINS` type definition, added docs for `upsert`, `findManyCursor`, and the connection-pool lifecycle functions).
+- CI/CD split into `ci.yml` (lint/format/type-check/build/test on push+PR) and `release.yml` (tag-triggered, npm Trusted Publishing via OIDC, no `NPM_TOKEN`).
+- Dependency cleanup: removed unused `@typescript-eslint/eslint-plugin`/`parser`; safe in-range updates to `mysql2`, `pg`, `eslint`, `typescript`, and others.
+- Published npm package restricted to `dist`, `bin`, `.claude`, `CHANGELOG.md` via an explicit `files` allowlist — previously shipped `coverage/`, test sources, `.github/`, and other dev-only files due to a missing `files` field combined with a near-empty `.npmignore`.
 
-### Technical
+## [1.3.0] - 2025-09-08
 
-- **ESLint + Prettier**: Configuration for clean and consistent code
-- **Jest Testing**: Unit and integration tests
-- **Husky Hooks**: Git hooks for code quality
-- **GitHub Actions**: Automated CI/CD
-- **NPM Publishing**: Automated NPM publishing
+- `insertMany`/`updateMany` batch operations added to the query builder.
+- `rawQuery` added with documentation.
+- `beginTransaction`/commit/rollback test coverage added for both MySQL and PostgreSQL clients.
+- Pre-commit hook updated to run type-checking, then tests.
+- README rewritten: clearer title/description, install instructions, usage examples, table of contents, method docs links.
+- Outdated `genericRepository`/`utils` tests removed as part of a broader cleanup.
+- Dependency bump: `braces` 3.0.2 → 3.0.3 (#9).
+- Removed unused `.eslintignore`/`.eslintrc.json` (#18).
 
-### Documentation
+## [1.0.38] - 2025-06-12
 
-- **Complete API Reference**: Complete API documentation
-- **Practical Examples**: Practical usage examples
-- **Advanced Use Cases**: Advanced use cases
-- **Monitoring Guide**: Monitoring and logging guide
-- **Installation Guide**: Installation and configuration guide
+- Removed an unnecessary local dependency link to `@starbemtech/star-db-query-builder` left over from local development.
 
-## [Unreleased]
+## [1.0.37] - 2025-04-23
+
+- `pgClient`: `installUnaccentExtension` is now conditional instead of always running.
+- `initDb`/`getDbClient`: optional `name` parameter to target a specific database client instance.
+
+## [1.0.34] - 2025-03-26
+
+- New `monitor` module exported from the package entrypoint for observability (connection/query/transaction events).
+
+## [1.0.33] - 2025-03-11
+
+- `OperatorCondition`: added `ILIKE`, `IS NULL` / `IS NOT NULL`, and `NOT EXISTS` operators; `createWhereClause` updated to handle each correctly.
+- `initDb` made asynchronous to support async setup operations.
+- `pgClient`: ensures the `unaccent` extension is installed when requested.
+- `findMany`/`joins`: added `unaccent` support via `QueryParams`.
+- `deleteMany` added — delete multiple records by a list of IDs.
+- `insert`: reserved-word column names are wrapped in double quotes for PostgreSQL.
+- Multi-connection support for MySQL and PostgreSQL, automatic retry mechanism for transient errors, externally configurable connection pool/retry settings, and monitoring/logging events.
+- Dependency bumps: `@types/pg` → 8.11.11, `typescript` → 5.8.2, `mysql2` → 3.13.0, `pg` → 8.13.3, `uuid` → 11.1.0; added `@types/promise-retry`.
+
+## [1.0.23] - 2024-07-18
+
+- Version bump only, no functional change since 1.0.22.
+
+## [1.0.22] - 2024-07-04
+
+- `joins`: added `orderBy` and `groupBy` support.
+- `findMany`/`joins`: added `offset` support for pagination.
+- Fixed a Postgres-specific bug in the WHERE-clause utility.
+- Fixed `RETURNING` clause behavior on `update`.
+- `package.json`: raised the minimum Node version requirement to `>=18`; removed the pinned `pnpm` version constraint from `engines` for flexibility; removed the unused commit-message linter package.
+
+## [1.0.14] - 2024-04-11
 
-## [] - 2025-09-08
+- Added `joins` query support with an updated interface and query fixes.
 
-### Planned
+## [1.0.13] - 2024-04-05
 
-- **MongoDB Support**: MongoDB support
-- **Redis Support**: Redis support
-- **Query Caching**: Query caching system
-- **Connection Health Checks**: Connection health checks
-- **Performance Metrics**: Detailed performance metrics
-- **Migration Tools**: Data migration tools
-- **Schema Validation**: Schema validation
-- **GraphQL Integration**: GraphQL integration
+- Added a query to fetch by user subscription.
+- Type declarations introduced; return type adjustments.
 
-### Improvements
+## [1.0.11] - 2024-04-02
 
-- **Better Error Messages**: More descriptive error messages
-- **Query Optimization**: Additional query optimizations
-- **Memory Management**: Better memory management
-- **Connection Pool Tuning**: Automatic connection pool tuning
+- Initial tagged release: core query methods, MySQL function support, `createWhereClause`, and initial type definitions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starbem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.