breadfruit 3.0.1 → 3.1.0

package/README.md

@@ -17,7 +17,7 @@ Not really bread. Not really fruit. Just like this package. Simple CRUD helpers
 npm install breadfruit
 ```
 
-Requires Node.js `>=20`.
+Requires Node.js `>=22`.
 
 ## Usage
 
@@ -102,6 +102,157 @@ Runs a raw SQL statement and returns rows.
 const rows = await raw('select * from users');
 ```
 
+### `count(table, filter, options?)`
+
+Returns the count of matching rows as a number.
+
+```js
+const activeUsers = await count('users', { active: true });
+```
+
+### `upsert(table, returnFields, data, conflictColumns, options?)`
+
+Inserts a row, or updates on conflict. `conflictColumns` can be a string or array.
+
+```js
+const row = await upsert(
+  'users',
+  '*',
+  { email: 'luis@example.com', name: 'Luis' },
+  'email',
+);
+```
+
+### `transaction(callback)`
+
+Wraps `knex.transaction()`. Pass the `trx` object as `dbApi` in your method calls.
+
+```js
+await transaction(async (trx) => {
+  await add('users', ['id'], { name: 'a' }, { dbApi: trx });
+  await add('users', ['id'], { name: 'b' }, { dbApi: trx });
+});
+```
+
+## Advanced
+
+### Passing an existing Knex instance
+
+Instead of a config object, you can pass a Knex instance. Useful when you already have a Knex connection in your app and want breadfruit to use it rather than open a second pool.
+
+```js
+import knex from './db.js';
+import breadfruit from 'breadfruit';
+
+const bf = breadfruit(knex);
+```
+
+### Composite filters
+
+Filter values accept operators beyond simple equality.
+
+| Shape | SQL |
+|---|---|
+| `{ col: value }` | `col = value` |
+| `{ col: [a, b, c] }` | `col IN (a, b, c)` |
+| `{ col: null }` | `col IS NULL` |
+| `{ col: { eq: x } }` | `col = x` |
+| `{ col: { ne: x } }` | `col != x` |
+| `{ col: { gt: x } }` | `col > x` |
+| `{ col: { gte: x } }` | `col >= x` |
+| `{ col: { lt: x } }` | `col < x` |
+| `{ col: { lte: x } }` | `col <= x` |
+| `{ col: { like: 'x%' } }` | `col LIKE 'x%'` |
+| `{ col: { ilike: 'x%' } }` | `col ILIKE 'x%'` |
+| `{ col: { in: [a, b] } }` | `col IN (a, b)` |
+| `{ col: { notIn: [a, b] } }` | `col NOT IN (a, b)` |
+| `{ col: { between: [a, b] } }` | `col BETWEEN a AND b` |
+| `{ col: { notBetween: [a, b] } }` | `col NOT BETWEEN a AND b` |
+| `{ col: { null: true } }` | `col IS NULL` |
+| `{ col: { null: false } }` | `col IS NOT NULL` |
+
+Multiple operators on the same column AND together:
+
+```js
+await browse('events', '*', {
+  count: { gt: 1, lte: 100 },
+  created_at: { gte: '2026-01-01' },
+});
+```
+
+### `forTable(tableName, options?)` — table-bound helpers
+
+Returns an object with the same BREAD methods but bound to a specific table, with optional **soft delete** and **view-for-reads** behavior.
+
+```js
+const users = bf.forTable('users', {
+  softDelete: true,
+  viewName: 'users_v',
+});
+
+await users.browse('*', { active: true });   // reads from users_v
+await users.del({ id: 42 });                  // soft-deletes in users
+await users.restore({ id: 42 });              // un-soft-deletes
+const total = await users.count({});          // respects soft delete
+```
+
+#### Soft delete
+
+Three options for the `softDelete` config:
+
+```js
+// 1. Boolean shorthand — uses is_deleted column, true/false
+softDelete: true
+
+// 2. Full config
+softDelete: {
+  column: 'is_deleted',
+  value: true,           // set on delete
+  undeletedValue: false, // the "active" value for filtering
+}
+
+// 3. Timestamp style — deleted_at IS NULL means active
+softDelete: {
+  column: 'deleted_at',
+  value: 'NOW',          // special string -> knex.fn.now()
+  undeletedValue: null,
+}
+```
+
+The `value` field accepts:
+- a literal (`true`, `false`, `Date`, etc.)
+- the string `'NOW'` — becomes `knex.fn.now()` so the DB generates the timestamp
+- a Knex raw expression like `knex.fn.now()` or `knex.raw('...')`
+- a function — called at delete time (runs in JS, not DB)
+
+#### Reads from a view, writes to the table
+
+Pass `viewName` to read from a view while writing to the underlying table. Great for denormalized read paths.
+
+```js
+bf.forTable('users', { viewName: 'user_groups_v' });
+```
+
+#### `withDeleted`
+
+Bypass the soft-delete filter for admin or audit views:
+
+```js
+const allUsers = await users.browse('*', {}, { withDeleted: true });
+const count = await users.count({}, { withDeleted: true });
+```
+
+### Transactions with `forTable`
+
+Pass `dbApi: trx` through just like the top-level API:
+
+```js
+await bf.transaction(async (trx) => {
+  await users.add('*', { email: 'a@b.c' }, { dbApi: trx });
+  await users.edit('*', { active: true }, { email: 'a@b.c' }, { dbApi: trx });
+});
+```
+
 ## License
 
 ISC

