sql-love 1.1.1 → 1.1.4

package/dist/index.mjs

@@ -1,15 +1,31 @@
 // src/Parser/Parser.ts
-class Parser {
+var Parser = class {
   query;
+  /**
+   * Create a new instance
+   * @param query  A Select object on which to build parsed conditions
+   */
   constructor(query) {
     this.query = query;
   }
+  /**
+   * Strip single-line and multi-line comment blocks
+   * @param sql  The SQL string
+   * @return  The SQL string without comments
+   * @private
+   */
   _stripComments(sql) {
     sql = sql.replace(/\/\*[\s\S]*?\*\//g, "");
     sql = sql.replace(/--([\r\n]|\s+[^\r\n]+[\r\n])/g, "");
     sql = sql.replace(/#[^\r\n]+[\r\n]/g, "");
     return sql;
   }
+  /**
+   * Before splitting into SQL clauses, extract some regex-able subQueries
+   * @param sql  The unparsed sql string
+   * @return  An array with new sql and subQueries
+   * @private
+   */
   _extractSubQueries(sql) {
     const subQueries = {};
     let i = 0;
@@ -23,6 +39,11 @@ class Parser {
     sql = sql.replace(/\bIN\s*\(\s*SELECT\s.+?\)/, extractor);
     return { sql, subQueries };
   }
+  /**
+   * Inject column subQueries back into this object
+   * @param subQueries  The lookup of extracted subQueries
+   * @private
+   */
   _injectSubQueries(subQueries) {
     const replacer = ($0) => {
       return subQueries[$0] || $0;
@@ -35,10 +56,21 @@ class Parser {
     this.query._wheres = this.query._wheres.map(mapper);
     this.query._havings = this.query._havings.map(mapper);
   }
+  /**
+   * Split SQL into clauses (used by parse())
+   * @param sql  The SQL to split
+   * @return
+   * @private
+   */
   _split(sql) {
     const splitter = /(?:^|\s)(SELECT|FROM|(?:INNER|LEFT\s+OUTER|RIGHT\s+OUTER|LEFT|RIGHT|CROSS|FULL|FULL\s+OUTER)\s+JOIN|WHERE|GROUP\s+BY|HAVING|ORDER\s+BY|LIMIT|OFFSET|FETCH\s+NEXT)\b/i;
     return sql.split(splitter);
   }
+  /**
+   * Get a QuickSelect object representing the given SQL SELECT statement
+   * @param  rawSql  The raw SQL for the SELECT statement
+   * @return True if the SQL was parsed successfully
+   */
   parse(rawSql) {
     const stripped = this._stripComments(rawSql);
     const { sql, subQueries } = this._extractSubQueries(stripped);
@@ -49,11 +81,16 @@ class Parser {
       const keyword = rawKeyword.toUpperCase().replace(/\s+/g, "_");
       const clause = expressions[i++].trim();
       const handler = `_handle${keyword}`;
-      this[handler](clause);
+      this[handler]?.(clause);
     }
     this._injectSubQueries(subQueries);
     return true;
   }
+  /**
+   * Handle SQL_CALC_FOUND_ROWS and column names
+   * @param clause  The clause after the SELECT
+   * @private
+   */
   _handleSELECT(clause) {
     let columns = clause.split(/s*,s*/);
     let buffer = "";
@@ -81,34 +118,84 @@ class Parser {
       }
     });
   }
+  /**
+   * Handle table names
+   * @param clause  The clause after the FROM
+   * @private
+   */
   _handleFROM(clause) {
     const tables = clause.split(/\s*,\s*/);
     tables.forEach((table) => this.query.table(table));
   }
+  /**
+   * Handle INNER JOIN statements
+   * @param clause  The clause after the INNER JOIN
+   * @private
+   */
   _handleINNER_JOIN(clause) {
     this.query.innerJoin(clause);
   }
+  /**
+   * Handle LEFT JOIN statements
+   * @param clause  The clause after the LEFT JOIN
+   * @private
+   */
   _handleLEFT_JOIN(clause) {
     this.query.leftJoin(clause);
   }
+  /**
+   * Handle LEFT OUTER JOIN statements
+   * @param clause  The clause after the LEFT OUTER JOIN
+   * @private
+   */
   _handleLEFT_OUTER_JOIN(clause) {
     this.query.leftOuterJoin(clause);
   }
+  /**
+   * Handle RIGHT JOIN statements
+   * @param clause  The clause after the RIGHT JOIN
+   * @private
+   */
   _handleRIGHT_JOIN(clause) {
     this.query.rightJoin(clause);
   }
+  /**
+   * Handle RIGHT OUTER JOIN statements
+   * @param clause  The clause after the RIGHT OUTER JOIN
+   * @private
+   */
   _handleRIGHT_OUTER_JOIN(clause) {
     this.query.rightOuterJoin(clause);
   }
+  /**
+   * Handle CROSS JOIN statements
+   * @param clause  The clause after the CROSS JOIN
+   * @private
+   */
   _handleCROSS_JOIN(clause) {
     this.query.crossJoin(clause);
   }
+  /**
+   * Handle FULL JOIN statements
+   * @param clause  The clause after the FULL JOIN
+   * @private
+   */
   _handleFULL_JOIN(clause) {
     this.query.fullJoin(clause);
   }
+  /**
+   * Handle FULL OUTER JOIN statements
+   * @param clause  The clause after the FULL OUTER JOIN
+   * @private
+   */
   _handleFULL_OUTER_JOIN(clause) {
     this.query.fullOuterJoin(clause);
   }
+  /**
+   * Handle WHERE conditions
+   * @param clause  All the conditions after WHERE
+   * @private
+   */
   _handleWHERE(clause) {
     if (/^(1|'1'|true)$/i.test(clause)) {
       this.query._wheres.push(clause);
@@ -116,9 +203,20 @@ class Parser {
       this._handleConditions("where", clause);
     }
   }
+  /**
+   * Handle HAVING statements
+   * @param clause  All the conditions after HAVING
+   * @private
+   */
   _handleHAVING(clause) {
     this._handleConditions("having", clause);
   }
+  /**
+   * Build a conditions list
+   * @param type  Either where or having
+   * @param clause  The expressions following the type keyword
+   * @private
+   */
   _handleConditions(type, clause) {
     const andGroups = clause.split(/\bAND\b/i);
     andGroups.forEach((andGroup) => {
@@ -132,14 +230,29 @@ class Parser {
       }
     });
   }
+  /**
+   * Handle GROUP BY statements
+   * @param clause  The clauses after the GROUP BY
+   * @private
+   */
   _handleGROUP_BY(clause) {
     const columns = clause.split(/\s*,\s*/);
     columns.forEach((column) => this.query.groupBy(column));
   }
+  /**
+   * Handle ORDER BY statements
+   * @param clause  The clause after the ORDER BY
+   * @private
+   */
   _handleORDER_BY(clause) {
     const columns = clause.split(/\s*,\s*/);
     columns.forEach((column) => this.query.orderBy(column));
   }
+  /**
+   * Handle LIMIT statements including "LIMIT #" and "LIMIT #, #"
+   * @param clause  The clause after the LIMIT
+   * @private
+   */
   _handleLIMIT(clause) {
     const offsetLimit = clause.match(/^(\d+|\?|:\w+)\s*,\s*(\d+|\?|:\w+)$/);
     if (offsetLimit) {
@@ -150,15 +263,26 @@ class Parser {
       this.query.limit(clause);
     }
   }
+  /**
+   * Handle OFFSET statements
+   * @param clause  The number after the OFFSET
+   * @private
+   */
   _handleOFFSET(clause) {
     clause = clause.replace(/^(\d+) ROWS$/i, "$1");
     this.query.offset(clause);
   }
+  /**
+   * Handle OFFSET statements
+   * @param clause  The number after the OFFSET
+   * @private
+   */
   _handleFETCH_NEXT(clause) {
     clause = clause.replace(/^(\d+) ROWS ONLY$/i, "$1");
     this.query.limit(clause);
   }
-}
+};
+
 // src/substrCount/substrCount.ts
 function substrCount(haystack, needle) {
   let count = 0;
@@ -171,23 +295,76 @@ function substrCount(haystack, needle) {
 }
 
 // src/SelectBuilder/SelectBuilder.ts
-var isNullish = (v) => v === undefined || v === null || v === false || isNaN(v);
+var isNullish = (v) => v === void 0 || v === null || v === false || Object.is(NaN, v);
 var defaultEngine = "mysql";
-
-class SelectBuilder {
+var SelectBuilder = class _SelectBuilder {
+  /**
+   * The list of values to bind to the query
+   * @private
+   */
   _bindings = [];
+  /**
+   * The list of strings to come immediately after "SELECT"
+   * and before column names
+   * @private
+   */
   _options = [];
+  /**
+   * The list of column names to select
+   * @private
+   */
   _tables = [];
+  /**
+   * The list of tables in the FROM clause
+   * @private
+   */
   _columns = [];
+  /**
+   * The list of JOIN strings to add
+   * @private
+   */
   _joins = [];
+  /**
+   * The list of WHERE clauses to join with AND
+   * @private
+   */
   _wheres = [];
+  /**
+   * The list of GROUP BY clauses to join with commas
+   * @private
+   */
   _groupBys = [];
+  /**
+   * The list of HAVING clauses to join with AND
+   * @private
+   */
   _havings = [];
+  /**
+   * The list of ORDER BY clauses to join with commas
+   * @private
+   */
   _orderBys = [];
+  /**
+   * The LIMIT to use
+   * @private
+   */
   _limit;
+  /**
+   * The OFFSET to use
+   * @private
+   */
   _offset;
+  /**
+   * The page used to construct an OFFSET based on the LIMIT
+   * @private
+   */
   _page;
-  constructor(sql = null, bindings = null) {
+  /**
+   * Select constructor
+   * @param [sql]  A base SQL query to parse
+   * @param [bindings]  Placeholders to bind to the query
+   */
+  constructor(sql, bindings = {}) {
     if (sql) {
       if (bindings) {
         const keys = Object.keys(bindings);
@@ -200,58 +377,58 @@ 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;
+    return _SelectBuilder;
   }
+  /**
+   * Get the SQL as a pretty-printed string alongside an array of bindings
+   * @param engine  The database engine style (mssql, mysql, oracle, pg)
+   * @return The SQL query as a string
+   */
   compile({
     engine = defaultEngine,
     bindingIndex = 1
   } = {}) {
     const lines = [
       "SELECT",
-      this._options.length ? `  ${this._options.join(`
-  `)}` : null,
-      this._columns.length ? `  ${this._columns.join(`,
-  `)}` : `  *
-`,
+      this._options.length ? `  ${this._options.join("\n  ")}` : null,
+      this._columns.length ? `  ${this._columns.join(",\n  ")}` : "  *\n",
       `FROM ${this._tables.join(", ")}`,
-      this._joins.length ? this._joins.join(`
-`) : null,
-      this._wheres.length ? `WHERE ${this._wheres.join(`
-  AND `)}` : null,
-      this._groupBys.length ? `GROUP BY ${this._groupBys.join(`,
-  `)}` : null,
-      this._havings.length ? `HAVING ${this._havings.join(`
-  AND `)}` : null,
-      this._orderBys.length ? `ORDER BY ${this._orderBys.join(`,
-  `)}` : null
+      this._joins.length ? this._joins.join("\n") : null,
+      this._wheres.length ? `WHERE ${this._wheres.join("\n  AND ")}` : null,
+      this._groupBys.length ? `GROUP BY ${this._groupBys.join(",\n  ")}` : null,
+      this._havings.length ? `HAVING ${this._havings.join("\n  AND ")}` : null,
+      this._orderBys.length ? `ORDER BY ${this._orderBys.join(",\n  ")}` : null
     ];
-    if (this._page > 0) {
+    if (this._page && this._page > 0 && this._limit) {
       const offset = (this._page - 1) * this._limit;
-      lines.push(this._compileOFFSET(engine, offset));
-      lines.push(this._compileLIMIT(engine, this._limit));
+      lines.push(this._compileOFFSET(engine, offset) ?? "");
+      lines.push(this._compileLIMIT(engine, this._limit) ?? "");
     } else {
       if (this._offset) {
-        lines.push(this._compileOFFSET(engine, this._offset));
+        lines.push(this._compileOFFSET(engine, this._offset) ?? "");
       }
       if (this._limit) {
-        lines.push(this._compileLIMIT(engine, this._limit));
+        lines.push(this._compileLIMIT(engine, this._limit) ?? "");
       }
     }
-    const pretty = lines.filter(Boolean).join(`
-`).trim();
+    const pretty = lines.filter(Boolean).join("\n").trim();
     let replacer;
     const bindings = [];
     if (engine === "pg") {
       let idx = bindingIndex;
       replacer = (_, $1) => {
-        bindings.push(this._bindings[$1]);
+        bindings.push(this._bindings[Number($1)]);
         return "$" + idx++;
       };
     } else {
       replacer = (_, $1) => {
-        bindings.push(this._bindings[$1]);
+        bindings.push(this._bindings[Number($1)]);
         return "?";
       };
     }
@@ -272,6 +449,11 @@ class SelectBuilder {
       return `OFFSET ${offset} ROWS`;
     }
   }
+  /**
+   * Get SQL needed to return the found rows of this query
+   * @param engineStyle  The database engine style (mssql, mysql, oracle, pg)
+   * @param countExpr  The expression to use inside the COUNT()
+   */
   compileCount({
     countExpr = "*",
     engine = defaultEngine,
@@ -279,11 +461,10 @@ class SelectBuilder {
   } = {}) {
     const query = this.getFoundRowsQuery(countExpr);
     const { sql, bindings } = query.compile({ engine, bindingIndex });
-    if (this._havings.length === 0) {
+    if (this._havings.length === 0 && this._groupBys.length === 0) {
       return { sql, bindings };
     } else {
-      const subquerySql = sql.replace(/\n/g, `
-	`);
+      const subquerySql = sql.replace(/\n/g, "\n	");
       return {
         sql: `SELECT COUNT(*) AS found_rows
 FROM (
@@ -293,6 +474,11 @@ ${subquerySql}
       };
     }
   }
+  /**
+   * 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
@@ -309,7 +495,12 @@ UNION
       bindings: [...first.bindings, ...second.bindings]
     };
   }
-  reset(fieldOrFields = null) {
+  /**
+   * @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
+   * @return This object
+   */
+  reset(fieldOrFields) {
     if (Array.isArray(fieldOrFields)) {
       fieldOrFields.forEach((name) => this.reset(name));
       return this;
@@ -339,15 +530,18 @@ UNION
       this._groupBys = [];
       this._havings = [];
       this._orderBys = [];
-      this._limit = null;
-      this._offset = null;
-      this._page = null;
+      this._limit = void 0;
+      this._offset = void 0;
+      this._page = void 0;
       this._bindings = [];
     }
     return this;
   }
+  /**
+   * Clone this builder object
+   */
   getClone() {
-    const copy = new SelectBuilder;
+    const copy = new _SelectBuilder();
     copy._options = [...this._options];
     copy._columns = [...this._columns];
     copy._tables = [...this._tables];
@@ -362,6 +556,10 @@ UNION
     copy._bindings = [...this._bindings];
     return copy;
   }
+  /**
+   * Build a version of this query that simply returns COUNT(*)
+   * @param [countExpr="*"]  Use to specify `DISTINCT colname` if needed
+   */
   getFoundRowsQuery(countExpr = "*") {
     if (this._havings.length === 0) {
       const clone = this.getClone();
@@ -369,46 +567,86 @@ UNION
       clone._options = [];
       clone._groupBys = [];
       clone._orderBys = [];
-      clone._limit = null;
-      clone._offset = null;
-      clone._page = null;
+      clone._limit = void 0;
+      clone._offset = void 0;
+      clone._page = void 0;
       return clone;
     } else {
       const subquery = this.getClone();
-      subquery._limit = null;
-      subquery._offset = null;
-      subquery._page = null;
+      subquery._limit = void 0;
+      subquery._offset = void 0;
+      subquery._page = void 0;
       return subquery;
     }
   }
+  /**
+   * Add an array of column names to fetch
+   * @param columnNames  The names of columns
+   */
   select(columnNames) {
     this._columns = this._columns.concat(columnNames);
     return this;
   }
+  /**
+   * Add an array of column names to fetch
+   * @param columnNames  The names of columns
+   */
   columns(columnNames) {
     this._columns = this._columns.concat(columnNames);
     return this;
   }
+  /**
+   * Add a column name to fetch
+   * @param columnName  The name of the column
+   */
   column(columnName) {
     this._columns.push(columnName);
     return this;
   }
+  /**
+   * Add an option expression such as "TOP 10" or "SQL_CALC_FOUND_ROWS"
+   * @param optionExpression  Expression to go after "SELECT" and before column list
+   */
   option(optionExpression) {
     this._options.push(optionExpression);
     return this;
   }
+  /**
+   * Add a table to the "FROM" clause (same as .from())
+   * @param {String} tableName  The name of the table to query
+   * @return {Select}
+   */
   table(tableName) {
     this._tables.push(tableName);
     return this;
   }
+  /**
+   * Add multiple table to the "FROM" clause
+   * @param {Array} tableNames  The names of the tables to query
+   * @return {Select}
+   */
   tables(tableNames) {
     this._tables.push(...tableNames);
     return this;
   }
+  /**
+   * Add a table to the "FROM" clause (same as .table())
+   * @param {String} tableName  The name of the table to query
+   * @return {Select}
+   */
   from(tableName) {
     this._tables.push(tableName);
     return this;
   }
+  /**
+   * Add the given join type expression
+   * @param joinType  The type of join (e.g. "INNER JOIN", "LEFT JOIN", etc.)
+   * @param expression  The expression following the INNER JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.join('posts p ON p.id = c.post_id');
+   *   query.join('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   _addJoin(joinType, expression, bindings = []) {
     if (bindings.length > 0) {
       expression = expression.replace(/\?/g, () => {
@@ -418,42 +656,118 @@ UNION
     }
     this._joins.push(`${joinType} ${expression}`);
   }
+  /**
+   * Add a JOIN expression
+   * @param expression  The expression following the INNER JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.join('posts p ON p.id = c.post_id');
+   *   query.join('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   join(expression, bindings = []) {
     this._addJoin("JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Add a LEFT JOIN expression
+   * @param expression  The expression following the LEFT JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.leftJoin('posts p ON p.id = c.post_id');
+   *   query.leftJoin('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   leftJoin(expression, bindings = []) {
     this._addJoin("LEFT JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Add a FULL JOIN expression
+   * @param expression  The expression following the FULL JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.fullJoin('posts p ON p.id = c.post_id');
+   *   query.fullJoin('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   fullJoin(expression, bindings = []) {
     this._addJoin("FULL JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Add a RIGHT JOIN expression
+   * @param expression  The expression following the RIGHT JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.rightJoin('posts p ON p.id = c.post_id');
+   *   query.rightJoin('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   rightJoin(expression, bindings = []) {
     this._addJoin("RIGHT JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Add a CROSS JOIN expression
+   * @param expression  The expression following the CROSS JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.crossJoin('posts p ON p.id = c.post_id');
+   *   query.crossJoin('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   crossJoin(expression, bindings = []) {
     this._addJoin("CROSS JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Add an INNER JOIN expression (same as ->join())
+   * @param expression  The expression following the INNER JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.innerJoin('posts p ON p.id = c.post_id');
+   *   query.innerJoin('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   innerJoin(expression, bindings = []) {
     this._addJoin("INNER JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Add a LEFT OUTER JOIN expression
+   * @param expression  The expression following the LEFT OUTER JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.leftOuterJoin('posts p ON p.id = c.post_id');
+   *   query.leftOuterJoin('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   leftOuterJoin(expression, bindings = []) {
     this._addJoin("LEFT OUTER JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Add a FULL OUTER JOIN expression
+   * @param expression  The expression following the FULL OUTER JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.fullOuterJoin('posts p ON p.id = c.post_id');
+   *   query.fullOuterJoin('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   fullOuterJoin(expression, bindings = []) {
     this._addJoin("FULL OUTER JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Add a RIGHT OUTER JOIN expression
+   * @param expression  The expression following the RIGHT OUTER JOIN keyword
+   * @param bindings  A list of values to bind to ? placeholders in the expression
+   * @example
+   *   query.rightOuterJoin('posts p ON p.id = c.post_id');
+   *   query.rightOuterJoin('posts p ON p.id = c.post_id AND p.deleted_at < ?', [myDate]);
+   */
   rightOuterJoin(expression, bindings = []) {
     this._addJoin("RIGHT OUTER JOIN", expression, bindings);
     return this;
   }
+  /**
+   * Remove a join condition with the specified table
+   * @param table  The name of the table or tables in the first part of the join statement
+   */
   unjoin(table) {
     if (Array.isArray(table)) {
       table.forEach((t) => this.unjoin(t));
@@ -465,6 +779,34 @@ UNION
     });
     return this;
   }
+  /**
+   * Utility function to add conditions for a clause (WHERE, HAVING)
+   * @param  collection  The collection to add the clauses to (e.g. this._wheres or this._havings)
+   * @param  criteria  Criteria adhering to WhereCriteria type
+   * @example  The following are equivalent
+   *   this._conditions(this._wheres, ['deleted_at IS NULL']);
+   *   this._conditions(this._wheres, ['deleted_at', null]);
+   *   this._conditions(this._wheres, ['deleted_at', '=', null]);
+   * @example  More examples
+   *   this._conditions(this._wheres, ['fname', 'LIKE', 'joe']); // `fname` LIKE 'joe'
+   *   this._conditions(this._wheres, ['fname', 'LIKE ?', 'joe']); // `fname` LIKE 'joe'
+   *   this._conditions(this._wheres, ['fname LIKE %?%', 'joe']); // `fname` LIKE '%joe%'
+   *   this._conditions(this._wheres, ['fname LIKE ?%', 'joe']); // `fname` LIKE 'joe%'
+   *   this._conditions(this._wheres, ['fname', 'LIKE ?%', 'joe']); // `fname` LIKE 'joe%'
+   *   this._conditions(this._wheres, ['price >', 10]); // `price` > 10
+   *   this._conditions(this._wheres, ['price', '>', 10]); // `price` > 10
+   *   this._conditions(this._wheres, ['price =', 10]); // `price` = 10
+   *   this._conditions(this._wheres, ['price !=', 10]); // `price` != 10
+   *   this._conditions(this._wheres, ['price', 10]); // `price` = 10
+   *   this._conditions(this._wheres, ['price', '=', 10]); // `price` = 10
+   *   this._conditions(this._wheres, ['price', '!=', 10]); // `price` != 10
+   *   this._conditions(this._wheres, ['price', 'BETWEEN', [10,20]]); // `price` BETWEEN 10 AND 20
+   *   this._conditions(this._wheres, ['price', 'NOT BETWEEN', [10,20]]); // `price` NOT BETWEEN 10 AND 20
+   *   this._conditions(this._wheres, ['price', [10,20]]); // `price` IN(10,20)
+   *   this._conditions(this._wheres, ['price', '=', [10,20]]); // `price` IN(10,20)
+   *   this._conditions(this._wheres, ['price', 'IN', [10,20]]); // `price` IN(10,20)
+   *   this._conditions(this._wheres, ['price', 'NOT IN', [10,20]]); // `price` NOT IN(10,20)
+   */
   _conditions(collection, criteria) {
     const numArgs = criteria.length;
     let [column, operator, value] = criteria;
@@ -477,7 +819,7 @@ UNION
     if (numArgs === 1) {
       collection.push(column);
       return this;
-    } else if (numArgs === 2 && Array.isArray(operator) && operator.length > 0 && substrCount(column, "?") === operator.length) {
+    } else if (numArgs === 2 && Array.isArray(operator) && substrCount(column, "?") === operator.length) {
       const values = operator;
       const sql = column.replace(/\?/g, () => {
         this._bindings.push(values.shift());
@@ -488,18 +830,22 @@ UNION
     } else if (numArgs === 2) {
       value = operator;
       const parts = column.split(" ");
-      column = parts.shift();
+      column = parts.shift() ?? "";
       operator = parts.join(" ");
     }
     if (typeof operator !== "string" || operator === "") {
       operator = "=";
     }
     operator = operator.toLocaleUpperCase();
-    const likeMatch = operator.match(/^(LIKE|NOT LIKE|ILIKE|NOT ILIKE)(?: (\?|\?%|%\?|%\?%))?$/i);
+    const likeMatch = operator.match(
+      /^(LIKE|NOT LIKE|ILIKE|NOT ILIKE)(?: (\?|\?%|%\?|%\?%))?$/i
+    );
     if (operator === "NOT BETWEEN" || operator === "BETWEEN") {
       const one = this._bindings.length;
       const two = this._bindings.length + 1;
-      collection.push(`${column} ${operator} __BOUND_${one}__ AND __BOUND_${two}__`);
+      collection.push(
+        `${column} ${operator} __BOUND_${one}__ AND __BOUND_${two}__`
+      );
       this._bindings.push(value[0], value[1]);
     } else if (likeMatch) {
       const like = likeMatch[1].toUpperCase();
@@ -517,32 +863,52 @@ UNION
         this._bindings.push(infix.replace("?", value || ""));
       }
     } else if (value === null) {
-      collection.push(operator === "=" ? `${column} IS NULL` : `${column} IS NOT NULL`);
+      collection.push(
+        operator === "=" ? `${column} IS NULL` : `${column} IS NOT NULL`
+      );
     } else if (Array.isArray(value)) {
       const inVals = [];
-      for (let i = 0;i < value.length; i++) {
+      for (let i = 0; i < value.length; i++) {
         inVals.push(`__BOUND_${this._bindings.length}__`);
         this._bindings.push(value[i]);
       }
       const joined = inVals.join(", ");
-      collection.push(operator === "=" || operator === "IN" ? `${column} IN(${joined})` : `${column} NOT IN(${joined})`);
+      collection.push(
+        operator === "=" || operator === "IN" ? `${column} IN(${joined})` : `${column} NOT IN(${joined})`
+      );
     } else if (operator === "IN" || operator === "NOT IN") {
-      collection.push(`${column} ${operator}(__BOUND_${this._bindings.length}__)`);
+      collection.push(
+        `${column} ${operator}(__BOUND_${this._bindings.length}__)`
+      );
       this._bindings.push(value);
     } else {
-      collection.push(`${column} ${operator} __BOUND_${this._bindings.length}__`);
+      collection.push(
+        `${column} ${operator} __BOUND_${this._bindings.length}__`
+      );
       this._bindings.push(value);
     }
     return this;
   }
+  /**
+   * Add a group by column or expression
+   * @param column  The name of a column (or expression) to group by
+   */
   groupBy(column) {
     this._groupBys.push(column);
     return this;
   }
+  /**
+   * Add WHERE clauses to conditions (See _conditions for usage)
+   */
   where(...args) {
     this._conditions(this._wheres, args);
     return this;
   }
+  /**
+   * Add a WHERE clause with a BETWEEN condition
+   * @param column  The column name
+   * @param twoValueArray  The two values to be between. If the first is null, it will use >= instead. If the second is null, it will use <= instead. If both are null, no criteria will be added
+   */
   whereBetween(column, twoValueArray) {
     if (!isNullish(twoValueArray[0]) && !isNullish(twoValueArray[1])) {
       this.where(column, "BETWEEN", twoValueArray);
@@ -550,9 +916,14 @@ UNION
       this.where(column, ">=", twoValueArray[0]);
     } else if (isNullish(twoValueArray[0]) && !isNullish(twoValueArray[1])) {
       this.where(column, "<=", twoValueArray[1]);
-    } else {}
+    } else {
+    }
     return this;
   }
+  /**
+   * Add a series of WHERE clauses joined by OR (See _conditions for usage)
+   * @param conditions
+   */
   _orConditions(conditions) {
     const items = [];
     if (Array.isArray(conditions)) {
@@ -577,21 +948,44 @@ UNION
       return joined;
     }
   }
+  /**
+   * 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) {
     const joined = this._orConditions(conditions);
     this.where(`(${joined})`);
     return 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) {
     const joined = this._orConditions(conditions);
     this.having(`(${joined})`);
     return this;
   }
+  /**
+   * Add a HAVING condition (See _conditions for usage)
+   */
   having(...args) {
     this._conditions(this._havings, args);
     return this;
   }
-  orderBy(column, direction = null) {
+  /**
+   * Add a column or expression to order by
+   * @param column  The column name or expression to sort by. Include DESC or prefix with - to sort descending
+   * @param [direction]  The direction to sort by (ASC or DESC)
+   * @example
+   *   query.orderBy('modified_at'); // ORDER BY modified_at
+   *   query.orderBy('-modified_at'); // ORDER BY modified_at DESC
+   *   query.orderBy('COUNT(*)'); // ORDER BY COUNT(*)
+   *   query.orderBy('COUNT(*) DESC'); // ORDER BY COUNT(*) DESC
+   *   query.orderBy('modified_at DESC NULLS LAST'); // ORDER BY modified_at DESC NULLS LAST
+   *   query.orderBy('modified_at USING >'); // ORDER BY modified_at USING >
+   */
+  orderBy(column, direction) {
     if (direction) {
       this._orderBys.push(`${column} ${direction}`);
     } else {
@@ -600,8 +994,27 @@ UNION
     }
     return this;
   }
+  /**
+   * Sort by the given field, with a map of allowed fields to column expressions.
+   * Only field names present in mapNames are allowed; anything else emits a
+   * console.warn and adds no ORDER BY clause. This prevents SQL injection when
+   * fieldName comes from user input.
+   * @param fieldName  The field name such as 'created' or '-created' for descending
+   * @param mapNames  Allowed field names mapped to column expressions
+   * @param [modifier]  Additional clause to append such as 'NULLS LAST' or 'COLLATE "en_US"'
+   * @example
+   *   query.sortField('-created', {'created': 'created_at'}); // ORDER BY created_at DESC
+   *   query.sortField('-foo', {'created': 'created_at'}); // console.warn; no ORDER BY added
+   *   query.sortField('-created', {
+   *     'created': 'created_at NULLS LAST',
+   *     '-created': 'created_at DESC NULLS LAST'
+   *   }); // ORDER BY created_at DESC NULLS LAST
+   *   query.sortField('-name', {
+   *     'name': 'name COLLATE "jp_JP"'
+   *   }); // ORDER BY name COLLATE "jp_JP" DESC
+   */
   sortField(fieldName, mapNames = {}, modifier = "") {
-    if (!fieldName) {
+    if (typeof fieldName !== "string" || fieldName === "") {
       return this;
     }
     let direction = "ASC";
@@ -614,19 +1027,39 @@ UNION
       direction = "DESC";
       fieldName = fieldName.slice(1);
     }
-    const column = mapNames[fieldName] || fieldName;
+    if (!Object.prototype.hasOwnProperty.call(mapNames, fieldName)) {
+      console.warn(
+        `SelectBuilder: sortField() ignoring unknown field "${fieldName.slice(0, 100)}"`
+      );
+      return this;
+    }
+    const column = mapNames[fieldName];
     if (modifier) {
       direction += ` ${modifier}`;
     }
     this.orderBy(column, direction);
     return this;
   }
+  /**
+   * Check to see if the given string is 0 or all digits not starting with 0
+   * @param string  The input string
+   * @private
+   */
   _isEntirelyDigits(string) {
     return /^(0|[1-9]\d*)$/.test(string);
   }
+  /**
+   * Check to see if the given string is all digits
+   * @param string  The input string
+   * @private
+   */
   _isEntirelyDigitsNoZeros(string) {
     return /^[1-9]\d*$/.test(string);
   }
+  /**
+   * Limit results to the given number
+   * @param max  The number to limit by (placeholder string or integer greater than 0)
+   */
   limit(max) {
     if (typeof max === "string") {
       max = max.trim();
@@ -636,38 +1069,55 @@ UNION
     } else if (typeof max === "number" && Number.isInteger(max) && max >= 1) {
       this._limit = max;
     } else {
-      throw new Error(`SelectBuilder: "limit(n)" must receive a positive integer (got "${max}")`);
+      throw new Error(
+        `SelectBuilder: "limit(n)" must receive a positive integer (got "${max}")`
+      );
     }
     return this;
   }
+  /**
+   * Fetch results from the given offset
+   * @param number  The offset (placeholder string or integer greater than or equal to 0)
+   */
   offset(number) {
     if (typeof number === "string" && this._isEntirelyDigits(number.trim())) {
       this._offset = parseInt(number, 10);
     } else if (typeof number === "number" && Number.isInteger(number) && number >= 0) {
       this._offset = number;
     } else {
-      throw new Error(`SelectBuilder: "offset(n)" must receive a positive integer (got "${number}")`);
+      throw new Error(
+        `SelectBuilder: "offset(n)" must receive a positive integer (got "${number}")`
+      );
     }
     return this;
   }
+  /**
+   * Set the offset based on the limit with the given page number
+   * @param number  The page number (integer greater than 0)
+   */
   page(number) {
     if (typeof number === "string" && this._isEntirelyDigitsNoZeros(number.trim())) {
       this._page = parseInt(number, 10);
     } else if (typeof number === "number" && Number.isInteger(number) && number >= 1) {
       this._page = number;
     } else {
-      throw new Error('SelectBuilder: "page(n)" must receive a positive integer');
+      throw new Error(
+        'SelectBuilder: "page(n)" must receive a positive integer'
+      );
     }
     return this;
   }
-}
+};
+
 // src/extractGrouped/extractGrouped.ts
 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}`);
+      throw new Error(
+        `Column "${String(field)}" is not present in record ${idx}`
+      );
     }
     if (!grouped[record[field]]) {
       grouped[record[field]] = [];
@@ -677,35 +1127,44 @@ function extractGrouped(field, records) {
   }
   return grouped;
 }
+
 // src/extractIndexed/extractIndexed.ts
 function extractIndexed(field, records) {
   let idx = 0;
   const indexed = {};
   for (const record of records) {
     if (!(field in record)) {
-      throw new Error(`Column "${String(field)}" is not present in record ${idx}`);
+      throw new Error(
+        `Column "${String(field)}" is not present in record ${idx}`
+      );
     }
     indexed[record[field]] = record;
     idx++;
   }
   return indexed;
 }
+
 // src/extractLookup/extractLookup.ts
 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}`);
+      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}`);
+      throw new Error(
+        `Column "${String(valueField)}" is not present in record ${idx}`
+      );
     }
     idx++;
-    lookup[String(record[keyField])] = record[valueField];
+    lookup[record[keyField]] = record[valueField];
   }
   return lookup;
 }
+
 // src/getPagination/getPagination.ts
 function getPagination(query, total) {
   total = Number(total) || 0;
@@ -725,8 +1184,8 @@ function getPagination(query, total) {
   const numPages = total === 0 || perPage === null ? 0 : Math.ceil(total / perPage) || 0;
   const isFirst = page === 1;
   const isLast = numPages > 0 && page === numPages;
-  const prevPage = numPages === 0 ? null : page - 1 || null;
-  const nextPage = numPages > 0 && page + 1 <= numPages ? page + 1 : null;
+  const prevPage = numPages === 0 || page === null ? null : page - 1 || null;
+  const nextPage = numPages > 0 && page !== null && page + 1 <= numPages ? page + 1 : null;
   return {
     page,
     prevPage,
@@ -738,6 +1197,7 @@ function getPagination(query, total) {
     isLast
   };
 }
+
 // src/runMysql/runMysql.ts
 function _queryToPromise(mysqlClient, sql, bindings) {
   return new Promise((resolve, reject) => {
@@ -788,6 +1248,7 @@ async function runMysqlAsyncWithCount(mysqlClient, query, {
     return { records, total: 0, pagination: getPagination(query, 0), fields };
   }
 }
+
 // src/toSafeJson/toSafeJson.ts
 function toSafeJsonValue(value) {
   if (typeof value === "bigint") {
@@ -814,16 +1275,19 @@ function toSafeJsonString(records) {
 }
 
 // src/runPrisma/runPrisma.ts
-async function runPrisma(prisma, query, { engine = undefined } = {}) {
+async function runPrisma(prisma, query, { engine = void 0 } = {}) {
   const { sql, bindings } = query.compile({ engine });
   return prisma.$queryRawUnsafe(sql, ...bindings);
 }
 async function runPrismaWithCount(prisma, query, {
-  engine = undefined,
+  engine = void 0,
   countExpr = "*"
 } = {}) {
   const { sql, bindings } = query.compile({ engine });
-  const records = await prisma.$queryRawUnsafe(sql, ...bindings);
+  const records = await prisma.$queryRawUnsafe(
+    sql,
+    ...bindings
+  );
   if (records.length > 0) {
     const { sql: sql2, bindings: bindings2 } = query.compileCount({ engine, countExpr });
     const result = await prisma.$queryRawUnsafe(sql2, ...bindings2);
@@ -834,20 +1298,20 @@ async function runPrismaWithCount(prisma, query, {
   }
 }
 export {
-  toSafeJsonValue,
-  toSafeJsonString,
-  toSafeJsonRecords,
-  toSafeJsonRecord,
-  runPrismaWithCount,
-  runPrisma,
-  runMysqlWithCount,
-  runMysqlAsyncWithCount,
-  runMysqlAsync,
-  runMysql,
-  getPagination,
-  extractLookup,
-  extractIndexed,
-  extractGrouped,
+  Parser,
   SelectBuilder,
-  Parser
+  extractGrouped,
+  extractIndexed,
+  extractLookup,
+  getPagination,
+  runMysql,
+  runMysqlAsync,
+  runMysqlAsyncWithCount,
+  runMysqlWithCount,
+  runPrisma,
+  runPrismaWithCount,
+  toSafeJsonRecord,
+  toSafeJsonRecords,
+  toSafeJsonString,
+  toSafeJsonValue
 };