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

package/dist/src/core/repository.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.beginTransaction = exports.withTransaction = exports.rawQuery = exports.joins = exports.deleteMany = exports.deleteOne = exports.updateMany = exports.update = exports.insertMany = exports.insert = exports.findMany = exports.findFirst = void 0;
+exports.beginTransaction = exports.withTransaction = exports.rawQuery = exports.RawQueryError = exports.joins = exports.deleteMany = exports.deleteOne = exports.updateMany = exports.update = exports.upsert = exports.insertMany = exports.insert = exports.findManyCursor = exports.findMany = exports.findFirst = void 0;
 const uuid_1 = require("uuid");
 const utils_1 = require("./utils");
+const JOIN_TYPES = new Set(['INNER', 'LEFT', 'RIGHT', 'FULL']);
 /**
  * Finds the first record in the specified table
  *
@@ -21,7 +22,7 @@ const utils_1 = require("./utils");
  *   tableName: 'users',
  *   dbClient: dbClient,
  *   select: ['id', 'name', 'email'],
- *   where: { status: 'active' },
+ *   where: { status: { operator: '=', value: 'active' } },
  *   groupBy: ['status'],
  *   orderBy: [{ field: 'created_at', direction: 'DESC' }],
  * })
@@ -31,7 +32,7 @@ const utils_1 = require("./utils");
  *   tableName: 'users',
  *   dbClient: dbClient,
  *   select: ['id', 'name', 'email'],
- *   where: { status: 'active' },
+ *   where: { status: { operator: '=', value: 'active' } },
  *   groupBy: ['status'],
  *   orderBy: [{ field: 'created_at', direction: 'DESC' }],
  * })
@@ -39,6 +40,7 @@ const utils_1 = require("./utils");
 const findFirst = async ({ tableName, dbClient, select, where, groupBy, orderBy, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
     const fields = (0, utils_1.createSelectFields)(select, dbClient.clientType);
@@ -46,9 +48,10 @@ const findFirst = async ({ tableName, dbClient, select, where, groupBy, orderBy,
     const orderByClause = (0, utils_1.createOrderByClause)(orderBy);
     const groupByClause = (0, utils_1.createGroupByClause)(groupBy);
     const rows = await dbClient.query(`SELECT ${fields} FROM ${tableName}
-      ${whereClause.length > 7 ? whereClause : ''}
+      ${whereClause}
       ${groupByClause}
       ${orderByClause}
+      LIMIT 1
       `, params);
     return rows[0] || null;
 };
@@ -71,7 +74,7 @@ exports.findFirst = findFirst;
  *   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,
@@ -82,6 +85,7 @@ exports.findFirst = findFirst;
 const findMany = async ({ tableName, dbClient, select, where, groupBy, orderBy, limit, offset, unaccent, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
     const fields = (0, utils_1.createSelectFields)(select, dbClient.clientType);
@@ -91,7 +95,7 @@ const findMany = async ({ tableName, dbClient, select, where, groupBy, orderBy,
     const limitClause = (0, utils_1.createLimitClause)(limit);
     const offsetClause = (0, utils_1.createOffsetClause)(offset);
     const rows = await dbClient.query(`SELECT ${fields} FROM ${tableName}
-      ${whereClause.length > 7 ? whereClause : ''}
+      ${whereClause}
       ${groupByClause}
       ${orderByClause}
       ${limitClause}
@@ -100,6 +104,91 @@ const findMany = async ({ tableName, dbClient, select, where, groupBy, orderBy,
     return rows || [];
 };
 exports.findMany = findMany;
+/**
+ * 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,
+ * })
+ */
+const findManyCursor = async ({ tableName, dbClient, select, where, cursorField = 'id', cursor, direction = 'ASC', limit = 20, unaccent, }) => {
+    if (!tableName)
+        throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
+    if (!dbClient)
+        throw new Error('DB client is required');
+    (0, utils_1.assertValidIdentifier)(cursorField, 'cursor field');
+    if (direction !== 'ASC' && direction !== 'DESC') {
+        throw new Error(`Invalid direction: "${direction}". Only ASC or DESC are allowed.`);
+    }
+    if (!Number.isInteger(limit) || limit <= 0) {
+        throw new Error(`Invalid limit: "${limit}". Must be a positive integer.`);
+    }
+    const fields = (0, utils_1.createSelectFields)(select, dbClient.clientType);
+    const [whereClause, whereParams, nextIndex] = (0, utils_1.createWhereClause)(where, 1, dbClient.clientType, unaccent);
+    const params = [...whereParams];
+    let cursorCondition = '';
+    if (cursor !== undefined && cursor !== null) {
+        const operator = direction === 'ASC' ? '>' : '<';
+        const placeholder = dbClient.clientType === 'pg' ? `$${nextIndex}` : '?';
+        cursorCondition = `${cursorField} ${operator} ${placeholder}`;
+        params.push(cursor);
+    }
+    let combinedWhere = whereClause;
+    if (cursorCondition) {
+        combinedWhere = whereClause
+            ? `${whereClause} AND ${cursorCondition}`
+            : ` WHERE ${cursorCondition}`;
+    }
+    // fetch one extra row to know whether a next page exists without a
+    // separate COUNT query
+    const rows = await dbClient.query(`SELECT ${fields} FROM ${tableName}
+      ${combinedWhere}
+      ORDER BY ${cursorField} ${direction}
+      LIMIT ${limit + 1}
+    `, params);
+    const hasMore = rows.length > limit;
+    const data = hasMore ? rows.slice(0, limit) : rows;
+    const lastRow = data[data.length - 1];
+    return {
+        data,
+        nextCursor: hasMore && lastRow ? (lastRow[cursorField] ?? null) : null,
+    };
+};
+exports.findManyCursor = findManyCursor;
 /**
  * Inserts a new record into the specified table
  *
@@ -126,18 +215,20 @@ exports.findMany = findMany;
 const insert = async ({ tableName, dbClient, data, returning, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
     if (!data)
         throw new Error('Data object is required');
-    const keys = dbClient.clientType === 'pg'
-        ? Object.keys(data).map((key) => key === 'authorization' ? `"${key}"` : key)
-        : Object.keys(data);
+    const rawKeys = Object.keys(data);
+    rawKeys.forEach((key) => (0, utils_1.assertValidIdentifier)(key, 'column name'));
+    (0, utils_1.assertNoAutoManagedColumns)(rawKeys, 'insert');
+    const keys = rawKeys.map((key) => (0, utils_1.quoteIdentifier)(key, dbClient.clientType));
     const values = Object.values(data);
-    keys.unshift('id');
+    keys.unshift((0, utils_1.quoteIdentifier)('id', dbClient.clientType));
     const generatedUUID = (0, uuid_1.v4)();
     values.unshift(generatedUUID);
-    keys.push('updated_at');
+    keys.push((0, utils_1.quoteIdentifier)('updated_at', dbClient.clientType));
     values.push(new Date());
     const placeholders = (0, utils_1.generatePlaceholders)(keys, dbClient.clientType);
     let query = `INSERT INTO ${tableName} (${keys.join(', ')}) VALUES (${placeholders})`;
@@ -185,21 +276,41 @@ exports.insert = insert;
 const insertMany = async ({ tableName, dbClient, data, returning, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
     if (!data || data.length === 0)
         throw new Error('Data array is required and cannot be empty');
     const firstItem = data[0];
-    const keys = dbClient.clientType === 'pg'
-        ? Object.keys(firstItem).map((key) => key === 'authorization' ? `"${key}"` : key)
-        : Object.keys(firstItem);
-    const allKeys = ['id', ...keys, 'updated_at'];
+    const rawKeys = Object.keys(firstItem);
+    rawKeys.forEach((key) => (0, utils_1.assertValidIdentifier)(key, 'column name'));
+    (0, utils_1.assertNoAutoManagedColumns)(rawKeys, 'insertMany');
+    const rawKeySet = new Set(rawKeys);
+    data.forEach((item, index) => {
+        const itemKeys = Object.keys(item);
+        const itemKeySet = new Set(itemKeys);
+        const missing = rawKeys.filter((key) => !itemKeySet.has(key));
+        const extra = itemKeys.filter((key) => !rawKeySet.has(key));
+        if (missing.length > 0 || extra.length > 0) {
+            throw new Error(`insertMany: item at index ${index} has different keys than the first item.` +
+                (missing.length > 0 ? ` Missing: [${missing.join(', ')}].` : '') +
+                (extra.length > 0 ? ` Unexpected: [${extra.join(', ')}].` : ''));
+        }
+    });
+    const keys = rawKeys.map((key) => (0, utils_1.quoteIdentifier)(key, dbClient.clientType));
+    const allKeys = [
+        (0, utils_1.quoteIdentifier)('id', dbClient.clientType),
+        ...keys,
+        (0, utils_1.quoteIdentifier)('updated_at', dbClient.clientType),
+    ];
+    (0, utils_1.assertWithinBindParamLimit)(data.length * allKeys.length, 'insertMany');
     let query = `INSERT INTO ${tableName} (${allKeys.join(', ')}) VALUES `;
     const allValues = [];
     const valueRows = [];
     const generatedIds = [];
     data.forEach((item, rowIndex) => {
-        const values = Object.values(item);
+        const record = item;
+        const values = rawKeys.map((key) => record[key]);
         const generatedUUID = (0, uuid_1.v4)();
         generatedIds.push(generatedUUID);
         const currentValues = [generatedUUID, ...values, new Date()];
@@ -237,6 +348,116 @@ const insertMany = async ({ tableName, dbClient, data, returning, }) => {
     return inserted;
 };
 exports.insertMany = insertMany;
+/**
+ * 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'],
+ * })
+ */
+const upsert = async ({ tableName, dbClient, data, conflictFields, updateFields, returning, }) => {
+    if (!tableName)
+        throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
+    if (!dbClient)
+        throw new Error('DB client is required');
+    if (!data)
+        throw new Error('Data object is required');
+    if (!conflictFields || conflictFields.length === 0)
+        throw new Error('conflictFields is required and cannot be empty');
+    conflictFields.forEach((field) => (0, utils_1.assertValidIdentifier)(field, 'conflict field'));
+    const rawKeys = Object.keys(data);
+    rawKeys.forEach((key) => (0, utils_1.assertValidIdentifier)(key, 'column name'));
+    (0, utils_1.assertNoAutoManagedColumns)(rawKeys, 'upsert');
+    const rawKeySet = new Set(rawKeys);
+    const fieldsToUpdate = updateFields && updateFields.length > 0 ? updateFields : rawKeys;
+    fieldsToUpdate.forEach((key) => (0, utils_1.assertValidIdentifier)(key, 'column name'));
+    // 'updated_at' is always refreshed on conflict regardless of `data`
+    // (the function injects it below), so naming it in `updateFields` is
+    // valid even though it's never a key of `data`.
+    const unknownUpdateFields = fieldsToUpdate.filter((key) => key !== 'updated_at' && !rawKeySet.has(key));
+    if (unknownUpdateFields.length > 0) {
+        throw new Error(`upsert: updateFields references column(s) not present in data: [${unknownUpdateFields.join(', ')}]. Only columns included in data can be refreshed on conflict — a column left out of data would resolve to its table default instead of the intended value.`);
+    }
+    if (dbClient.clientType === 'mysql') {
+        const record = data;
+        const missingConflictValues = conflictFields.filter((field) => record[field] === undefined);
+        if (missingConflictValues.length > 0) {
+            throw new Error(`upsert: conflictFields references column(s) not present in data: [${missingConflictValues.join(', ')}]. mysql has no RETURNING, so upsert() re-selects the row by these columns after the write — they must be included in data.`);
+        }
+    }
+    const keys = rawKeys.map((key) => (0, utils_1.quoteIdentifier)(key, dbClient.clientType));
+    const values = Object.values(data);
+    keys.unshift((0, utils_1.quoteIdentifier)('id', dbClient.clientType));
+    const generatedUUID = (0, uuid_1.v4)();
+    values.unshift(generatedUUID);
+    keys.push((0, utils_1.quoteIdentifier)('updated_at', dbClient.clientType));
+    values.push(new Date());
+    const placeholders = (0, utils_1.generatePlaceholders)(keys, dbClient.clientType);
+    let query = `INSERT INTO ${tableName} (${keys.join(', ')}) VALUES (${placeholders})`;
+    if (dbClient.clientType === 'pg') {
+        const conflictTarget = conflictFields
+            .map((field) => (0, utils_1.quoteIdentifier)(field, 'pg'))
+            .join(', ');
+        const updateSet = Array.from(new Set([...fieldsToUpdate, 'updated_at']))
+            .map((key) => {
+            const quoted = (0, utils_1.quoteIdentifier)(key, 'pg');
+            return `${quoted} = EXCLUDED.${quoted}`;
+        })
+            .join(', ');
+        query += ` ON CONFLICT (${conflictTarget}) DO UPDATE SET ${updateSet}`;
+        if (returning && returning.length > 0) {
+            query += ` RETURNING ${(0, utils_1.createSelectFields)(returning, dbClient.clientType)}`;
+        }
+        const result = await dbClient.query(query, values);
+        return result[0];
+    }
+    const updateSet = Array.from(new Set([...fieldsToUpdate, 'updated_at']))
+        .map((key) => {
+        const quoted = (0, utils_1.quoteIdentifier)(key, 'mysql');
+        return `${quoted} = VALUES(${quoted})`;
+    })
+        .join(', ');
+    query += ` ON DUPLICATE KEY UPDATE ${updateSet}`;
+    await dbClient.query(query, values);
+    const record = data;
+    const whereClause = conflictFields
+        .map((field) => `${(0, utils_1.quoteIdentifier)(field, 'mysql')} = ?`)
+        .join(' AND ');
+    const conflictValues = conflictFields.map((field) => record[field]);
+    const rows = await dbClient.query(`SELECT ${returning && returning.length > 0
+        ? (0, utils_1.createSelectFields)(returning, dbClient.clientType)
+        : '*'} FROM ${tableName}
+      WHERE ${whereClause}
+    `, conflictValues);
+    return rows[0];
+};
+exports.upsert = upsert;
 /**
  * Updates a record in the specified table
  *
@@ -264,16 +485,24 @@ exports.insertMany = insertMany;
 const update = async ({ tableName, dbClient, id, data, returning, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
     if (!id)
-        throw new Error('ID is required');
+        throw new Error(`ID is required for update() on table "${tableName}"`);
     if (!data)
         throw new Error('Data object is required');
-    const keys = Object.keys(data);
-    const values = Object.values(data);
-    const setClause = (0, utils_1.generateSetClause)(keys, dbClient.clientType);
-    let query = `UPDATE ${tableName} SET ${setClause} WHERE id = '${id}'`;
+    const definedData = (0, utils_1.stripUndefinedValues)(data);
+    if (Object.keys(definedData).length === 0)
+        throw new Error('Data object must have at least one field to update');
+    const keys = Object.keys(definedData);
+    keys.forEach((key) => (0, utils_1.assertValidIdentifier)(key, 'column name'));
+    const values = Object.values(definedData);
+    const quotedKeys = keys.map((key) => (0, utils_1.quoteIdentifier)(key, dbClient.clientType));
+    const setClause = (0, utils_1.generateSetClause)(quotedKeys, dbClient.clientType);
+    const idPlaceholder = dbClient.clientType === 'pg' ? `$${values.length + 1}` : '?';
+    let query = `UPDATE ${tableName} SET ${setClause} WHERE id = ${idPlaceholder}`;
+    values.push(id);
     if (dbClient.clientType === 'pg') {
         if (returning && returning.length > 0) {
             query += ` RETURNING ${(0, utils_1.createSelectFields)(returning, dbClient.clientType)}`;
@@ -313,45 +542,62 @@ exports.update = update;
  *   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'],
  * })
  */
 const updateMany = async ({ tableName, dbClient, data, where, returning, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
     if (!data)
         throw new Error('Data object is required');
+    const definedData = (0, utils_1.stripUndefinedValues)(data);
+    if (Object.keys(definedData).length === 0)
+        throw new Error('Data object must have at least one field to update');
     if (!where)
         throw new Error('Where condition is required');
-    const keys = Object.keys(data);
-    const values = Object.values(data);
+    const keys = Object.keys(definedData);
+    keys.forEach((key) => (0, utils_1.assertValidIdentifier)(key, 'column name'));
+    const values = Object.values(definedData);
     // Generate SET clause with correct placeholders
-    const setClause = keys
-        .map((key, index) => dbClient.clientType === 'pg' ? `${key} = $${index + 1}` : `${key} = ?`)
-        .join(', ');
+    const quotedKeys = keys.map((key) => (0, utils_1.quoteIdentifier)(key, dbClient.clientType));
+    const setClause = (0, utils_1.generateSetClause)(quotedKeys, dbClient.clientType);
     // Generate WHERE clause with placeholders starting after SET values
     const [whereClause, whereParams] = (0, utils_1.createWhereClause)(where, values.length + 1, dbClient.clientType);
-    let query = `UPDATE ${tableName} SET ${setClause} ${whereClause}`;
+    if (!whereClause) {
+        throw new Error('updateMany: where condition produced an empty WHERE clause — refusing to update every row in the table. Pass at least one condition.');
+    }
+    let query = `UPDATE ${tableName} SET ${setClause}${whereClause}`;
     if (dbClient.clientType === 'pg') {
         if (returning && returning.length > 0) {
             query += ` RETURNING ${(0, utils_1.createSelectFields)(returning, dbClient.clientType)}`;
         }
+        return await dbClient.query(query, [...values, ...whereParams]);
     }
-    const updated = await dbClient.query(query, [...values, ...whereParams]);
-    if (dbClient.clientType === 'mysql') {
-        // For MySQL, we need to fetch the updated records separately
-        // since MySQL doesn't support RETURNING clause
-        const rows = await dbClient.query(`SELECT ${returning && returning.length > 0
-            ? (0, utils_1.createSelectFields)(returning, dbClient.clientType)
-            : '*'} FROM ${tableName}
-        ${whereClause}
-      `, whereParams);
-        return rows;
+    // MySQL has no RETURNING, so the rows have to be fetched with a separate
+    // SELECT. That SELECT must capture *which* rows matched before the UPDATE
+    // runs: re-running the original WHERE afterwards (as this used to do)
+    // silently returns the wrong rows whenever the UPDATE changes a column the
+    // WHERE itself filters on — e.g. `where: { status: 'pending' }` with
+    // `data: { status: 'done' }` matches zero rows once every row's status has
+    // already flipped to 'done', so the caller got back `[]` instead of the
+    // rows it just updated.
+    const idColumn = (0, utils_1.quoteIdentifier)('id', dbClient.clientType);
+    const matchedIdRows = await dbClient.query(`SELECT ${idColumn} FROM ${tableName}${whereClause}`, whereParams);
+    if (matchedIdRows.length === 0) {
+        await dbClient.query(query, [...values, ...whereParams]);
+        return [];
     }
-    return updated;
+    const ids = matchedIdRows.map((row) => row.id);
+    await dbClient.query(query, [...values, ...whereParams]);
+    const idPlaceholders = ids.map(() => '?').join(', ');
+    const rows = await dbClient.query(`SELECT ${returning && returning.length > 0
+        ? (0, utils_1.createSelectFields)(returning, dbClient.clientType)
+        : '*'} FROM ${tableName} WHERE ${idColumn} IN (${idPlaceholders})`, ids);
+    return rows;
 };
 exports.updateMany = updateMany;
 /**
@@ -379,10 +625,11 @@ exports.updateMany = updateMany;
 const deleteOne = async ({ tableName, dbClient, id, permanently = false, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
     if (!id)
-        throw new Error('ID is required');
+        throw new Error(`ID is required for deleteOne() on table "${tableName}"`);
     await dbClient.query(permanently
         ? `DELETE FROM ${tableName} WHERE id = ${dbClient.clientType === 'pg' ? '$1' : '?'}`
         : `UPDATE ${tableName} SET status = 'deleted' WHERE id = ${dbClient.clientType === 'pg' ? '$1' : '?'}`, [id]);
@@ -415,12 +662,15 @@ exports.deleteOne = deleteOne;
 const deleteMany = async ({ tableName, dbClient, ids, field = 'id', permanently = false, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
     if (!ids || ids.length === 0)
         throw new Error('IDs are required and cannot be empty');
     if (!field)
         throw new Error('Field is required');
+    (0, utils_1.assertValidIdentifier)(field, 'field');
+    (0, utils_1.assertWithinBindParamLimit)(ids.length, 'deleteMany');
     const placeholders = dbClient.clientType === 'pg'
         ? ids.map((_, index) => `$${index + 1}`).join(', ')
         : ids.map(() => '?').join(', ');
@@ -451,7 +701,7 @@ exports.deleteMany = deleteMany;
  *   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,
@@ -462,8 +712,18 @@ exports.deleteMany = deleteMany;
 const joins = async ({ tableName, dbClient, select, joins, where, groupBy, orderBy, limit, offset, unaccent, }) => {
     if (!tableName)
         throw new Error('Table name is required');
+    (0, utils_1.assertValidIdentifier)(tableName, 'table name');
     if (!dbClient)
         throw new Error('DB client is required');
+    if (joins) {
+        joins.forEach((join) => {
+            if (!JOIN_TYPES.has(join.type)) {
+                throw new Error(`Invalid join type: "${join.type}". Only INNER, LEFT, RIGHT or FULL are allowed.`);
+            }
+            (0, utils_1.assertValidIdentifier)(join.table, 'join table');
+            (0, utils_1.assertSafeSqlFragment)(join.on, 'join on condition');
+        });
+    }
     const fields = Array.isArray(select) ? select : [];
     const selectFields = (0, utils_1.createSelectFields)(fields, dbClient.clientType);
     const [whereClause, params] = (0, utils_1.createWhereClause)(where, 1, dbClient.clientType, unaccent);
@@ -486,6 +746,39 @@ const joins = async ({ tableName, dbClient, select, joins, where, groupBy, order
     return rows;
 };
 exports.joins = joins;
+/**
+ * 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.
+ */
+class RawQueryError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'RawQueryError';
+        // Set manually rather than via the ES2022 `Error(message, { cause })`
+        // constructor form, which this project's `lib` target doesn't include.
+        this.cause = cause;
+        if (cause && typeof cause === 'object') {
+            const driverError = cause;
+            if (typeof driverError.code === 'string')
+                this.code = driverError.code;
+            if (typeof driverError.detail === 'string')
+                this.detail = driverError.detail;
+            if (typeof driverError.constraint === 'string')
+                this.constraint = driverError.constraint;
+            if (typeof driverError.errno === 'number')
+                this.errno = driverError.errno;
+            if (typeof driverError.sqlState === 'string')
+                this.sqlState = driverError.sqlState;
+        }
+    }
+}
+exports.RawQueryError = RawQueryError;
 /**
  * Executa uma query SQL raw diretamente no banco de dados
  * @param params - Parâmetros da query raw
@@ -531,7 +824,7 @@ const rawQuery = async ({ dbClient, sql, params = [], }) => {
         return result;
     }
     catch (error) {
-        throw new Error(`Raw query execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        throw new RawQueryError(`Raw query execution failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error);
     }
 };
 exports.rawQuery = rawQuery;
@@ -548,7 +841,7 @@ exports.rawQuery = rawQuery;
  *   select: ['id', 'name', 'email'],
  *   from: 'users',
  *   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,