package/index.js

@@ -1,13 +1,92 @@
 import knexConstructor from 'knex';
 
+const defaults = {
+  dateField: 'created_at',
+  limit: 1000,
+  offset: 0,
+  sortOrder: 'ASC',
+};
+
+const OPERATORS = {
+  eq: '=',
+  ne: '!=',
+  gt: '>',
+  gte: '>=',
+  lt: '<',
+  lte: '<=',
+  like: 'like',
+  ilike: 'ilike',
+};
+
+// Apply a filter object to a Knex query. Supports:
+//   { col: value }                        -> WHERE col = value
+//   { col: [a, b, c] }                    -> WHERE col IN (...)
+//   { col: null }                         -> WHERE col IS NULL
+//   { col: { gt: x, lte: y } }            -> WHERE col > x AND col <= y
+//   { col: { in: [a, b] } }               -> WHERE col IN (...)
+//   { col: { notIn: [a, b] } }            -> WHERE col NOT IN (...)
+//   { col: { between: [a, b] } }          -> WHERE col BETWEEN a AND b
+function applyFilter(query, filter) {
+  if (!filter) return query;
+  for (const [key, value] of Object.entries(filter)) {
+    if (value === undefined) continue;
+    if (value === null) {
+      query = query.whereNull(key);
+    } else if (Array.isArray(value)) {
+      query = query.whereIn(key, value);
+    } else if (typeof value === 'object' && !(value instanceof Date) && !value.toSQL) {
+      for (const [op, operand] of Object.entries(value)) {
+        if (operand === undefined) continue;
+        if (op === 'in') query = query.whereIn(key, operand);
+        else if (op === 'notIn') query = query.whereNotIn(key, operand);
+        else if (op === 'between') query = query.whereBetween(key, operand);
+        else if (op === 'notBetween') query = query.whereNotBetween(key, operand);
+        else if (op === 'null') {
+          query = operand ? query.whereNull(key) : query.whereNotNull(key);
+        } else if (OPERATORS[op]) {
+          query = query.where(key, OPERATORS[op], operand);
+        } else {
+          throw new Error(`Unknown filter operator: ${op}`);
+        }
+      }
+    } else {
+      query = query.where(key, value);
+    }
+  }
+  return query;
+}
+
+// Resolve a soft-delete config to { column, value, undeletedValue }.
+// Accepts:
+//   true                                  -> { column: 'is_deleted', value: true, undeletedValue: false }
+//   { column, value, undeletedValue }     -> used as-is
+//   value can be:
+//     - a literal (true, false, Date, etc.)
+//     - the string 'NOW' -> knex.fn.now()
+//     - a Knex raw expression (e.g. knex.fn.now())
+//     - a function -> called at delete time
+function resolveSoftDelete(config, knex) {
+  if (!config) return null;
+  if (config === true) {
+    return { column: 'is_deleted', value: true, undeletedValue: false };
+  }
+  if (typeof config !== 'object') {
+    throw new Error('softDelete must be true or an object');
+  }
+  const column = config.column || 'is_deleted';
+  const undeletedValue = 'undeletedValue' in config ? config.undeletedValue : false;
+  let value = 'value' in config ? config.value : true;
+  if (value === 'NOW') value = knex.fn.now();
+  return { column, value, undeletedValue };
+}
+
+function resolveValue(value) {
+  return typeof value === 'function' ? value() : value;
+}
+
 export default function connect(settings) {
-  const knex = knexConstructor(settings);
-  const defaults = {
-    dateField: 'created_at',
-    limit: 1000,
-    offset: 0,
-    sortOrder: 'ASC',
-  };
+  // Allow passing an existing knex instance or a config
+  const knex = typeof settings === 'function' ? settings : knexConstructor(settings);
 
   function browse(table, fields, filter, options = {}) {
     const dbApi = options.dbApi || knex;
@@ -16,11 +95,9 @@ export default function connect(settings) {
     const dateField = options.dateField || defaults.dateField;
     const sortOrder = options.sortOrder || defaults.sortOrder;
 
-    let query = dbApi(table)
-      .where(filter)
-      .select(fields)
-      .limit(limit)
-      .offset(offset);
+    let query = dbApi(table).select(fields).limit(limit).offset(offset);
+
+    query = applyFilter(query, filter);
 
     if (options.search_start_date && options.search_end_date) {
       query = query.whereBetween(dateField, [
@@ -45,8 +122,10 @@ export default function connect(settings) {
 
   async function read(table, fields, filter, options = {}) {
     const dbApi = options.dbApi || knex;
-    const [row] = await dbApi(table).where(filter).select(fields);
-    return row;
+    let query = dbApi(table).select(fields);
+    query = applyFilter(query, filter);
+    const row = await query.first();
+    return row || null;
   }
 
   async function add(table, fields, data, options = {}) {
@@ -57,16 +136,36 @@ export default function connect(settings) {
 
   async function edit(table, fields, data, filter, options = {}) {
     const dbApi = options.dbApi || knex;
-    const [row] = await dbApi(table)
-      .where(filter)
-      .returning(fields)
-      .update(data);
+    let query = dbApi(table).returning(fields).update(data);
+    query = applyFilter(query, filter);
+    const [row] = await query;
     return row;
   }
 
   function del(table, filter, options = {}) {
     const dbApi = options.dbApi || knex;
-    return dbApi(table).where(filter).del();
+    let query = dbApi(table).del();
+    query = applyFilter(query, filter);
+    return query;
+  }
+
+  async function count(table, filter, options = {}) {
+    const dbApi = options.dbApi || knex;
+    let query = dbApi(table).count('* as total');
+    query = applyFilter(query, filter);
+    const [row] = await query;
+    return Number(row.total);
+  }
+
+  async function upsert(table, fields, data, conflictColumns, options = {}) {
+    const dbApi = options.dbApi || knex;
+    const cols = Array.isArray(conflictColumns) ? conflictColumns : [conflictColumns];
+    const [row] = await dbApi(table)
+      .insert(data)
+      .onConflict(cols)
+      .merge()
+      .returning(fields);
+    return row;
   }
 
   async function raw(sql, options = {}) {
@@ -75,5 +174,75 @@ export default function connect(settings) {
     return res.rows || res;
   }
 
-  return { browse, read, add, edit, del, raw, knex };
+  function transaction(callback) {
+    return knex.transaction(callback);
+  }
+
+  // Table-bound API with optional softDelete and viewName support.
+  // Returns an object with the same BREAD methods but bound to a specific table,
+  // with soft-delete filtering baked into browse/read/del, and optional
+  // separate readTable (view) for reads vs writes.
+  function forTable(tableName, tableOptions = {}) {
+    const softDelete = resolveSoftDelete(tableOptions.softDelete, knex);
+    const readTable = tableOptions.viewName || tableName;
+    const writeTable = tableName;
+
+    function addSoftDeleteFilter(filter = {}, options = {}) {
+      if (!softDelete) return filter;
+      if (options.withDeleted) return filter;
+      // Don't override if caller explicitly set the column
+      if (filter[softDelete.column] !== undefined) return filter;
+      return { ...filter, [softDelete.column]: softDelete.undeletedValue };
+    }
+
+    return {
+      browse(fields, filter, options = {}) {
+        return browse(readTable, fields, addSoftDeleteFilter(filter, options), options);
+      },
+      read(fields, filter, options = {}) {
+        return read(readTable, fields, addSoftDeleteFilter(filter, options), options);
+      },
+      add(fields, data, options = {}) {
+        return add(writeTable, fields, data, options);
+      },
+      edit(fields, data, filter, options = {}) {
+        return edit(writeTable, fields, data, addSoftDeleteFilter(filter, options), options);
+      },
+      del(filter, options = {}) {
+        if (softDelete) {
+          const dbApi = options.dbApi || knex;
+          let query = dbApi(writeTable).update({
+            [softDelete.column]: resolveValue(softDelete.value),
+          });
+          query = applyFilter(query, addSoftDeleteFilter(filter, options));
+          return query;
+        }
+        return del(writeTable, filter, options);
+      },
+      restore(filter, options = {}) {
+        if (!softDelete) {
+          throw new Error('restore() requires softDelete to be configured');
+        }
+        const dbApi = options.dbApi || knex;
+        let query = dbApi(writeTable).update({
+          [softDelete.column]: softDelete.undeletedValue,
+        });
+        // When restoring, look only at deleted rows
+        const restoreFilter = { ...filter, [softDelete.column]: { ne: softDelete.undeletedValue } };
+        query = applyFilter(query, restoreFilter);
+        return query;
+      },
+      count(filter, options = {}) {
+        return count(readTable, addSoftDeleteFilter(filter, options), options);
+      },
+      upsert(fields, data, conflictColumns, options = {}) {
+        return upsert(writeTable, fields, data, conflictColumns, options);
+      },
+      softDelete,
+      tableName: writeTable,
+      readTable,
+    };
+  }
+
+  return { browse, read, add, edit, del, raw, count, upsert, transaction, forTable, knex };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breadfruit",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Boilerplate SQL query helpers for Node.js using Knex",
   "type": "module",
   "main": "./index.js",
@@ -15,7 +15,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "lint": "eslint .",