sql-love 1.0.6 → 1.1.1

package/LICENSE.md

@@ -1,5 +1,5 @@
 ISC License (ISC)
-Copyright 2023-2025 Ken Snyder
+Copyright 2023-2026 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,15 +1,13 @@
-<img alt="SQL Love Logo" src="https://github.com/kensnyder/sql-love/raw/main/assets/sql-love-logo.png?v=1.0.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.1.0" width="250" height="208" />
 
 # sql-love
 
-[![NPM Link](https://badgen.net/npm/v/sql-love?v=1.0.6)](https://npmjs.com/package/sql-love)
-[![Language](https://badgen.net/static/language/TS?v=1.0.6)](https://github.com/search?q=repo:kensnyder/sql-love++language:TypeScript&type=code)
-[![Build Status](https://github.com/kensnyder/sql-love/actions/workflows/node.js.yml/badge.svg?v=1.0.6)](https://github.com/kensnyder/sql-love/actions)
-[![Code Coverage](https://codecov.io/gh/kensnyder/sql-love/branch/main/graph/badge.svg?v=1.0.6)](https://codecov.io/gh/kensnyder/sql-love)
-[![Gzipped Size](https://badgen.net/bundlephobia/minzip/sql-love?label=minzipped&v=1.0.6)](https://bundlephobia.com/package/sql-love@1.0.6)
-[![Dependency details](https://badgen.net/bundlephobia/dependency-count/sql-love?v=1.0.6)](https://www.npmjs.com/package/sql-love?activeTab=dependencies)
-[![Tree shakeable](https://badgen.net/bundlephobia/tree-shaking/sql-love?v=1.0.6)](https://www.npmjs.com/package/sql-love)
-[![ISC License](https://badgen.net/static/license/ISC/green?v=1.0.6)](https://opensource.org/licenses/ISC)
+[![NPM Link](https://badgen.net/npm/v/sql-love?v=1.1.0)](https://npmjs.com/package/sql-love)
+[![Language](https://badgen.net/static/language/TS?v=1.1.0)](https://github.com/search?q=repo:kensnyder/sql-love++language:TypeScript&type=code)
+[![Code Coverage](https://codecov.io/gh/kensnyder/sql-love/branch/main/graph/badge.svg?v=1.1.0)](https://codecov.io/gh/kensnyder/sql-love)
+![Dependencies](https://badgen.net/static/dependencies/0/green)
+![Tree shakeable](https://badgen.net/static/tree%20shakeable/Yes/green)
+[![ISC License](https://badgen.net/static/license/ISC/green?v=1.1.0)](https://opensource.org/licenses/ISC)
 
 Classes for parsing and building SQL select queries in Node/Bun/Deno.
 
@@ -68,7 +66,7 @@ if (areaCode) {
 }
 query.sort(sortField);
 query.limit(limitTo);
-const { sql, bindings } = query.compile();
+const { sql, bindings } = query.compile({ engine: 'pg' });
 
 //
 // Then execute the SQL in your preferred client:
@@ -190,15 +188,16 @@ Use the following methods to build queries. And see
 - `query.having(expression)` - Having an arbitrary expression
 - `query.having(columnValueRecord)` - Add multiple conditions
 - `query.orHaving(expressions)` - Multiple `having()`s joined by OR
-- `query.orderBy(column)` - Add ORDER BY clause
-- `query.sortField(column, mapNames)` - Add ORDER BY clause with mapNames
+- `query.orderBy(column, direction)` - Add ORDER BY clause
+- `query.sortField(column, mapNames, modifier)` - Add ORDER BY clause with mapNames
 - `query.limit(num)` - Limit by the given number
 - `query.offset(num)` - Specify an offset
 - `query.page(num)` - Automatically calculate offset based on limit and page
 - `query.columns(columnNames)` - Add column names to fetch (alias `select()`)
 - `query.column(columnName)` - Add a column name to fetch
-- `query.table(tableName)` - Specify the table in the FROM clause
-- `query.from(tableName)` - Same as above
+- `query.table(tableName)` - Add a table to add to the FROM clause
+- `query.tables(tableNames)` - Add an array of tables to add to the FROM clause
+- `query.from(tableName)` - Alias for `table()`
 - `query.join(expression)` - Add a JOIN expression
 - `query.innerJoin(expression)` - Add an INNER JOIN expression
 - `query.leftJoin(expression)` - Add a LEFT JOIN expression
@@ -213,7 +212,13 @@ Use the following methods to build queries. And see
 ### More examples
 
 ```js
-// The following are equivalent
+// building the FROM clause
+query.column('id');
+query.column('"Media"."postId"');
+query.column('CONCAT(first_name, " ", last_name) AS full_name');
+query.columns(['id', 'first_name', 'last_name']);
+
+// Ways to test against NULL
 query.where('deleted_at', '=', null);
 query.where('deleted_at', '=', undefined);
 query.where('deleted_at', null);
@@ -222,15 +227,16 @@ query.where('deleted_at IS NULL');
 query.where({ deleted_at: null });
 query.where({ deleted_at: undefined });
 
-// the following demonstrate ways to use LIKE
+// Using 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%');
+query.where('name', 'ILIKE %?', 'son');
 
-// The following demonstrate ways to use various operators
+// Various operators
 query.where('price', '=', 100);
 query.where('price', '!=', 100);
 query.where('price', '<>', 100);
@@ -243,7 +249,7 @@ 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
+// Using IN and NOT IN
 query.where('status', 'IN', ['pending', 'approved']);
 query.where('status', ['pending', 'approved']);
 query.where('status', '=', ['pending', 'approved']);
@@ -254,7 +260,7 @@ query.where({ 'status NOT IN': ['pending', 'approved'] });
 query.where({ 'status !=': ['pending', 'approved'] });
 query.where({ 'status <>': ['pending', 'approved'] });
 
-// the following demonstrates how to use question marks for binding
+// Question marks for binding
 query.where(
   'users.id IN (SELECT user_id FROM roles WHERE customer_id IN (?, ?))',
   [1, 2]
@@ -265,7 +271,7 @@ query.where(
   [1]
 );
 
-// The following demonstrates using objects to specify multiple conditions
+// Multiple conditions
 query.where({
   deleted_at: null,
   'price >': 100,
@@ -277,7 +283,7 @@ query.where({
 
 // Note: .having() supports the same signatures as .where()
 
-// The following demonstrate equivalent ways to use OR
+// 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']);
@@ -289,7 +295,7 @@ query.where('(approved_at IS NULL OR denied_at IS NULL)');
 
 // Note: .orHaving() supports the same signatures as .orWhere()
 
-// The following demonstrate joins
+// 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(?, ?)', [
@@ -297,10 +303,40 @@ query.outerJoin('phone_numbers p ON p.user_id = u.id AND p.type NOT IN(?, ?)', [
   'cell',
 ]);
 
-// The following demonstrates pagination
-query.limit(10).page(3); // LIMIT 10 OFFSET 20
-
-// The following demonstrates cloning
+// Grouping
+
+// Sorting
+query.orderBy('modified_at'); // ORDER BY modified_at
+query.orderBy('modified_at', 'DESC'); // ORDER BY modified_at DESC
+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('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 >
+
+// Sorting with support for hyphens and mapping
+query.sortField('-modified_at'); // ORDER BY modified_at DESC
+query.sortField('-created', { created: 'created_at' }); // ORDER BY created_at DESC
+query.sortField(
+  '-created_at',
+  {
+    created_at: 'posts.created_timestamp',
+  },
+  'NULLS LAST'
+); // ORDER BY posts.created_timestamp DESC NULLS LAST
+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
+
+// Pagination
+query.limit(10).page(3); // "LIMIT 10 OFFSET 20" (or for mssql, "OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY")
+
+// Cloning for creating similar queries
 const query1 = new SelectBuilder();
 query1.where('email', 'john@example.com');
 const query2 = query1.getClone();
@@ -398,10 +434,10 @@ If you need to use SQL keywords in strings, use bindings.
 
 ```js
 // ❌ WILL NOT WORK
-new SelectBuilder(`SELECT id, CONCAT('where ', expr) FROM users`);
+new SelectBuilder(`SELECT id, CONCAT('where ', column) FROM users`);
 
 // ✅ WORKING EQUIVALENT
-new SelectBuilder(`SELECT id, CONCAT(:prefix, expr) FROM users`, {
+new SelectBuilder(`SELECT id, CONCAT(:prefix, column) FROM users`, {
   prefix: 'where ',
 });
 ```
@@ -498,7 +534,9 @@ const grouped = extractGrouped('dept', records);
     { id: 1, name: 'John', dept: 'Marketing' },
     { id: 3, name: 'Tim', dept: 'Marketing' },
   ],
-  Finance: [{ id: 2, name: 'Jane', dept: 'Finance' }],
+  Finance: [
+    { id: 2, name: 'Jane', dept: 'Finance' }
+  ],
 }
 */
 ```

package/dist/index.cjs

@@ -650,13 +650,24 @@ UNION
     }
     return this;
   }
-  sortField(fieldName, mapNames = {}) {
+  sortField(fieldName, mapNames = {}, modifier = "") {
+    if (!fieldName) {
+      return this;
+    }
     let direction = "ASC";
     if (fieldName.startsWith("-")) {
+      if (mapNames[fieldName]) {
+        const maybeModifier = modifier ? ` ${modifier}` : "";
+        this.orderBy(mapNames[fieldName] + maybeModifier);
+        return this;
+      }
       direction = "DESC";
       fieldName = fieldName.slice(1);
     }
     const column = mapNames[fieldName] || fieldName;
+    if (modifier) {
+      direction += ` ${modifier}`;
+    }
     this.orderBy(column, direction);
     return this;
   }

package/dist/index.d.ts

@@ -320,7 +320,7 @@ export declare class SelectBuilder {
 	/**
 	 * Add a WHERE clause with a BETWEEN condition
 	 * @param column  The column name
-	 * @param twoValueArray  The two values to be between
+	 * @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: string, twoValueArray: [
 		any,
@@ -350,21 +350,31 @@ export declare class SelectBuilder {
 	 * @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.sortField('modified_at'); // ORDER BY modified_at
-	 *   query.sortField('-modified_at'); // ORDER BY modified_at DESC
-	 *   query.sortField('COUNT(*)'); // ORDER BY COUNT(*)
-	 *   query.sortField('COUNT(*) DESC'); // ORDER BY COUNT(*) DESC
+	 *   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: string, direction?: "ASC" | "DESC"): this;
 	/**
 	 * Sort by the given column, with a map of columns to translate
-	 * @param fieldName  The file name such as "created_at" or "-created_at" for descending
+	 * @param fieldName  The file name such as 'created_at' or '-created_at' for descending
 	 * @param [mapNames]  Column names to translate from field to column expression
+	 * @param [modifier]  Additional clause to append such as 'NULLS LAST' or 'COLLATE "en_US"'
 	 * @example
 	 *   query.sortField('-modified_at'); // ORDER BY modified_at DESC
 	 *   query.sortField('-created', {'created': 'created_at'}); // ORDER BY created_at DESC
-	 */
-	sortField(fieldName: string, mapNames?: Record<string, string>): this;
+	 *   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: string, mapNames?: Record<string, string>, modifier?: string): this;
 	/**
 	 * Check to see if the given string is 0 or all digits not starting with 0
 	 * @param string  The input string

package/dist/index.mjs

@@ -600,13 +600,24 @@ UNION
     }
     return this;
   }
-  sortField(fieldName, mapNames = {}) {
+  sortField(fieldName, mapNames = {}, modifier = "") {
+    if (!fieldName) {
+      return this;
+    }
     let direction = "ASC";
     if (fieldName.startsWith("-")) {
+      if (mapNames[fieldName]) {
+        const maybeModifier = modifier ? ` ${modifier}` : "";
+        this.orderBy(mapNames[fieldName] + maybeModifier);
+        return this;
+      }
       direction = "DESC";
       fieldName = fieldName.slice(1);
     }
     const column = mapNames[fieldName] || fieldName;
+    if (modifier) {
+      direction += ` ${modifier}`;
+    }
     this.orderBy(column, direction);
     return this;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sql-love",
-  "version": "1.0.6",
+  "version": "1.1.1",
   "description": "Build SQL queries with JavaScript",
   "type": "module",
   "engines": {
@@ -11,7 +11,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "tyxpes": "./dist/index.d.ts",
+      "types": "./dist/index.d.ts",
       "require": "./dist/index.cjs",
       "import": "./dist/index.mjs"
     }
@@ -19,7 +19,8 @@
   "scripts": {
     "test": "bun test",
     "test-watch": "bun test --watch",
-    "coverage": "bun test --coverage --coverage-reporter=lcov",
+    "coverage": "bun test --coverage",
+    "coverage-lcov": "bun test --coverage --coverage-reporter=lcov",
     "build": "bun run build:clean && bun run build:dts && bun run build:esm && bun run build:cjs",
     "build:clean": "rm -Rf dist/ && mkdir dist && touch dist/.gitkeep",
     "build:dts": "yes | bunx dts-bundle-generator -o dist/index.d.ts index.ts",
@@ -50,10 +51,10 @@
   },
   "homepage": "https://github.com/kensnyder/sql-love#readme",
   "devDependencies": {
-    "@types/bun": "^1.2.8",
-    "@types/node": "22.14.0",
-    "prettier": "3.5.3",
-    "prettier-plugin-organize-imports": "4.1.0",
-    "typescript": "5.8.3"
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "prettier": "3.9.6",
+    "prettier-plugin-organize-imports": "4.3.0",
+    "typescript": "7.0.2"
   }
 }