@starbemtech/star-db-query-builder 1.3.1 → 1.4.1

package/bin/install-skill.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+// Copies this package's bundled Claude Code skill into the consuming repo's
+// .claude/skills/ so agents get correct star-db-query-builder usage guidance
+// without a manual copy-paste. Run from the consuming repo's root:
+//
+//   npx star-db-query-builder-install-skill
+//
+// Safe to re-run after upgrading the package — it always overwrites with the
+// version bundled in the currently installed package.
+
+const fs = require('fs')
+const path = require('path')
+
+const SKILL_NAME = 'star-db-query-builder'
+const SOURCE = path.join(__dirname, '..', '.claude', 'skills', SKILL_NAME, 'SKILL.md')
+const TARGET_DIR = path.join(process.cwd(), '.claude', 'skills', SKILL_NAME)
+const TARGET = path.join(TARGET_DIR, 'SKILL.md')
+
+function main() {
+  if (!fs.existsSync(SOURCE)) {
+    console.error(
+      `[star-db-query-builder] Could not find bundled skill at ${SOURCE}. ` +
+        'Is @starbemtech/star-db-query-builder installed correctly?'
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const alreadyExists = fs.existsSync(TARGET)
+  const previous = alreadyExists ? fs.readFileSync(TARGET, 'utf8') : null
+  const next = fs.readFileSync(SOURCE, 'utf8')
+
+  if (previous === next) {
+    console.log(`[star-db-query-builder] Skill already up to date at ${path.relative(process.cwd(), TARGET)}`)
+    return
+  }
+
+  fs.mkdirSync(TARGET_DIR, { recursive: true })
+  fs.writeFileSync(TARGET, next)
+
+  console.log(
+    `[star-db-query-builder] ${alreadyExists ? 'Updated' : 'Installed'} skill at ${path.relative(
+      process.cwd(),
+      TARGET
+    )}`
+  )
+  if (!alreadyExists) {
+    console.log('[star-db-query-builder] Commit this file so the rest of the team gets it too.')
+  }
+}
+
+main()

package/dist/src/core/repository.d.ts

@@ -1,5 +1,5 @@
-import { QueryParams, RawQueryParams } from './types';
-import { ITransactionClient } from '../db/IDatabaseClient';
+import { QueryParams, RawQueryParams, CursorPageResult, Conditions } from './types';
+import { IDatabaseClient, ITransactionClient } from '../db/IDatabaseClient';
 /**
  * Finds the first record in the specified table
  *
@@ -18,7 +18,7 @@ import { ITransactionClient } from '../db/IDatabaseClient';
  *   tableName: 'users',
  *   dbClient: dbClient,
  *   select: ['id', 'name', 'email'],
- *   where: { status: 'active' },
+ *   where: { status: { operator: '=', value: 'active' } },
  *   groupBy: ['status'],
  *   orderBy: [{ field: 'created_at', direction: 'DESC' }],
  * })
@@ -28,7 +28,7 @@ import { ITransactionClient } from '../db/IDatabaseClient';
  *   tableName: 'users',
  *   dbClient: dbClient,
  *   select: ['id', 'name', 'email'],
- *   where: { status: 'active' },
+ *   where: { status: { operator: '=', value: 'active' } },
  *   groupBy: ['status'],
  *   orderBy: [{ field: 'created_at', direction: 'DESC' }],
  * })
@@ -52,7 +52,7 @@ export declare const findFirst: <T>({ tableName, dbClient, select, where, groupB
  *   tableName: 'users',
  *   dbClient: dbClient,
  *   select: ['id', 'name', 'email'],
- *   where: { status: 'active' },
+ *   where: { status: { operator: '=', value: 'active' } },
  *   groupBy: ['status'],
  *   orderBy: [{ field: 'created_at', direction: 'DESC' }],
  *   limit: 10,
@@ -61,6 +61,51 @@ export declare const findFirst: <T>({ tableName, dbClient, select, where, groupB
  * })
  */
 export declare const findMany: <T>({ tableName, dbClient, select, where, groupBy, orderBy, limit, offset, unaccent, }: QueryParams<T>) => Promise<T[]>;
+/**
+ * Finds multiple records in the specified table using keyset (cursor)
+ * pagination instead of offset/limit
+ *
+ * Unlike offset-based pagination, keyset pagination stays O(1) regardless of
+ * how deep the page is (no `OFFSET N` row-skipping) and does not skip/repeat
+ * rows when the underlying data changes between pages. It requires
+ * `cursorField` to be a strictly ordered, indexed column — `id` (if
+ * sequential) or `created_at` are typical choices; a plain UUID `id` works
+ * for uniqueness but its ordering is arbitrary, so prefer a monotonically
+ * increasing column when the page order matters to callers.
+ *
+ * @template T - The type of the records to be returned
+ * @param params - Query parameters including table name, database client, select fields, where conditions, cursor field, cursor value, direction, page size and unaccent
+ * @returns Promise<CursorPageResult<T>> - The page of records plus the cursor to request the next page (`null` when there is no next page)
+ *
+ * @throws {Error} When table name is not provided
+ * @throws {Error} When database client is not provided
+ * @throws {Error} When direction is not ASC or DESC
+ *
+ * @example
+ * // First page
+ * const page1 = await findManyCursor({
+ *   tableName: 'users',
+ *   dbClient: dbClient,
+ *   where: { status: { operator: '=', value: 'active' } },
+ *   cursorField: 'created_at',
+ *   limit: 20,
+ * })
+ *
+ * @example
+ * // Next page
+ * const page2 = await findManyCursor({
+ *   tableName: 'users',
+ *   dbClient: dbClient,
+ *   cursorField: 'created_at',
+ *   cursor: page1.nextCursor,
+ *   limit: 20,
+ * })
+ */
+export declare const findManyCursor: <T>({ tableName, dbClient, select, where, cursorField, cursor, direction, limit, unaccent, }: QueryParams<T> & {
+    cursorField?: string;
+    cursor?: string | number;
+    direction?: "ASC" | "DESC";
+}) => Promise<CursorPageResult<T>>;
 /**
  * Inserts a new record into the specified table
  *
@@ -115,6 +160,44 @@ export declare const insertMany: <P, R>({ tableName, dbClient, data, returning,
     data: P[];
     returning?: string[];
 }) => Promise<R[]>;
+/**
+ * Inserts a record, or updates it in place if it collides with an existing
+ * unique/primary key
+ *
+ * Builds `INSERT ... ON CONFLICT (...) DO UPDATE SET ...` for pg and
+ * `INSERT ... ON DUPLICATE KEY UPDATE ...` for mysql. `conflictFields` must
+ * name columns actually covered by a unique or primary key constraint on
+ * `tableName` — this function does not create or verify that constraint, it
+ * only builds SQL that assumes it exists. For mysql, `conflictFields` is not
+ * part of the generated SQL (`ON DUPLICATE KEY UPDATE` relies on the table's
+ * own constraint) — it is used only to re-select the row afterwards, since
+ * mysql has no `RETURNING`.
+ *
+ * @template P - The type of the data to be upserted
+ * @template R - The type of the record to be returned
+ * @param params - Query parameters including table name, database client, data, conflict target fields, optional fields to update on conflict (defaults to every field in data), and optional returning fields
+ * @returns Promise<R> - The inserted or updated record
+ *
+ * @throws {Error} When table name is not provided
+ * @throws {Error} When database client is not provided
+ * @throws {Error} When data object is not provided
+ * @throws {Error} When conflictFields is not provided or empty
+ *
+ * @example
+ * const record = await upsert({
+ *   tableName: 'users',
+ *   dbClient: dbClient,
+ *   data: { email: 'john.doe@example.com', name: 'John Doe' },
+ *   conflictFields: ['email'],
+ *   returning: ['id', 'name', 'email'],
+ * })
+ */
+export declare const upsert: <P, R>({ tableName, dbClient, data, conflictFields, updateFields, returning, }: QueryParams<R> & {
+    data: P;
+    conflictFields: string[];
+    updateFields?: string[];
+    returning?: string[];
+}) => Promise<R>;
 /**
  * Updates a record in the specified table
  *
@@ -164,7 +247,7 @@ export declare const update: <P, R>({ tableName, dbClient, id, data, returning,
  *   tableName: 'users',
  *   dbClient: dbClient,
  *   data: { name: 'John Doe', email: 'john.doe@example.com' },
- *   where: { status: 'active' },
+ *   where: { status: { operator: '=', value: 'active' } },
  *   returning: ['id', 'name', 'email'],
  * })
  */
@@ -247,7 +330,7 @@ export declare const deleteMany: <T>({ tableName, dbClient, ids, field, permanen
  *   dbClient: dbClient,
  *   select: ['id', 'name', 'email'],
  *   joins: [{ type: 'INNER', table: 'orders', on: 'users.id = orders.user_id' }],
- *   where: { status: 'active' },
+ *   where: { status: { operator: '=', value: 'active' } },
  *   groupBy: ['status'],
  *   orderBy: [{ field: 'created_at', direction: 'DESC' }],
  *   limit: 10,
@@ -255,7 +338,39 @@ export declare const deleteMany: <T>({ tableName, dbClient, ids, field, permanen
  *   unaccent: true,
  * })
  */
-export declare const joins: <T>({ tableName, dbClient, select, joins, where, groupBy, orderBy, limit, offset, unaccent, }: QueryParams<T>) => Promise<T[]>;
+export declare const joins: <T, W = T>({ tableName, dbClient, select, joins, where, groupBy, orderBy, limit, offset, unaccent, }: Omit<QueryParams<T>, "where"> & {
+    /**
+     * `W` (defaults to `T`) is a separate generic from the result row type `T`:
+     * a join's `where` routinely qualifies columns from joined tables (e.g.
+     * `'orders.total'`), which are never keys of `T`. `Conditions<T | W>`'s
+     * `OR`/`AND`/`JOINS` already accept a dotted qualified-column key
+     * structurally (see `QualifiedCondition` in `./types`), so this only
+     * matters when `T` is passed explicitly and a qualified column is needed
+     * at the top level of `where` (not inside `AND`/`OR`/`JOINS`) — pass `W`
+     * explicitly too in that case:
+     * `joins<Row, Row & { 'orders.total'?: unknown }>(...)`.
+     */
+    where?: Conditions<W>;
+}) => Promise<T[]>;
+/**
+ * Error thrown by `rawQuery` when the underlying driver query fails.
+ *
+ * Carries over the original driver error as `cause` plus the common
+ * cross-driver fields consumers actually branch on (e.g. Postgres'
+ * `code: '23505'` for a unique violation, `detail`, `constraint`; mysql2's
+ * `errno`/`sqlState`) — `rawQuery` used to wrap failures in a plain `Error`
+ * built from just `error.message`, which discarded all of this and left
+ * callers with no way to distinguish a conflict from a syntax error.
+ */
+export declare class RawQueryError extends Error {
+    cause?: unknown;
+    code?: string;
+    detail?: string;
+    constraint?: string;
+    errno?: number;
+    sqlState?: string;
+    constructor(message: string, cause: unknown);
+}
 /**
  * Executa uma query SQL raw diretamente no banco de dados
  * @param params - Parâmetros da query raw
@@ -341,7 +456,7 @@ export declare const rawQuery: <T = any>({ dbClient, sql, params, }: RawQueryPar
  *   console.error('Transaction failed:', error)
  * }
  */
-export declare const withTransaction: <T>(dbClient: any, transactionFn: (tx: ITransactionClient) => Promise<T>) => Promise<T>;
+export declare const withTransaction: <T>(dbClient: IDatabaseClient, transactionFn: (tx: ITransactionClient) => Promise<T>) => Promise<T>;
 /**
  * Creates a transaction client for manual transaction management
  * @param dbClient - Database client instance
@@ -371,4 +486,4 @@ export declare const withTransaction: <T>(dbClient: any, transactionFn: (tx: ITr
  *   throw error
  * }
  */
-export declare const beginTransaction: (dbClient: any) => Promise<ITransactionClient>;
+export declare const beginTransaction: (dbClient: IDatabaseClient) => Promise<ITransactionClient>;