sql-love 0.9.6 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## Change Log
 
+### v1.0.0 - 12 Dec 2023
+
+- Upgrade to vitest v1
+- More documentation
+- 100% test coverage
+- First stable release
+
+### v0.9.7 - 7 Dec 2023
+
+- Added extractLookup utility
+- Added toSafeJson utilities
+
 ### v0.9.6 - 5 Dec 2023
 
 - Utility functions (extractGrouped, extractIndexed, getPagination, runPrisma, runMysql)

package/LICENSE.md

@@ -1,5 +1,5 @@
 ISC License (ISC)
-Copyright 2021-2023 Ken Snyder
+Copyright 2023 Ken Snyder
 
 Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
 

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.6" width="250" height="208" />
+<img alt="SQL Love Logo" src="https://github.com/kensnyder/sql-love/raw/main/assets/sql-love-logo.png?v=1.0.1" width="250" height="208" />
 
 # sql-love
 
-[![NPM Link](https://badgen.net/npm/v/sql-love?v=0.9.6)](https://npmjs.com/package/sql-love)
-[![Dependencies](https://badgen.net/static/dependencies/0/green?v=0.9.6)](https://npmjs.com/package/sql-love)
-[![Build Status](https://github.com/kensnyder/sql-love/actions/workflows/node.js.yml/badge.svg?v=0.9.6)](https://github.com/kensnyder/sql-love/actions)
-[![Code Coverage](https://codecov.io/gh/kensnyder/sql-love/branch/main/graph/badge.svg?v=0.9.6)](https://codecov.io/gh/kensnyder/sql-love)
-[![ISC License](https://badgen.net/static/license/ISC/green?v=0.9.6)](https://opensource.org/licenses/ISC)
+[![NPM Link](https://badgen.net/npm/v/sql-love?v=1.0.1)](https://npmjs.com/package/sql-love)
+[![Dependencies](https://badgen.net/static/dependencies/0/green?v=1.0.1)](https://www.npmjs.com/package/sql-love?activeTab=dependencies)
+[![Build Status](https://github.com/kensnyder/sql-love/actions/workflows/node.js.yml/badge.svg?v=1.0.1)](https://github.com/kensnyder/sql-love/actions)
+[![Code Coverage](https://codecov.io/gh/kensnyder/sql-love/branch/main/graph/badge.svg?v=1.0.1)](https://codecov.io/gh/kensnyder/sql-love)
+[![ISC License](https://badgen.net/static/license/ISC/green?v=1.0.1)](https://opensource.org/licenses/ISC)
 
 Classes for parsing and building SQL select queries in Node
 
@@ -22,17 +22,18 @@ npm install sql-love
   - [Parsing base SQL](#parsing-base-sql)
   - [SQL injection](#sql-injection)
   - [Building the Query](#building-the-query)
-  - [More examples](#where-examples)
+  - [More examples](#more-examples)
   - [Counting results](#counting-results)
   - [Other methods](#other-methods)
-  - [new SelectBuilder() limitations](#selectparse-limitations)
+  - [Parser limitations](#parser-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)
+  - [extractGrouped](#extractgrouped)
+  - [extractIndexed](#extractindexed)
+  - [extractLookup](#extractlookup)
+  - [runPrisma and runPrismaWithCount](#runprisma-and-runprismawithcount)
+  - [runMysql and runMysqlWithCount](#runmysql-and-runmysqlwithcount)
+  - [toSafeJson functions](#tosafejson)
 - [How to contribute](./CONTRIBUTING.md)
 - [ISC license](./LICENSE.md)
 
@@ -64,17 +65,29 @@ if (areaCode) {
 query.sort(sortField);
 query.limit(limitTo);
 const { sql, bindings } = query.compile();
+```
+
+Then execute the SQL in your preferred client:
 
-// then execute the SQL in your preferred client:
-// like mysql2
+```js
+// mysql2:
 connection.query(sql, bindings, (err, results, fields) => {});
-// or Prisma
+
+// 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.
+// Cloudflare d1
+const { results } = await env.DB.prepare(sql)
+  .bind(...bindings)
+  .all();
 ```
 
+_Note that these are prepared statements so the values in the "bindings"_
+_array are safe from SQL injection, with the caveat that you are in charge of_
+_quoting any identifiers. For instance, we don't recommend populating `u.email`_
+_from user input in the example above. But if you do, be sure to use your_
+_client's `quoteIdentifier()` function._
+
 It is possible to add placeholders to the base query.
 
 ```js
@@ -110,7 +123,7 @@ And "bindings" equals:
 You may specify a compiler engine to use. The default is `"mysql"`.
 
 ```js
-import { SelectBuilder } from 'sql-love';
+import { SelectBuilder, setDefaultEngine } from 'sql-love';
 
 const query = new SelectBuilder('SELECT * FROM users')
   .limit(10)
@@ -118,19 +131,18 @@ const query = new SelectBuilder('SELECT * FROM users')
   .where('id', 1);
 
 query.compile({ engine: 'mysql' }).sql;
+query.compile({ engine: 'sqlite' }).sql;
 // SELECT * FROM users WHERE id = ? OFFSET 20 LIMIT 10
 
 query.compile({ engine: 'pg' }).sql;
 // SELECT * FROM users WHERE id = $1 OFFSET 20 LIMIT 10
 
 query.compile({ engine: 'mssql' }).sql;
-// SELECT * FROM users WHERE id = ? OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY
-
 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');
+setDefaultEngine('pg');
 ```
 
 ### SQL injection
@@ -138,10 +150,19 @@ SelectBuilder.setDefaultEngine('pg');
 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
+Using `mysqlClient.query(sql, bindings)` and
+`prisma.$queryRawUnsafe(sql, ...bindings)` are examples of using prepared
 statements.
 
+Note that even though the name `prisma.$queryRawUnsafe(sql, ...bindings)`
+implies that the query is unsafe, it is actually safe because
+`prisma.$queryRawUnsafe` uses prepared statements.
+
+SQL Love also includes utility functions for running queries in mysql and
+Prisma so you don't have to remember these functions. See documentation for
+[runPrisma](#runprisma-and-runprismawithcount) and
+[runMysql](#runmysql-and-runmysqlwithcount) below.
+
 ### Building the query
 
 Use the following methods to build queries. And see
@@ -221,7 +242,17 @@ 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 how to use question marks for binding
+query.where(
+  'users.id IN (SELECT user_id FROM roles WHERE customer_id IN (?, ?))',
+  [1, 2]
+);
+query.where(
+  'users.id IN (SELECT user_id FROM roles WHERE customer_id = ?)',
+  // even if there is only one placeholder, you must use an array
+  [1]
+);
 
 // The following demonstrates using objects to specify multiple conditions
 query.where({
@@ -233,6 +264,8 @@ query.where({
   conditions: ['new', 'used'],
 });
 
+// Note: .having() supports the same signatures as .where()
+
 // The following demonstrate equivalent ways to use OR
 query.orWhere([{ approved_at: null }, { denied_at: null }]);
 query.orWhere({ approved_at: null, denied_at: null });
@@ -242,6 +275,7 @@ query.orWhere([
   ['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
@@ -451,12 +485,31 @@ const grouped = extractGrouped('dept', records);
 */
 ```
 
+### extractLookup
+
+You can create a lookup object based on a results set
+
+```js
+const records = [
+  { id: 1, name: 'John', age: 30 },
+  { id: 2, name: 'Jane', age: 35 },
+];
+
+const nameById = extractLookup('id', 'name', records);
+/*
+{ 
+  '1': 'John',
+  '2': 'Jane',
+}
+*/
+```
+
 ### runPrisma and runPrismaWithCount
 
 `runPrisma()` will run a query using Prisma and return the results.
 
 ```js
-import { SelectBuilder, runPrisma, runPrismaWithCount } from 'sql-love';
+import { SelectBuilder, runPrisma } from 'sql-love';
 import { prisma } from '~/db.server';
 
 const query = new SelectBuilder('SELECT * FROM users');
@@ -469,7 +522,7 @@ const rows = runPrisma(prisma, query, { engine: 'pg' });
 found rows and pagination.
 
 ```js
-import { SelectBuilder, runPrisma, runPrismaWithCount } from 'sql-love';
+import { SelectBuilder, runPrismaWithCount } from 'sql-love';
 import { prisma } from '~/db.server';
 
 const query = new SelectBuilder('SELECT * FROM users')
@@ -485,4 +538,74 @@ See [getPagination](#getpagination) for details on the pagination object.
 
 ### runMysql and runMysqlWithCount
 
-### runPg and runPgWithCount
+`runMysql()` will run a query using mysql and return the results.
+
+```js
+import { SelectBuilder, runMysql } from 'sql-love';
+import { mysql } from 'mysql2';
+const client = mysql.createConnection(config);
+
+const query = new SelectBuilder('SELECT * FROM users');
+query.where('dept', 'Marketing');
+
+const rows = await runMysql(client, query);
+```
+
+`runMysqlWithCount()` will run a query using mysql and return the results,
+found rows and pagination.
+
+```js
+import { SelectBuilder, runMysqlWithCount } from 'sql-love';
+import { mysql } from 'mysql2';
+const client = mysql.createConnection(config);
+
+const query = new SelectBuilder('SELECT * FROM users')
+  .where('dept', 'Marketing')
+  .limit(2)
+  .page(5);
+
+const { records, total, pagination } = await runMysqlWithCount(client, query);
+```
+
+You can also use the mysql2 promise api:
+
+```js
+import { SelectBuilder, runMysqlAsync, runMysqlAsyncWithCount } from 'sql-love';
+import { mysql } from 'mysql2/promise';
+const client = await mysql.createConnection(config);
+
+const query = new SelectBuilder('SELECT * FROM users')
+  .where('dept', 'Marketing')
+  .limit(2)
+  .page(5);
+
+const records = await runMysqlAsync(client, query);
+// OR
+const { records, total, pagination } = await runMysqlAsyncWithCount(
+  client,
+  query
+);
+```
+
+### toSafeJson
+
+With some database clients such as Prisma, your recordsets may contain BigInt
+objects. These are not safe to pass to JSON.stringify(). The following are
+examples of the toSafeJson\* utility functions.
+
+```js
+import { toSafeJsonString, toSafeJsonRecords } from 'sql-love';
+
+const records = [{ count: 12n }, { count: 9007199254740993n }];
+
+toSafeJsonRecords(records);
+// [
+//   { count: 12 },
+//   { count: "9007199254740993" },
+// ]
+
+toSafeJsonString(records);
+// '[{"count":12},{"count":"9007199254740993"}]'
+
+// Note that BigInt values too big for Number are converted to strings
+```

package/dist/index.d.ts

@@ -2,5 +2,8 @@ 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 extractLookup } from './src/extractLookup/extractLookup';
 export { default as getPagination } from './src/getPagination/getPagination';
+export { runMysql, runMysqlAsync, runMysqlAsyncWithCount, runMysqlWithCount, } from './src/runMysql/runMysql';
 export { runPrisma, runPrismaWithCount } from './src/runPrisma/runPrisma';
+export { toSafeJsonRecord, toSafeJsonRecords, toSafeJsonString, toSafeJsonValue, } from './src/toSafeJson/toSafeJson';

package/dist/index.js

@@ -2,5 +2,8 @@ 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 extractLookup } from './src/extractLookup/extractLookup';
 export { default as getPagination } from './src/getPagination/getPagination';
+export { runMysql, runMysqlAsync, runMysqlAsyncWithCount, runMysqlWithCount, } from './src/runMysql/runMysql';
 export { runPrisma, runPrismaWithCount } from './src/runPrisma/runPrisma';
+export { toSafeJsonRecord, toSafeJsonRecords, toSafeJsonString, toSafeJsonValue, } from './src/toSafeJson/toSafeJson';

package/dist/src/extractLookup/extractLookup.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Given an array of records, extract an object with keyField-valueField pairs
+ * @param records  An array of records
+ * @param keyField  The field to use as the key
+ * @param valueField  The field to use as the value
+ */
+export default function extractLookup<T extends Array<Record<K | V, any>>, K extends keyof T[number], V extends keyof T[number]>(keyField: K, valueField: V, records: T): {
+    [key in T[number][K]]: T[number][V];
+};

package/dist/src/extractLookup/extractLookup.js

@@ -0,0 +1,21 @@
+/**
+ * Given an array of records, extract an object with keyField-valueField pairs
+ * @param records  An array of records
+ * @param keyField  The field to use as the key
+ * @param valueField  The field to use as the value
+ */
+export default function extractLookup(keyField, valueField, records) {
+    const lookup = {};
+    let idx = 0;
+    for (const record of records) {
+        if (!(keyField in record)) {
+            throw new Error(`Column "${String(keyField)}" is not present in record ${idx}`);
+        }
+        if (!(valueField in record)) {
+            throw new Error(`Column "${String(valueField)}" is not present in record ${idx}`);
+        }
+        idx++;
+        lookup[String(record[keyField])] = record[valueField];
+    }
+    return lookup;
+}

package/dist/src/getPagination/getPagination.js

@@ -5,13 +5,28 @@
  */
 export default function getPagination(query, total) {
     total = Number(total) || 0;
-    const page = Number(query._page) || 1;
-    const perPage = Number(query._limit);
-    const numPages = Math.ceil(total / perPage) || 0;
+    const perPage = Number(query._limit) || null;
+    let page = null;
+    if (total === 0) {
+        page = null;
+    }
+    else if (query._page) {
+        page = Number(query._page);
+    }
+    else if (query._limit && query._offset) {
+        page = Math.floor(Number(query._offset) / Number(query._limit)) + 1;
+    }
+    else if (query._limit && !query._offset) {
+        page = 1;
+    }
+    else {
+        page = null;
+    }
+    const numPages = total === 0 || perPage === null ? 0 : Math.ceil(total / perPage) || 0;
     const isFirst = page === 1;
-    const isLast = page === numPages;
-    const prevPage = page - 1 || null;
-    const nextPage = page + 1 <= numPages ? page + 1 : null;
+    const isLast = numPages > 0 && page === numPages;
+    const prevPage = numPages === 0 ? null : page - 1 || null;
+    const nextPage = numPages > 0 && page + 1 <= numPages ? page + 1 : null;
     return {
         page,
         prevPage,

package/dist/src/runMysql/runMysql.d.ts

@@ -6,7 +6,19 @@ interface MysqlClient {
 interface MysqlAsyncClient {
     query: (sql: string, bindings: any[]) => Promise<[Array<Record<string, any>>, any[]]>;
 }
+/**
+ * Run the given query with mysql and return the results
+ * @param mysqlClient  A client created with mysql.createConnection()  or mysql.createPool()
+ * @param query  The SelectBuilder query to run
+ */
 export declare function runMysql(mysqlClient: MysqlClient, query: SelectBuilder): Promise<[Array<Record<string, any>>, any[]]>;
+/**
+ * Run the given query with mysql and return the results, count, and pagination
+ * @param mysqlClient  A client created with mysql.createConnection()  or mysql.createPool()
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.countExpr  The SQL expression to use for the count (default "*")
+ */
 export declare function runMysqlWithCount(mysqlClient: MysqlClient, query: SelectBuilder, { countExpr }?: {
     countExpr?: string;
 }): Promise<{

package/dist/src/runMysql/runMysql.js

@@ -10,10 +10,22 @@ function _queryToPromise(mysqlClient, sql, bindings) {
         });
     });
 }
+/**
+ * Run the given query with mysql and return the results
+ * @param mysqlClient  A client created with mysql.createConnection()  or mysql.createPool()
+ * @param query  The SelectBuilder query to run
+ */
 export async function runMysql(mysqlClient, query) {
     const { sql, bindings } = query.compile({ engine: 'mysql' });
     return _queryToPromise(mysqlClient, sql, bindings);
 }
+/**
+ * Run the given query with mysql and return the results, count, and pagination
+ * @param mysqlClient  A client created with mysql.createConnection()  or mysql.createPool()
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.countExpr  The SQL expression to use for the count (default "*")
+ */
 export async function runMysqlWithCount(mysqlClient, query, { countExpr = '*' } = {}) {
     const { sql, bindings } = query.compile({ engine: 'mysql' });
     const [records, fields] = await _queryToPromise(mysqlClient, sql, bindings);

package/dist/src/runPrisma/runPrisma.d.ts

@@ -3,9 +3,24 @@ import type { EngineStyle } from '../SelectBuilder/SelectBuilder';
 interface PrismaClient {
     $queryRawUnsafe: (sql: string, ...bindings: any[]) => Promise<Array<Record<string, any>>>;
 }
+/**
+ * Run the given query with prisma and return the results
+ * @param prisma  The prisma client instance
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.engine  The engine style to use ("mssql" | "mysql" | "oracle" | "pg")
+ */
 export declare function runPrisma(prisma: PrismaClient, query: SelectBuilder, { engine }?: {
     engine?: EngineStyle;
 }): Promise<Array<Record<string, any>>>;
+/**
+ * Run the given query with prisma and return the results, count, and pagination
+ * @param prisma  The prisma client instance
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.engine  The engine style to use ("mssql" | "mysql" | "oracle" | "pg")
+ * @param options.countExpr  The SQL expression to use for the count (default "*")
+ */
 export declare function runPrismaWithCount(prisma: PrismaClient, query: SelectBuilder, { engine, countExpr, }?: {
     engine?: EngineStyle;
     countExpr?: string;

package/dist/src/runPrisma/runPrisma.js

@@ -1,15 +1,31 @@
 import getPagination from '../getPagination/getPagination';
+import { toSafeJsonValue } from '../toSafeJson/toSafeJson';
+/**
+ * Run the given query with prisma and return the results
+ * @param prisma  The prisma client instance
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.engine  The engine style to use ("mssql" | "mysql" | "oracle" | "pg")
+ */
 export async function runPrisma(prisma, query, { engine = undefined } = {}) {
     const { sql, bindings } = query.compile({ engine });
     return prisma.$queryRawUnsafe(sql, ...bindings);
 }
+/**
+ * Run the given query with prisma and return the results, count, and pagination
+ * @param prisma  The prisma client instance
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.engine  The engine style to use ("mssql" | "mysql" | "oracle" | "pg")
+ * @param options.countExpr  The SQL expression to use for the count (default "*")
+ */
 export async function runPrismaWithCount(prisma, query, { engine = undefined, countExpr = '*', } = {}) {
     const { sql, bindings } = query.compile({ engine });
     const records = await prisma.$queryRawUnsafe(sql, ...bindings);
     if (records.length > 0) {
         const { sql, bindings } = query.compileCount({ engine, countExpr });
         const result = await prisma.$queryRawUnsafe(sql, ...bindings);
-        const total = result[0].found_rows;
+        const total = toSafeJsonValue(result[0].found_rows);
         return { records, total, pagination: getPagination(query, total) };
     }
     else {

package/dist/src/substrCount/substrCount.d.ts

@@ -1 +1,6 @@
+/**
+ * Count the number of times a substring appears in a string
+ * @param haystack
+ * @param needle
+ */
 export default function substrCount(haystack: string, needle: string): number;

package/dist/src/substrCount/substrCount.js

@@ -1,3 +1,8 @@
+/**
+ * Count the number of times a substring appears in a string
+ * @param haystack
+ * @param needle
+ */
 export default function substrCount(haystack, needle) {
     let count = 0;
     let pos = haystack.indexOf(needle);

package/dist/src/toSafeJson/toSafeJson.d.ts

@@ -0,0 +1,25 @@
+type SafeValue<T> = T extends BigInt ? number | string : T extends Date ? string : T;
+type SafeRecord<T> = Record<string, SafeValue<T>>;
+type SafeRecords<T> = Array<SafeRecord<T>>;
+/**
+ * Convert a value to a value that can be safely serialized to JSON
+ * @param value
+ */
+export declare function toSafeJsonValue<T>(value: T): SafeValue<T>;
+/**
+ * Convert a record to one that can be safely serialized to JSON
+ * @param record
+ */
+export declare function toSafeJsonRecord<T extends Record<string, any>>(record: T): SafeRecord<T>;
+/**
+ * Convert a recordset to one that can be safely serialized to JSON
+ * @param records
+ */
+export declare function toSafeJsonRecords<T extends Record<string, any>>(records: T[]): SafeRecords<T>;
+/**
+ * JSON stringify a value or data structure, ensuring first that all values are
+ *   safe to serialize
+ * @param records
+ */
+export declare function toSafeJsonString(records: Array<Record<string, any>>): string;
+export {};

package/dist/src/toSafeJson/toSafeJson.js

@@ -0,0 +1,48 @@
+/**
+ * Convert a value to a value that can be safely serialized to JSON
+ * @param value
+ */
+export function toSafeJsonValue(value) {
+    if (typeof value === 'bigint') {
+        const asNumber = Number(value);
+        // Use double equals instead of triple equals below to check if the BigInt
+        //   is too big to fit in a JS Number.
+        //   If so, then return it as a string, otherwise return it as a Number
+        // @ts-expect-error
+        return value == asNumber ? asNumber : value.toString();
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return value;
+}
+/**
+ * Convert a record to one that can be safely serialized to JSON
+ * @param record
+ */
+export function toSafeJsonRecord(record) {
+    const newRecord = {};
+    for (const key in record) {
+        /* v8 ignore next 3 */
+        if (!Object.prototype.hasOwnProperty.call(record, key)) {
+            continue;
+        }
+        newRecord[key] = toSafeJsonValue(record[key]);
+    }
+    return newRecord;
+}
+/**
+ * Convert a recordset to one that can be safely serialized to JSON
+ * @param records
+ */
+export function toSafeJsonRecords(records) {
+    return records.map(toSafeJsonRecord);
+}
+/**
+ * JSON stringify a value or data structure, ensuring first that all values are
+ *   safe to serialize
+ * @param records
+ */
+export function toSafeJsonString(records) {
+    return JSON.stringify(records, (_, value) => toSafeJsonValue(value));
+}

package/index.ts

@@ -2,5 +2,18 @@ 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 extractLookup } from './src/extractLookup/extractLookup';
 export { default as getPagination } from './src/getPagination/getPagination';
+export {
+  runMysql,
+  runMysqlAsync,
+  runMysqlAsyncWithCount,
+  runMysqlWithCount,
+} from './src/runMysql/runMysql';
 export { runPrisma, runPrismaWithCount } from './src/runPrisma/runPrisma';
+export {
+  toSafeJsonRecord,
+  toSafeJsonRecords,
+  toSafeJsonString,
+  toSafeJsonValue,
+} from './src/toSafeJson/toSafeJson';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sql-love",
-  "version": "0.9.6",
+  "version": "1.0.1",
   "description": "Build SQL queries with JavaScript",
   "main": "dist/index.js",
   "type": "module",
@@ -32,11 +32,11 @@
   },
   "homepage": "https://github.com/kensnyder/sql-love#readme",
   "devDependencies": {
-    "@vitest/coverage-v8": "0.34.6",
-    "prettier": "3.1.0",
+    "@vitest/coverage-v8": "1.3.1",
+    "prettier": "3.2.5",
     "prettier-plugin-organize-imports": "3.2.4",
     "rimraf": "5.0.5",
-    "typescript": "5.3.2",
-    "vitest": "0.34.6"
+    "typescript": "5.3.3",
+    "vitest": "1.3.1"
   }
 }

package/src/extractLookup/extractLookup.spec.ts

@@ -0,0 +1,38 @@
+import extractLookup from './extractLookup';
+
+describe('extractLookup()', () => {
+  it('should handle lookup by number', () => {
+    const records = [
+      { id: 1, name: 'John', age: 30 },
+      { id: 2, name: 'Jane', age: 35 },
+    ];
+    const nameById = extractLookup('id', 'name', records);
+    expect(nameById).toEqual({ '1': 'John', '2': 'Jane' });
+  });
+  it('should handle lookups with non-unique fields', () => {
+    const records = [
+      { id: 1, name: 'John', age: 30 },
+      { id: 2, name: 'Jane', age: 30 },
+    ];
+    const ageById = extractLookup('age', 'name', records);
+    expect(ageById).toEqual({ '30': 'Jane' });
+  });
+  it('should throw if key field is not present', () => {
+    const records = [
+      { id: 1, name: 'John', age: 30 },
+      { id: 2, name: 'Jane' },
+    ];
+    // @ts-expect-error
+    const thrower = () => extractLookup('age', 'name', records);
+    expect(thrower).toThrow();
+  });
+  it('should throw if value field is not present', () => {
+    const records = [
+      { id: 1, name: 'John', age: 30 },
+      { id: 2, name: 'Jane' },
+    ];
+    // @ts-expect-error
+    const thrower = () => extractLookup('id', 'age', records);
+    expect(thrower).toThrow();
+  });
+});

package/src/extractLookup/extractLookup.ts

@@ -0,0 +1,33 @@
+/**
+ * Given an array of records, extract an object with keyField-valueField pairs
+ * @param records  An array of records
+ * @param keyField  The field to use as the key
+ * @param valueField  The field to use as the value
+ */
+export default function extractLookup<
+  T extends Array<Record<K | V, any>>,
+  K extends keyof T[number],
+  V extends keyof T[number],
+>(
+  keyField: K,
+  valueField: V,
+  records: T
+): { [key in T[number][K]]: T[number][V] } {
+  const lookup: { [key in T[number][K]]: T[number][V] } = {} as any;
+  let idx = 0;
+  for (const record of records) {
+    if (!(keyField in record)) {
+      throw new Error(
+        `Column "${String(keyField)}" is not present in record ${idx}`
+      );
+    }
+    if (!(valueField in record)) {
+      throw new Error(
+        `Column "${String(valueField)}" is not present in record ${idx}`
+      );
+    }
+    idx++;
+    lookup[String(record[keyField])] = record[valueField];
+  }
+  return lookup;
+}

package/src/getPagination/getPagination.spec.ts

@@ -17,6 +17,20 @@ describe('getPagination()', () => {
     });
   });
   it('should handle 42 results with offset', () => {
+    const query = new SelectBuilder('SELECT * FROM users LIMIT 10').offset(20);
+    const pagination = getPagination(query, 42n);
+    expect(pagination).toEqual({
+      page: 3,
+      prevPage: 2,
+      nextPage: 4,
+      perPage: 10,
+      numPages: 5,
+      total: 42,
+      isFirst: false,
+      isLast: false,
+    });
+  });
+  it('should handle 42 results with page', () => {
     const query = new SelectBuilder('SELECT * FROM users LIMIT 10').page(3);
     const pagination = getPagination(query, 42n);
     expect(pagination).toEqual({
@@ -34,13 +48,13 @@ describe('getPagination()', () => {
     const query = new SelectBuilder('SELECT * FROM users LIMIT 10');
     const pagination = getPagination(query, 0);
     expect(pagination).toEqual({
-      page: 1,
+      page: null,
       prevPage: null,
       nextPage: null,
       perPage: 10,
       numPages: 0,
       total: 0,
-      isFirst: true,
+      isFirst: false,
       isLast: false,
     });
   });
@@ -48,13 +62,13 @@ describe('getPagination()', () => {
     const query = new SelectBuilder('SELECT * FROM users');
     const pagination = getPagination(query, 42);
     expect(pagination).toEqual({
-      page: 1,
+      page: null,
       prevPage: null,
       nextPage: null,
-      perPage: NaN,
+      perPage: null,
       numPages: 0,
       total: 42,
-      isFirst: true,
+      isFirst: false,
       isLast: false,
     });
   });

package/src/getPagination/getPagination.ts

@@ -10,13 +10,25 @@ export default function getPagination(
   total: BigInt | number
 ) {
   total = Number(total) || 0;
-  const page = Number(query._page) || 1;
-  const perPage = Number(query._limit);
-  const numPages = Math.ceil(total / perPage) || 0;
+  const perPage = Number(query._limit) || null;
+  let page: number | null = null;
+  if (total === 0) {
+    page = null;
+  } else if (query._page) {
+    page = Number(query._page);
+  } else if (query._limit && query._offset) {
+    page = Math.floor(Number(query._offset) / Number(query._limit)) + 1;
+  } else if (query._limit && !query._offset) {
+    page = 1;
+  } else {
+    page = null;
+  }
+  const numPages =
+    total === 0 || perPage === null ? 0 : Math.ceil(total / perPage) || 0;
   const isFirst = page === 1;
-  const isLast = page === numPages;
-  const prevPage = page - 1 || null;
-  const nextPage = page + 1 <= numPages ? page + 1 : null;
+  const isLast = numPages > 0 && page === numPages;
+  const prevPage = numPages === 0 ? null : page - 1 || null;
+  const nextPage = numPages > 0 && page + 1 <= numPages ? page + 1 : null;
   return {
     page,
     prevPage,

package/src/runMysql/runMysql.spec.ts

@@ -41,7 +41,33 @@ describe('runMysql', () => {
     expect(results).toBe(mockResults);
     expect(fields).toBe(mockFields);
   });
-  it('should also run with count', async () => {
+  it('should handle errors', async () => {
+    const client = {
+      query: vi.fn(
+        (
+          sql: string,
+          bindings: any[],
+          callback: (
+            err: Error | null,
+            rows: Array<Record<string, any>>,
+            fields: any[]
+          ) => void
+        ) => {
+          callback(new Error('Test Error'), [], []);
+        }
+      ),
+    };
+    const query = new SelectBuilder('SELECT * FROM users').where(
+      'dept',
+      'Marketing'
+    );
+    try {
+      await runMysql(client, query);
+    } catch (e) {
+      expect(e.message).toBe('Test Error');
+    }
+  });
+  it('should run with count', async () => {
     const mockResults1 = [
       { id: 1, name: 'John', dept: 'Marketing' },
       { id: 2, name: 'Jane', dept: 'Marketing' },
@@ -93,7 +119,53 @@ describe('runMysql', () => {
       isLast: true,
     });
   });
-  it('should invoke client.query with correct args (async)', async () => {
+  it('should run when count is 0', async () => {
+    const mockResults1 = [];
+    const mockFields1 = [{ name: 'id' }, { name: 'name' }, { name: 'dept' }];
+    const mockResults2 = [{ found_rows: 0 }];
+    const mockFields2 = [{ name: 'found_rows' }];
+    let callCount = 0;
+    const client = {
+      query: vi.fn(
+        (
+          sql: string,
+          bindings: any[],
+          callback: (
+            err: Error | null,
+            rows: Array<Record<string, any>>,
+            fields: any[]
+          ) => void
+        ) => {
+          if (++callCount === 1) {
+            callback(null, mockResults1, mockFields1);
+          }
+          callback(null, mockResults2, mockFields2);
+        }
+      ),
+    };
+    const query = new SelectBuilder('SELECT * FROM users')
+      .where('dept', 'Marketing')
+      .limit(2)
+      .page(5);
+    const { records, total, pagination } = await runMysqlWithCount(
+      client,
+      query
+    );
+    expect(callCount).toBe(1);
+    expect(records).toBe(mockResults1);
+    expect(total).toBe(0);
+    expect(pagination).toEqual({
+      page: null,
+      prevPage: null,
+      nextPage: null,
+      perPage: 2,
+      numPages: 0,
+      total: 0,
+      isFirst: false,
+      isLast: false,
+    });
+  });
+  it('should invoke client.query with correct args (promises)', async () => {
     const mockResults = [
       { id: 1, name: 'John', dept: 'Marketing' },
       { id: 2, name: 'Jane', dept: 'Marketing' },
@@ -117,7 +189,7 @@ describe('runMysql', () => {
     expect(results).toBe(mockResults);
     expect(fields).toBe(mockFields);
   });
-  it('should also run with count (async)', async () => {
+  it('should run with count (promises)', async () => {
     const mockResults1 = [
       { id: 1, name: 'John', dept: 'Marketing' },
       { id: 2, name: 'Jane', dept: 'Marketing' },
@@ -143,10 +215,7 @@ describe('runMysql', () => {
       client,
       query
     );
-    expect(client.query).toHaveBeenCalledWith(
-      'SELECT\n  *\nFROM users\nWHERE dept = ?\nOFFSET 8\nLIMIT 2',
-      ['Marketing']
-    );
+    expect(callCount).toBe(2);
     expect(records).toBe(mockResults1);
     expect(total).toBe(9);
     expect(pagination).toEqual({
@@ -161,4 +230,57 @@ describe('runMysql', () => {
     });
     expect(fields).toEqual(mockFields1);
   });
+  it('should run with count of zero (promises)', async () => {
+    const mockResults1 = [];
+    const mockFields1 = [{ name: 'id' }, { name: 'name' }, { name: 'dept' }];
+    const mockResults2 = [{ found_rows: 0 }];
+    const mockFields2 = [{ name: 'found_rows' }];
+    let callCount = 0;
+    const client = {
+      query: vi.fn((sql: string, bindings: any[]) => {
+        if (++callCount === 1) {
+          return Promise.resolve([mockResults1, mockFields1]);
+        }
+        return Promise.resolve([mockResults2, mockFields2]);
+      }),
+    };
+    const query = new SelectBuilder('SELECT * FROM users')
+      .where('dept', 'Marketing')
+      .limit(2)
+      .page(5);
+    const { records, total, pagination } = await runMysqlAsyncWithCount(
+      // @ts-expect-error
+      client,
+      query
+    );
+    expect(callCount).toBe(1);
+    expect(records).toBe(mockResults1);
+    expect(total).toBe(0);
+    expect(pagination).toEqual({
+      page: null,
+      prevPage: null,
+      nextPage: null,
+      perPage: 2,
+      numPages: 0,
+      total: 0,
+      isFirst: false,
+      isLast: false,
+    });
+  });
+  it('should handle errors (promises)', async () => {
+    const client = {
+      query: vi.fn((sql: string, bindings: any[]) => {
+        return Promise.reject('Test Test');
+      }),
+    };
+    const query = new SelectBuilder('SELECT * FROM users').where(
+      'dept',
+      'Marketing'
+    );
+    try {
+      await runMysqlAsync(client, query);
+    } catch (e) {
+      expect(e).toBe('Test Test');
+    }
+  });
 });

package/src/runMysql/runMysql.ts

@@ -37,6 +37,11 @@ function _queryToPromise(
   });
 }
 
+/**
+ * Run the given query with mysql and return the results
+ * @param mysqlClient  A client created with mysql.createConnection()  or mysql.createPool()
+ * @param query  The SelectBuilder query to run
+ */
 export async function runMysql(
   mysqlClient: MysqlClient,
   query: SelectBuilder
@@ -45,6 +50,13 @@ export async function runMysql(
   return _queryToPromise(mysqlClient, sql, bindings);
 }
 
+/**
+ * Run the given query with mysql and return the results, count, and pagination
+ * @param mysqlClient  A client created with mysql.createConnection()  or mysql.createPool()
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.countExpr  The SQL expression to use for the count (default "*")
+ */
 export async function runMysqlWithCount(
   mysqlClient: MysqlClient,
   query: SelectBuilder,

package/src/runPrisma/runPrisma.spec.ts

@@ -64,4 +64,36 @@ describe('runPrisma', () => {
       isLast: true,
     });
   });
+  it('should handle when recordset is empty', async () => {
+    const prisma = {
+      $queryRawUnsafe: vi.fn(() => []),
+    };
+    const query = new SelectBuilder('SELECT * FROM users')
+      .where('dept', 'Marketing')
+      .limit(2)
+      .page(5);
+    const { records, total, pagination } = await runPrismaWithCount(
+      // @ts-expect-error
+      prisma,
+      query
+    );
+    // @ts-expect-error
+    expect(prisma.$queryRawUnsafe.mock.calls[0][0]).toBe(
+      'SELECT\n  *\nFROM users\nWHERE dept = ?\nOFFSET 8\nLIMIT 2'
+    );
+    // @ts-expect-error
+    expect(prisma.$queryRawUnsafe.mock.calls[0][1]).toBe('Marketing');
+    expect(records).toStrictEqual([]);
+    expect(total).toBe(0);
+    expect(pagination).toEqual({
+      page: null,
+      prevPage: null,
+      nextPage: null,
+      perPage: 2,
+      numPages: 0,
+      total: 0,
+      isFirst: false,
+      isLast: false,
+    });
+  });
 });

package/src/runPrisma/runPrisma.ts

@@ -1,6 +1,7 @@
 import type SelectBuilder from '../SelectBuilder/SelectBuilder';
 import type { EngineStyle } from '../SelectBuilder/SelectBuilder';
 import getPagination from '../getPagination/getPagination';
+import { toSafeJsonValue } from '../toSafeJson/toSafeJson';
 
 interface PrismaClient {
   $queryRawUnsafe: (
@@ -9,29 +10,64 @@ interface PrismaClient {
   ) => Promise<Array<Record<string, any>>>;
 }
 
-export async function runPrisma(
+/**
+ * Run the given query with prisma and return the results
+ * @param prisma  The prisma client instance
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.engine  The engine style to use ("mssql" | "mysql" | "oracle" | "pg")
+ */
+export async function runPrisma<
+  T extends Array<Record<string, any>> = Array<Record<string, any>>,
+>(
   prisma: PrismaClient,
   query: SelectBuilder,
   { engine = undefined }: { engine?: EngineStyle } = {}
-): Promise<Array<Record<string, any>>> {
+): Promise<T> {
   const { sql, bindings } = query.compile({ engine });
-  return prisma.$queryRawUnsafe(sql, ...bindings);
+  return prisma.$queryRawUnsafe(sql, ...bindings) as unknown as Promise<T>;
 }
 
-export async function runPrismaWithCount(
+/**
+ * Run the given query with prisma and return the results, count, and pagination
+ * @param prisma  The prisma client instance
+ * @param query  The SelectBuilder query to run
+ * @param options
+ * @param options.engine  The engine style to use ("mssql" | "mysql" | "oracle" | "pg")
+ * @param options.countExpr  The SQL expression to use for the count (default "*")
+ */
+export async function runPrismaWithCount<
+  T extends Array<Record<string, any>> = Array<Record<string, any>>,
+>(
   prisma: PrismaClient,
   query: SelectBuilder,
   {
     engine = undefined,
     countExpr = '*',
   }: { engine?: EngineStyle; countExpr?: string } = {}
-) {
+): Promise<{
+  records: T;
+  total: number;
+  pagination: {
+    page: number;
+    prevPage: number;
+    nextPage: number;
+    perPage: number;
+    numPages: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+  };
+}> {
   const { sql, bindings } = query.compile({ engine });
-  const records = await prisma.$queryRawUnsafe(sql, ...bindings);
+  const records = (await prisma.$queryRawUnsafe(
+    sql,
+    ...bindings
+  )) as unknown as T;
   if (records.length > 0) {
     const { sql, bindings } = query.compileCount({ engine, countExpr });
     const result = await prisma.$queryRawUnsafe(sql, ...bindings);
-    const total = result[0].found_rows;
+    const total = toSafeJsonValue(result[0].found_rows);
     return { records, total, pagination: getPagination(query, total) };
   } else {
     return { records, total: 0, pagination: getPagination(query, 0) };

package/src/substrCount/substrCount.ts

@@ -1,9 +1,14 @@
+/**
+ * Count the number of times a substring appears in a string
+ * @param haystack
+ * @param needle
+ */
 export default function substrCount(haystack: string, needle: string) {
-	let count = 0;
-	let pos = haystack.indexOf(needle);
-	while (pos !== -1) {
-		count += 1;
-		pos = haystack.indexOf(needle, pos + 1);
-	}
-	return count;
+  let count = 0;
+  let pos = haystack.indexOf(needle);
+  while (pos !== -1) {
+    count += 1;
+    pos = haystack.indexOf(needle, pos + 1);
+  }
+  return count;
 }

package/src/toSafeJson/toSafeJson.spec.ts

@@ -0,0 +1,28 @@
+import { toSafeJsonRecords, toSafeJsonString } from './toSafeJson';
+
+describe('toSafeJsonString()', () => {
+  it('should convert small BigInt to Number', () => {
+    const records = [{ found_rows: 30n }];
+    const json = toSafeJsonString(records);
+    expect(json).toBe('[{"found_rows":30}]');
+  });
+  it('should convert large BigInt to String', () => {
+    const myBigInt = BigInt(String(Number.MAX_SAFE_INTEGER) + '0');
+    const records = [{ found_rows: myBigInt }];
+    const json = toSafeJsonString(records);
+    expect(json).toBe(`[{"found_rows":"${myBigInt.toString()}"}]`);
+  });
+});
+describe('jsonSafePrisma()', () => {
+  it('should convert small BigInt to Number', () => {
+    const records = [{ found_rows: 30n }];
+    const json = toSafeJsonRecords(records);
+    expect(json).toStrictEqual([{ found_rows: 30 }]);
+  });
+  it('should convert large BigInt to String', () => {
+    const myBigInt = BigInt(String(Number.MAX_SAFE_INTEGER) + '0');
+    const records = [{ found_rows: myBigInt }];
+    const json = toSafeJsonRecords(records);
+    expect(json).toStrictEqual([{ found_rows: myBigInt.toString() }]);
+  });
+});

package/src/toSafeJson/toSafeJson.ts

@@ -0,0 +1,56 @@
+type SafeValue<T> = T extends BigInt ? number | string : T;
+type SafeRecord<T> = Record<string, SafeValue<T>>;
+type SafeRecords<T> = Array<SafeRecord<T>>;
+
+/**
+ * Convert a value to a value that can be safely serialized to JSON
+ * @param value
+ */
+export function toSafeJsonValue<T>(value: T): SafeValue<T> {
+  if (typeof value === 'bigint') {
+    const asNumber = Number(value);
+    // Use double equals instead of triple equals below to check if the BigInt
+    //   is too big to fit in a JS Number.
+    //   If so, then return it as a string, otherwise return it as a Number
+    // @ts-expect-error
+    return value == asNumber ? asNumber : value.toString();
+  }
+  return value as SafeValue<T>;
+}
+
+/**
+ * Convert a record to one that can be safely serialized to JSON
+ * @param record
+ */
+export function toSafeJsonRecord<T extends Record<string, any>>(
+  record: T
+): SafeRecord<T> {
+  const newRecord: SafeValue<T> = {} as any;
+  for (const key in record) {
+    /* v8 ignore next 3 */
+    if (!Object.prototype.hasOwnProperty.call(record, key)) {
+      continue;
+    }
+    newRecord[key] = toSafeJsonValue(record[key]);
+  }
+  return newRecord;
+}
+
+/**
+ * Convert a recordset to one that can be safely serialized to JSON
+ * @param records
+ */
+export function toSafeJsonRecords<T extends Record<string, any>>(
+  records: T[]
+): SafeRecords<T> {
+  return records.map(toSafeJsonRecord);
+}
+
+/**
+ * JSON stringify a value or data structure, ensuring first that all values are
+ *   safe to serialize
+ * @param records
+ */
+export function toSafeJsonString(records: Array<Record<string, any>>) {
+  return JSON.stringify(records, (_, value: any) => toSafeJsonValue(value));
+}

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.spec.ts'],
+    coverage: {
+      exclude: ['index.ts'],
+    },
+    globals: true,
+  },
+});

package/vitest.config.js

@@ -1,8 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-	test: {
-		include: ['**/*.spec.ts'],
-		globals: true,
-	},
-});