sql-love 0.9.3 → 0.9.5

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 ## Change Log
 
-### v0.9.3 - 30 Nov 2023
+### v0.9.5 - 5 Dec 2023
+
+- Utility functions (extractGrouped, extractIndexed, getPagination, runPrisma, runMysql)
+- Added `SelectBuilder.setDefaultEngine(engine)`
+- More documentation
+
+### v0.9.4 - 30 Nov 2023
 
 - Support parsing and building "ILIKE" and "NOT ILIKE"
 

package/README.md

@@ -1,12 +1,12 @@
-<img alt="SQL Love Logo" src="https://github.com/kensnyder/sql-love/raw/main/assets/sql-love-logo.png?v=0.9.3" width="250" height="208" />
+<img alt="SQL Love Logo" src="https://github.com/kensnyder/sql-love/raw/main/assets/sql-love-logo.png?v=0.9.5" width="250" height="208" />
 
 # sql-love
 
-[![NPM Link](https://badgen.net/npm/v/sql-love?v=0.9.3)](https://npmjs.com/package/sql-love)
-[![Dependencies](https://badgen.net/static/dependencies/0/green?v=0.9.3)](https://npmjs.com/package/sql-love)
-[![Build Status](https://github.com/kensnyder/sql-love/actions/workflows/node.js.yml/badge.svg?v=0.9.3)](https://github.com/kensnyder/sql-love/actions)
-[![Code Coverage](https://codecov.io/gh/kensnyder/sql-love/branch/main/graph/badge.svg?v=0.9.3)](https://codecov.io/gh/kensnyder/sql-love)
-[![ISC License](https://badgen.net/static/license/ISC/green?v=0.9.3)](https://opensource.org/licenses/ISC)
+[![NPM Link](https://badgen.net/npm/v/sql-love?v=0.9.5)](https://npmjs.com/package/sql-love)
+[![Dependencies](https://badgen.net/static/dependencies/0/green?v=0.9.5)](https://npmjs.com/package/sql-love)
+[![Build Status](https://github.com/kensnyder/sql-love/actions/workflows/node.js.yml/badge.svg?v=0.9.5)](https://github.com/kensnyder/sql-love/actions)
+[![Code Coverage](https://codecov.io/gh/kensnyder/sql-love/branch/main/graph/badge.svg?v=0.9.5)](https://codecov.io/gh/kensnyder/sql-love)
+[![ISC License](https://badgen.net/static/license/ISC/green?v=0.9.5)](https://opensource.org/licenses/ISC)
 
 Classes for parsing and building SQL select queries in Node
 
@@ -20,12 +20,21 @@ npm install sql-love
 
 - [SelectBuilder](#selectbuilder)
   - [Parsing base SQL](#parsing-base-sql)
+  - [SQL injection](#sql-injection)
   - [Building the Query](#building-the-query)
-  - [Counting Results](#counting-results)
-  - [Other Methods](#other-methods)
-  - [new SelectBuilder() Limitations](#selectparse-limitations)
-- [How to Contribute](./CONTRIBUTING.md)
-- [ISC License](./LICENSE.md)
+  - [More examples](#where-examples)
+  - [Counting results](#counting-results)
+  - [Other methods](#other-methods)
+  - [new SelectBuilder() limitations](#selectparse-limitations)
+- [Utility functions](#utility-functions)
+  - [getPagination](#getpagination)
+  - [extractGrouped](#extractGrouped)
+  - [extractIndexed](#extractIndexed)
+  - [runMysql and runPrismaWithCount](#runPrisma-and-runPrismaWithCount)
+  - [runMysql and runMysqlWithCount](#runMysql-and-runMysqlWithCount)
+  - [runPg and runPgWithCount](#runPg-and-runPgWithCount)
+- [How to contribute](./CONTRIBUTING.md)
+- [ISC license](./LICENSE.md)
 
 ## SelectBuilder
 
@@ -37,7 +46,8 @@ clauses including JOIN, WHERE, ORDER BY, LIMIT, OFFSET.
 You can define a base query and pass it to the SelectBuilder constructor.
 
 ```js
-const { SelectBuilder } = require('sql-love');
+import { SelectBuilder } from 'sql-love';
+
 const query = new SelectBuilder(`
   SELECT u.id, u.fname, u.lname, u.email, p.phone
   FROM users
@@ -60,11 +70,16 @@ const { sql, bindings } = query.compile();
 connection.query(sql, bindings, (err, results, fields) => {});
 // or Prisma
 const result = await prisma.$queryRawUnsafe(sql, ...bindings);
+
+// Note that these are prepared statements so the values in the "bindings"
+//   array are safe from SQL injection.
 ```
 
 It is possible to add placeholders to the base query.
 
 ```js
+import { SelectBuilder } from 'sql-love';
+
 const query = new SelectBuilder(
   `
     SELECT u.id, u.fname, u.lname, u.email, a.city, a.zip
@@ -95,27 +110,42 @@ And "bindings" equals:
 You may specify a compiler engine to use. The default is `"mysql"`.
 
 ```js
+import { SelectBuilder } from 'sql-love';
+
 const query = new SelectBuilder('SELECT * FROM users')
   .limit(10)
   .page(3)
   .where('id', 1);
 
-query.compile('mysql').sql;
+query.compile({ engine: 'mysql' }).sql;
 // SELECT * FROM users WHERE id = ? OFFSET 20 LIMIT 10
 
-query.compile('pg').sql;
+query.compile({ engine: 'pg' }).sql;
 // SELECT * FROM users WHERE id = $1 OFFSET 20 LIMIT 10
 
-query.compile('mssql').sql;
+query.compile({ engine: 'mssql' }).sql;
 // SELECT * FROM users WHERE id = ? OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY
 
-query.compile('oracle').sql;
+query.compile({ engine: 'oracle' }).sql;
 // SELECT * FROM users WHERE id = ? OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY
+
+// Or you can specify the default engine to use in the compile function
+SelectBuilder.setDefaultEngine('pg');
 ```
 
-### Building the Query
+### SQL injection
+
+You should use prepared statements to run the sql and bindings returned by
+`SelectBuilder.compile()`. This will protect you from SQL injection.
+
+Even though `prisma.$queryRawUnsafe()` implies that the query is unsafe,
+execute with the "sql", and "bindings" is actually safe because it uses prepared
+statements.
+
+### Building the query
 
-Use the following methods to build queries.
+Use the following methods to build queries. And see
+[more examples below](#where-examples).
 
 - `query.where(column, operator, value)` - Require column satisfy operator
 - `query.where(column, value)` - Require column equal a value
@@ -148,7 +178,94 @@ Use the following methods to build queries.
 - `query.rightOuterJoin(expression)` - Add a RIGHT OUTER JOIN expression
 - `query.groupBy(column)` - Group by a column or expression
 
-### Counting Results
+### More examples
+
+```js
+// The following are equivalent
+query.where('deleted_at', '=', null);
+query.where('deleted_at', '=', undefined);
+query.where('deleted_at', null);
+query.where('deleted_at', undefined);
+query.where('deleted_at IS NULL');
+query.where({ deleted_at: null });
+query.where({ deleted_at: undefined });
+
+// the following demonstrate ways to use LIKE
+query.where('name', 'LIKE', 'son');
+query.where('name', 'LIKE ?', 'son');
+query.where('name', 'LIKE ?%', 'son');
+query.where('name', 'LIKE %?', 'son');
+query.where('name', 'LIKE %?%', 'son');
+query.where('name', 'LIKE', '%son%');
+
+// The following demonstrate ways to use various operators
+query.where('price', '=', 100);
+query.where('price', '!=', 100);
+query.where('price', '<>', 100);
+query.where('price', '>', 100);
+query.where({ 'price >': 100 });
+query.where('price', 'BETWEEN', [100, 200]);
+query.where('price', 'NOT BETWEEN', [100, 200]);
+query.whereBetween('price', [100, 200]); // price BETWEEN 100 AND 200
+query.whereBetween('price', [100, null]); // price > 100
+query.whereBetween('price', [null, 200]); // price < 200
+query.whereBetween('price', [null, null]); // clause is ignored
+
+// The following demonstrate ways to use IN and NOT IN
+query.where('status', 'IN', ['pending', 'approved']);
+query.where('status', ['pending', 'approved']);
+query.where('status', '=', ['pending', 'approved']);
+query.where('status', '!=', ['pending', 'approved']);
+query.where('status', 'NOT IN', ['pending', 'approved']);
+query.where({ status: ['pending', 'approved'] });
+query.where({ 'status NOT IN': ['pending', 'approved'] });
+query.where({ 'status !=': ['pending', 'approved'] });
+query.where({ 'status <>': ['pending', 'approved'] });
+// Note: .having() supports the same signatures as .where()
+
+// The following demonstrates using objects to specify multiple conditions
+query.where({
+  deleted_at: null,
+  'price >': 100,
+  'price <': 200,
+  color: ['blue', 'black'],
+  'stars BETWEEN': [4, 5],
+  conditions: ['new', 'used'],
+});
+
+// The following demonstrate equivalent ways to use OR
+query.orWhere([{ approved_at: null }, { denied_at: null }]);
+query.orWhere({ approved_at: null, denied_at: null });
+query.orWhere(['approved_at IS NULL', 'denied_at IS NULL']);
+query.orWhere([
+  ['approved_at', null],
+  ['denied_at =', null],
+]);
+query.where('(approved_at IS NULL OR denied_at IS NULL)');
+// Note: .orHaving() supports the same signatures as .orWhere()
+
+// The following demonstrate joins
+query.innerJoin('phone_numbers p ON p.user_id = u.id');
+query.leftJoin('phone_numbers p ON p.user_id = u.id AND p.type = ?', ['main']);
+query.outerJoin('phone_numbers p ON p.user_id = u.id AND p.type NOT IN(?, ?)', [
+  'home',
+  'cell',
+]);
+
+// The following demonstrates pagination
+query.limit(10).page(3); // LIMIT 10 OFFSET 20
+
+// The following demonstrates cloning
+const query1 = new SelectBuilder();
+query1.where('email', 'john@example.com');
+const query2 = query1.getClone();
+query1.table('users');
+query2.table('contacts');
+query1.compile().sql; // SELECT * FROM users WHERE email = ?
+query2.compile().sql; // SELECT * FROM contacts WHERE email = ?
+```
+
+### Counting results
 
 One powerful feature of SelectBuilder is that it can construct a count query
 to determine the number of results that would have been returned if there were
@@ -159,6 +276,9 @@ const query = new SelectBuilder('SELECT id, name FROM users LIMIT 5');
 
 const { sql } = query.compileCount();
 // SELECT COUNT(*) AS found_rows FROM users
+
+const { sql } = query.compileCount({ countExpr: 'DISTINCT externalId' });
+// SELECT COUNT(DISTINCT externalId) AS found_rows FROM users
 ```
 
 With queries that have a "HAVING" clause, the main query will be wrapped in a
@@ -193,14 +313,14 @@ SelectBuilder has a few other useful methods.
 - `query.reset(fields)` - Reset a few particular aspects of the query (e.g. \['where', 'having'\])
 - `query.reset()` - Reset query to an empty state
 
-### Parser Limitations
+### Parser limitations
 
 `new SelectBuilder(sql)` uses regular expressions and is not a true parser.
 The goal is to be fast and useful for 99% of situations.
 
 Below are some limitations illustrated by example.
 
-#### Nested Subqueries
+#### Nested subqueries
 
 Most subqueries can be parsed but sub-subqueries don't work.
 
@@ -215,14 +335,13 @@ SELECT * FROM categories_posts WHERE category_id IN(
 
 // ✅ WORKING EQUIVALENT
 const query = new SelectBuilder(`SELECT * FROM categories_posts`);
-const subquery =
-  new SelectBuilder(`SELECT id FROM categories WHERE client_id IN(
-    SELECT client_id FROM affiliations WHERE name LIKE 'test'
-)`);
+const subquery = `SELECT id FROM categories WHERE client_id IN(
+  SELECT client_id FROM affiliations WHERE name LIKE 'test'
+)`;
 query.where(`category_id IN(${subquery})`);
 ```
 
-#### Keywords in Strings
+#### Keywords in strings
 
 If you need to use SQL keywords in strings, use bindings.
 
@@ -236,7 +355,7 @@ new SelectBuilder(`SELECT id, CONCAT(:prefix, expr) FROM users`, {
 });
 ```
 
-#### Nested OR and AND Clauses
+#### Nested OR and AND clauses
 
 Nested logic can't be parsed properly.
 
@@ -260,3 +379,110 @@ query.orWhere([
   'id > 0 AND is_active IS NOT NULL',
 ]);
 ```
+
+## Utility functions
+
+There are several utility functions bundled with this library.
+
+### getPagination
+
+You can get detailed page and limit information from a query.
+
+```js
+import { SelectBuilder, getPagination } from 'sql-love';
+
+const query = new SelectBuilder('SELECT * FROM users').limit(10).page(1);
+// ...
+// run a count query to determine that there are 42 results
+const pagination = getPagination(query, 42);
+expect(pagination).toEqual({
+  page: 1,
+  prevPage: null,
+  nextPage: 2,
+  perPage: 10,
+  numPages: 5,
+  total: 42,
+  isFirst: true,
+  isLast: false,
+});
+```
+
+### extractIndexed
+
+You can index a results set by a particular field.
+
+```js
+import { extractIndexed } from 'sql-love';
+
+const records = [
+  { id: 1, name: 'John' },
+  { id: 2, name: 'Jane' },
+];
+const indexed = extractIndexed('id', records);
+/*
+{
+  1: { id: 1, name: 'John' },
+  2: { id: 2, name: 'Jane' },
+});
+*/
+```
+
+### extractGrouped
+
+You can divide a results set into groups based on a particular field.
+
+```js
+import { extractGrouped } from 'sql-love';
+
+const records = [
+  { id: 1, name: 'John', dept: 'Marketing' },
+  { id: 2, name: 'Jane', dept: 'Finance' },
+  { id: 3, name: 'Tim', dept: 'Marketing' },
+];
+const grouped = extractGrouped('dept', records);
+/*
+{
+  Marketing: [
+    { id: 1, name: 'John', dept: 'Marketing' },
+    { id: 3, name: 'Tim', dept: 'Marketing' },
+  ],
+  Finance: [{ id: 2, name: 'Jane', dept: 'Finance' }],
+}
+*/
+```
+
+### runPrisma and runPrismaWithCount
+
+`runPrisma()` will run a query using Prisma and return the results.
+
+```js
+import { SelectBuilder, runPrisma, runPrismaWithCount } from 'sql-love';
+import { prisma } from '~/db.server';
+
+const query = new SelectBuilder('SELECT * FROM users');
+query.where('dept', 'Marketing');
+
+const rows = runPrisma(prisma, query, { engine: 'pg' });
+```
+
+`runPrismaWithCount()` will run a query using Prisma and return the results,
+found rows and pagination.
+
+```js
+import { SelectBuilder, runPrisma, runPrismaWithCount } from 'sql-love';
+import { prisma } from '~/db.server';
+
+const query = new SelectBuilder('SELECT * FROM users')
+  .where('dept', 'Marketing')
+  .limit(2)
+  .page(5);
+const { records, total, pagination } = await runPrismaWithCount(prisma, query, {
+  engine: 'pg',
+});
+```
+
+See [getPagination](#getpagination) for details on the pagination object.
+
+### runMysql and runMysqlWithCount
+
+### runPg and runPgWithCount

package/dist/index.d.ts

@@ -1,2 +1,6 @@
 export { default as Parser } from './src/Parser/Parser';
 export { default as SelectBuilder } from './src/SelectBuilder/SelectBuilder';
+export { default as extractGrouped } from './src/extractGrouped/extractGrouped';
+export { default as extractIndexed } from './src/extractIndexed/extractIndexed';
+export { default as getPagination } from './src/getPagination/getPagination';
+export { runPrisma, runPrismaWithCount } from './src/runPrisma/runPrisma';

package/dist/index.js

@@ -1,2 +1,6 @@
 export { default as Parser } from './src/Parser/Parser';
 export { default as SelectBuilder } from './src/SelectBuilder/SelectBuilder';
+export { default as extractGrouped } from './src/extractGrouped/extractGrouped';
+export { default as extractIndexed } from './src/extractIndexed/extractIndexed';
+export { default as getPagination } from './src/getPagination/getPagination';
+export { runPrisma, runPrismaWithCount } from './src/runPrisma/runPrisma';

package/dist/src/SelectBuilder/SelectBuilder.d.ts

@@ -73,12 +73,20 @@ export default class SelectBuilder {
      * @param [bindings]  Placeholders to bind to the query
      */
     constructor(sql?: string, bindings?: Record<string, any>);
+    /**
+     * Set the default database engine style (mssql, mysql, oracle, pg)
+     * @param engine
+     */
+    static setDefaultEngine(engine: EngineStyle): typeof SelectBuilder;
     /**
      * Get the SQL as a pretty-printed string alongside an array of bindings
-     * @param engineStyle  The database engine style (mssql, mysql, oracle, pg)
+     * @param engine  The database engine style (mssql, mysql, oracle, pg)
      * @return The SQL query as a string
      */
-    compile(engineStyle?: EngineStyle): {
+    compile({ engine, bindingIndex, }?: {
+        engine?: EngineStyle;
+        bindingIndex?: number;
+    }): {
         sql: string;
         bindings: any;
     };
@@ -89,10 +97,26 @@ export default class SelectBuilder {
      * @param engineStyle  The database engine style (mssql, mysql, oracle, pg)
      * @param countExpr  The expression to use inside the COUNT()
      */
-    compileCount(engineStyle?: EngineStyle, countExpr?: string): {
+    compileCount({ countExpr, engine, bindingIndex, }?: {
+        countExpr?: string;
+        engine?: EngineStyle;
+        bindingIndex?: number;
+    }): {
         sql: string;
         bindings: any;
     };
+    /**
+     * Get SQL needed to union this query with another
+     * @param query  The query to union
+     * @param engine  The database engine style (mssql, mysql, oracle, pg)
+     */
+    compileUnion(query: SelectBuilder, { engine, bindingIndex, }?: {
+        engine?: EngineStyle;
+        bindingIndex?: number;
+    }): {
+        sql: string;
+        bindings: any[];
+    };
     /**
      * @param  [fieldOrFields]  If given, reset the given component(s), otherwise reset all query components
      *   Valid components: option, column, table, where, orWhere, having, groupBy, orderBy, limit, offset, page
@@ -290,17 +314,17 @@ export default class SelectBuilder {
      * Add a series of WHERE clauses joined by OR (See _conditions for usage)
      * @param conditions
      */
-    _orConditions(conditions: WhereCriteria[] | Record<string, any>[]): string;
+    _orConditions(conditions: WhereCriteria[] | Record<string, any>[] | Record<string, any>): string;
     /**
      * Add WHERE conditions to place inside an OR block (See _conditions for usage)
      * @param conditions  A list or object where each item is an array with parameters that would be taken by where()
      */
-    orWhere(conditions: WhereCriteria[] | Record<string, any>[]): this;
+    orWhere(conditions: WhereCriteria[] | Record<string, any>[] | Record<string, any>): this;
     /**
      * Add an OR with conditions under the HAVING clause
      * @param conditions  A list or object where each item is an array with parameters that would be taken by having()
      */
-    orHaving(conditions: WhereCriteria[] | Record<string, any>[]): this;
+    orHaving(conditions: WhereCriteria[] | Record<string, any>[] | Record<string, any>): this;
     /**
      * Add a HAVING condition (See _conditions for usage)
      */
@@ -352,5 +376,4 @@ export default class SelectBuilder {
      * @param number  The page number (integer greater than 0)
      */
     page(number: number | string): this;
-    fetch(engine: any): void;
 }

package/dist/src/SelectBuilder/SelectBuilder.js

@@ -1,6 +1,7 @@
 import Parser from '../Parser/Parser';
 import substrCount from '../substrCount/substrCount';
 const isNullish = v => v === undefined || v === null || v === false || isNaN(v);
+let defaultEngine = 'mysql';
 /**
  * Build a select query
  * Class Select
@@ -85,12 +86,20 @@ export default class SelectBuilder {
             new Parser(this).parse(sql);
         }
     }
+    /**
+     * Set the default database engine style (mssql, mysql, oracle, pg)
+     * @param engine
+     */
+    static setDefaultEngine(engine) {
+        defaultEngine = engine;
+        return SelectBuilder;
+    }
     /**
      * Get the SQL as a pretty-printed string alongside an array of bindings
-     * @param engineStyle  The database engine style (mssql, mysql, oracle, pg)
+     * @param engine  The database engine style (mssql, mysql, oracle, pg)
      * @return The SQL query as a string
      */
-    compile(engineStyle = 'mysql') {
+    compile({ engine = defaultEngine, bindingIndex = 1, } = {}) {
         // build all the lines
         const lines = [
             'SELECT',
@@ -105,29 +114,29 @@ export default class SelectBuilder {
         ];
         if (this._page > 0) {
             const offset = (this._page - 1) * this._limit;
-            lines.push(this._compileOFFSET(engineStyle, offset));
-            lines.push(this._compileLIMIT(engineStyle, this._limit));
+            lines.push(this._compileOFFSET(engine, offset));
+            lines.push(this._compileLIMIT(engine, this._limit));
         }
         else {
             if (this._offset) {
-                lines.push(this._compileOFFSET(engineStyle, this._offset));
+                lines.push(this._compileOFFSET(engine, this._offset));
             }
             if (this._limit) {
-                lines.push(this._compileLIMIT(engineStyle, this._limit));
+                lines.push(this._compileLIMIT(engine, this._limit));
             }
         }
         const pretty = lines.filter(Boolean).join('\n').trim();
         let replacer;
         const bindings = [];
-        if (engineStyle === 'pg') {
-            let idx = 1;
-            replacer = ($0, $1) => {
+        if (engine === 'pg') {
+            let idx = bindingIndex;
+            replacer = (_, $1) => {
                 bindings.push(this._bindings[$1]);
                 return '$' + idx++;
             };
         }
         else {
-            replacer = ($0, $1) => {
+            replacer = (_, $1) => {
                 bindings.push(this._bindings[$1]);
                 return '?';
             };
@@ -156,9 +165,9 @@ export default class SelectBuilder {
      * @param engineStyle  The database engine style (mssql, mysql, oracle, pg)
      * @param countExpr  The expression to use inside the COUNT()
      */
-    compileCount(engineStyle = 'mysql', countExpr = '*') {
+    compileCount({ countExpr = '*', engine = defaultEngine, bindingIndex = 1, } = {}) {
         const query = this.getFoundRowsQuery(countExpr);
-        const { sql, bindings } = query.compile(engineStyle);
+        const { sql, bindings } = query.compile({ engine, bindingIndex });
         if (this._havings.length === 0) {
             return { sql, bindings };
         }
@@ -170,6 +179,22 @@ export default class SelectBuilder {
             };
         }
     }
+    /**
+     * Get SQL needed to union this query with another
+     * @param query  The query to union
+     * @param engine  The database engine style (mssql, mysql, oracle, pg)
+     */
+    compileUnion(query, { engine = defaultEngine, bindingIndex = 1, } = {}) {
+        const first = this.compile({ engine, bindingIndex });
+        const second = query.compile({
+            engine,
+            bindingIndex: first.bindings.length + bindingIndex,
+        });
+        return {
+            sql: `(${first.sql})\nUNION\n(${second.sql})`,
+            bindings: [...first.bindings, ...second.bindings],
+        };
+    }
     /**
      * @param  [fieldOrFields]  If given, reset the given component(s), otherwise reset all query components
      *   Valid components: option, column, table, where, orWhere, having, groupBy, orderBy, limit, offset, page
@@ -618,12 +643,21 @@ export default class SelectBuilder {
      */
     _orConditions(conditions) {
         const items = [];
-        for (const condition of conditions) {
-            if (Array.isArray(condition)) {
-                this._conditions(items, condition);
+        if (Array.isArray(conditions)) {
+            for (const condition of conditions) {
+                if (Array.isArray(condition)) {
+                    this._conditions(items, condition);
+                }
+                else {
+                    this._conditions(items, [condition]);
+                }
             }
-            else {
-                this._conditions(items, [condition]);
+        }
+        else {
+            for (const [key, value] of Object.entries(conditions)) {
+                const one = [];
+                this._conditions(one, [key, value]);
+                items.push(one[0]);
             }
         }
         const joined = items.join(' OR ');
@@ -769,9 +803,4 @@ export default class SelectBuilder {
         }
         return this;
     }
-    fetch(engine) {
-        if (engine.$queryRawUnsafe) {
-            //
-        }
-    }
 }

package/dist/src/extractGrouped/extractGrouped.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Group database rows by a column value
+ * @param field  The database column to group by
+ * @param records  Records from the database
+ * @example
+ * extractGrouped('org', users); // result:
+ * {
+ *     "Marketing": [
+ *         { id: 1, name: "John", org: "Marketing" },
+ *         { id: 2, name: "Jane", org: "Marketing" },
+ *     ],
+ *     "Finance": [
+ *         { id: 3, name: "Jose", org: "Finance" },
+ *     ],
+ * }
+ */
+export default function extractGrouped<DbRecord extends Record<string, any>>(field: keyof DbRecord, records: DbRecord[]): Record<string, DbRecord[]>;

package/dist/src/extractGrouped/extractGrouped.js

@@ -0,0 +1,31 @@
+/**
+ * Group database rows by a column value
+ * @param field  The database column to group by
+ * @param records  Records from the database
+ * @example
+ * extractGrouped('org', users); // result:
+ * {
+ *     "Marketing": [
+ *         { id: 1, name: "John", org: "Marketing" },
+ *         { id: 2, name: "Jane", org: "Marketing" },
+ *     ],
+ *     "Finance": [
+ *         { id: 3, name: "Jose", org: "Finance" },
+ *     ],
+ * }
+ */
+export default function extractGrouped(field, records) {
+    let idx = 0;
+    const grouped = {};
+    for (const record of records) {
+        if (!(field in record)) {
+            throw new Error(`Column "${String(field)}" is not present in record ${idx}`);
+        }
+        if (!grouped[record[field]]) {
+            grouped[record[field]] = [];
+        }
+        grouped[record[field]].push(record);
+        idx++;
+    }
+    return grouped;
+}