sql-love 0.9.1

package/.github/workflows/node.js.yml

@@ -0,0 +1,37 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: build
+
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+        # See supported Node.js release schedule at https://nodejs.org/en/about/previous-releases
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - run: |
+          npm ci
+          npm run build
+          npm test
+          npm run coverage
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          directory: ./coverage/

package/.prettierrc.json

@@ -0,0 +1,13 @@
+{
+  "plugins": ["prettier-plugin-organize-imports"],
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "bracketSpacing": true,
+  "jsxBracketSameLine": false,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+## Change Log
+
+### v0.9.1
+
+- More documentation
+- GitHub Actions CI
+- Support for parsing "OFFSET # ROWS"
+- Support for parsing "FETCH NEXT # ROWS ONLY"
+
+### v0.9.0
+
+- Initial release with `SelectBuilder`

package/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing
+
+When contributing to this repository, please note we have a code of conduct;
+please follow it in all your interactions with the project.
+
+## Pull Request Process
+
+1. Ensure all unit tests pass. Add more unit tests if applicable.
+2. Update the README.md with details of change if applicable.
+3. Give maintainers some time to review the changes.
+
+## Code of Conduct
+
+### Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+### Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+### Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+### Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+### Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening a GitHub ticket. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and
+appropriate to the circumstances. The project team is obligated to maintain
+confidentiality with regard to the reporter of an incident. Further details of
+specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+### Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

package/LICENSE.md

@@ -0,0 +1,6 @@
+ISC License (ISC)
+Copyright 2021-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.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# sql-love
+
+[![NPM Link](https://badgen.net/npm/v/sql-love?v=0.9.1)](https://npm.com/package/any-date-parser)
+[![Dependencies](https://badgen.net/static/dependencies/0/green?v=0.9.1)](https://npm.com/package/any-date-parser)
+[![Build Status](https://github.com/kensnyder/sql-love/actions/workflows/node.js.yml/badge.svg?v=0.9.1)](https://github.com/kensnyder/sql-love/actions)
+[![Code Coverage](https://codecov.io/gh/kensnyder/sql-love/branch/main/graph/badge.svg?v=0.9.1)](https://codecov.io/gh/kensnyder/sql-love)
+[![ISC License](https://badgen.net/static/license/ISC/green?v=0.9.1)](https://opensource.org/licenses/ISC)
+
+Classes for parsing and building SQL select queries in Node
+
+## Installation
+
+```bash
+npm install sql-love
+```
+
+## Table of Contents
+
+- [SelectBuilder](#selectbuilder)
+  - [Parsing base SQL](#parsing-base-sql)
+  - [Building the Query](#building-the-query)
+  - [Fetching Data](#fetching-data)
+  - [Counting Results](#counting-results)
+  - [Other Methods](#other-methods)
+  - [new SelectBuilder() Limitations](#selectparse-limitations)
+- [How to Contribute](./CONTRIBUTING.md)
+- [ISC License](./LICENSE.md)
+
+## SelectBuilder
+
+A Select object represents a SQL SELECT query and allows dynamically adding
+clauses including JOIN, WHERE, ORDER BY, LIMIT, OFFSET.
+
+### Parsing base SQL
+
+You can define a base query and pass it to the SelectBuilder constructor.
+
+```js
+const { SelectBuilder } = require('sql-love');
+const query = new SelectBuilder(`
+  SELECT u.id, u.fname, u.lname, u.email, p.phone
+  FROM users
+  LEFT JOIN phone_numbers p ON p.user_id = u.id
+    AND p.type = 'main'
+  WHERE u.is_active = 1
+`);
+if (email) {
+  query.where('u.email', email);
+}
+if (areaCode) {
+  query.where('p.phone', 'LIKE ?%', areaCode);
+}
+query.sort(sortField);
+query.limit(limitTo);
+const { sql, bindings } = query.compile();
+
+// then execute the SQL in your preferred client:
+// like mysql2
+mysql.query(sql, bindings);
+// or Prisma
+const result = await prisma.$executeRaw(sql, bindings);
+```
+
+It is possible to add placeholders to the base query.
+
+```js
+const query = new SelectBuilder(
+  `
+    SELECT u.id, u.fname, u.lname, u.email, a.city, a.zip
+    FROM users
+    LEFT JOIN addresses a ON a.user_id = u.id
+    WHERE a.state = :state
+      AND a.city IN (:city)
+  `,
+  { state: 'CA', city: ['San Francisco', 'Los Angeles'] }
+);
+
+const { sql, bindings } = query.compile();
+/* 
+Then "sql" equals:
+
+SELECT u.id, u.fname, u.lname, u.email, a.city, a.zip
+FROM users
+LEFT JOIN addresses a ON a.user_id = u.id
+WHERE a.state = ?
+  AND a.city IN (?, ?)
+  
+And "bindings" equals:
+
+['CA', 'San Francisco', 'Los Angeles'] 
+*/
+```
+
+You may specify a compiler engine to use. The default is `"mysql"`.
+
+```js
+const query = new SelectBuilder('SELECT * FROM users')
+  .limit(10)
+  .page(3)
+  .where('id', 1);
+
+query.compile('mysql').sql;
+// SELECT * FROM users WHERE id = ? OFFSET 20 LIMIT 10
+
+query.compile('pg').sql;
+// SELECT * FROM users WHERE id = $1 OFFSET 20 LIMIT 10
+
+query.compile('mssql').sql;
+// SELECT * FROM users WHERE id = ? OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY
+
+query.compile('oracle').sql;
+// SELECT * FROM users WHERE id = ? OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY
+```
+
+### Building the Query
+
+Use the following methods to build queries.
+
+- `query.where(column, operator, value)` - Require column satisfy operator
+- `query.where(column, value)` - Require column equal a value
+- `query.where(expression)` - Add an arbitrary WHERE expression
+- `query.where(columnValueRecord)` - Add multiple conditions
+- `query.whereBetween(column, [min, max])` - Require value BETWEEN, < or >
+- `query.orWhere(conditions)` - Specify multiple `where()`s joined by `OR`
+- `query.having(column, operator, value)` - Having column satisfy operator
+- `query.having(column, value)` - Having column equal value
+- `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.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.join(expression)` - Add a JOIN expression
+- `query.innerJoin(expression)` - Add an INNER JOIN expression
+- `query.leftJoin(expression)` - Add a LEFT JOIN expression
+- `query.fullJoin(expression)` - Add a FULL JOIN expression
+- `query.rightJoin(expression)` - Add a RIGHT JOIN expression
+- `query.crossJoin(expression)` - Add a CROSS JOIN expression
+- `query.leftOuterJoin(expression)` - Add a LEFT OUTER JOIN expression
+- `query.fullOuterJoin(expression)` - Add a FULL OUTER JOIN expression
+- `query.rightOuterJoin(expression)` - Add a RIGHT OUTER JOIN expression
+- `query.groupBy(column)` - Group by a column or expression
+
+### Counting Results
+
+One powerful feature of SelectBuilder is that it can construct a count query
+to determine the number of results that would have been returned if there were
+no LIMIT.
+
+```js
+const query = new SelectBuilder('SELECT id, name FROM users LIMIT 5');
+
+const { sql } = query.compileCount();
+// SELECT COUNT(*) AS found_rows FROM users
+```
+
+With queries that have a "HAVING" clause, the main query will be wrapped in a
+count query.
+
+```js
+const query = new SelectBuilder(`
+  SELECT category, COUNT(*) 
+  FROM posts 
+  GROUP BY category 
+  HAVING COUNT(*) > 1
+`);
+
+const { sql } = query.compileCount();
+/*
+SELECT COUNT(*) AS found_rows FROM (
+  SELECT category, COUNT(*) 
+  FROM posts 
+  GROUP BY category 
+  HAVING COUNT(*) > 1
+) AS subquery_results
+*/
+```
+
+### Other methods
+
+SelectBuilder has a few other useful methods.
+
+- `query.getClone()` - Get an exact copy of this query object
+- `query.unjoin(tableName)` - Remove a join expression
+- `query.reset(field)` - Reset a single aspect of the query (e.g. 'where' or 'having')
+- `query.reset(fields)` - Reset a few particular aspects of the query (e.g. \['where', 'having'\])
+- `query.reset()` - Reset query to an empty state
+
+### Parser Limitations
+
+`new SelectBuilder(sql)` uses regular expressions and is not a true parser.
+The goal is to be fast and useful for 99% of situations.
+
+Below are some limitations illustrated by example.
+
+#### Nested Subqueries
+
+Most subqueries can be parsed but sub-subqueries don't work.
+
+```js
+// ❌ WILL NOT WORK
+const query = new SelectBuilder(`
+SELECT * FROM categories_posts WHERE category_id IN(
+    SELECT id FROM categories WHERE client_id IN(
+        SELECT client_id FROM affiliations WHERE name LIKE 'test'
+    )
+)`);
+
+// ✅ WORKING EQUIVALENT
+const query = new SelectBuilder(`SELECT * FROM categories_posts`);
+const subquery =
+  new SelectBuilder(`SELECT id FROM categories WHERE client_id IN(
+    SELECT client_id FROM affiliations WHERE name LIKE 'test'
+)`);
+query.where(`category_id IN(${subquery})`);
+```
+
+#### Keywords in Strings
+
+If you need to use SQL keywords in strings, use bindings.
+
+```js
+// ❌ WILL NOT WORK
+new SelectBuilder(`SELECT id, CONCAT('where ', expr) FROM users`);
+
+// ✅ WORKING EQUIVALENT
+new SelectBuilder(`SELECT id, CONCAT(:prefix, expr) FROM users`, {
+  prefix: 'where ',
+});
+```
+
+#### Nested OR and AND Clauses
+
+Nested logic can't be parsed properly.
+
+```js
+// ❌ WILL NOT WORK
+new SelectBuilder(`
+  SELECT * FROM users
+  WHERE (
+      fname = 'Matthew' AND (
+          lname LIKE '%john' OR lname LIKE 'john%'
+      ) OR (
+          id > 0 AND is_active IS NOT NULL
+      )
+  )
+`);
+
+// ✅ WORKING EQUIVALENT
+const query = new SelectBuilder(`SELECT * FROM users`);
+query.orWhere([
+  "fname = 'Matthew' AND (lname LIKE '%john' OR lname LIKE 'john%')",
+  'id > 0 AND is_active IS NOT NULL',
+]);
+```

package/codecov.yml

@@ -0,0 +1,7 @@
+codecov:
+  branch: main
+
+coverage:
+  precision: 1
+  round: down
+  range: '70...100'

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Parser } from './src/Parser/Parser';
+export { default as SelectBuilder } from './src/SelectBuilder/SelectBuilder';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { default as Parser } from './src/Parser/Parser';
+export { default as SelectBuilder } from './src/SelectBuilder/SelectBuilder';

package/dist/src/Parser/Parser.d.ts

@@ -0,0 +1,157 @@
+import type Select from '../SelectBuilder/SelectBuilder';
+/**
+ * Parse SQL and populate onto a Select query object
+ */
+export default class Parser {
+    query: Select;
+    /**
+     * Create a new instance
+     * @param query  A Select object on which to build parsed conditions
+     */
+    constructor(query: Select);
+    /**
+     * Strip single-line and multi-line comment blocks
+     * @param sql  The SQL string
+     * @return  The SQL string without comments
+     * @private
+     */
+    _stripComments(sql: string): string;
+    /**
+     * 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: string): {
+        sql: string;
+        subQueries: {};
+    };
+    /**
+     * Inject column subQueries back into this object
+     * @param subQueries  The lookup of extracted subQueries
+     * @private
+     */
+    _injectSubQueries(subQueries: Record<string, string>): void;
+    /**
+     * Split SQL into clauses (used by parse())
+     * @param sql  The SQL to split
+     * @return
+     * @private
+     */
+    _split(sql: string): string[];
+    /**
+     * 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: string): boolean;
+    /**
+     * Handle SQL_CALC_FOUND_ROWS and column names
+     * @param clause  The clause after the SELECT
+     * @private
+     */
+    _handleSELECT(clause: string): void;
+    /**
+     * Handle table names
+     * @param clause  The clause after the FROM
+     * @private
+     */
+    _handleFROM(clause: string): void;
+    /**
+     * Handle INNER JOIN statements
+     * @param clause  The clause after the INNER JOIN
+     * @private
+     */
+    _handleINNER_JOIN(clause: string): void;
+    /**
+     * Handle LEFT JOIN statements
+     * @param clause  The clause after the LEFT JOIN
+     * @private
+     */
+    _handleLEFT_JOIN(clause: string): void;
+    /**
+     * Handle LEFT OUTER JOIN statements
+     * @param clause  The clause after the LEFT OUTER JOIN
+     * @private
+     */
+    _handleLEFT_OUTER_JOIN(clause: string): void;
+    /**
+     * Handle RIGHT JOIN statements
+     * @param clause  The clause after the RIGHT JOIN
+     * @private
+     */
+    _handleRIGHT_JOIN(clause: string): void;
+    /**
+     * Handle RIGHT OUTER JOIN statements
+     * @param clause  The clause after the RIGHT OUTER JOIN
+     * @private
+     */
+    _handleRIGHT_OUTER_JOIN(clause: string): void;
+    /**
+     * Handle CROSS JOIN statements
+     * @param clause  The clause after the CROSS JOIN
+     * @private
+     */
+    _handleCROSS_JOIN(clause: string): void;
+    /**
+     * Handle FULL JOIN statements
+     * @param clause  The clause after the FULL JOIN
+     * @private
+     */
+    _handleFULL_JOIN(clause: string): void;
+    /**
+     * Handle FULL OUTER JOIN statements
+     * @param clause  The clause after the FULL OUTER JOIN
+     * @private
+     */
+    _handleFULL_OUTER_JOIN(clause: string): void;
+    /**
+     * Handle WHERE conditions
+     * @param clause  All the conditions after WHERE
+     * @private
+     */
+    _handleWHERE(clause: string): void;
+    /**
+     * Handle HAVING statements
+     * @param clause  All the conditions after HAVING
+     * @private
+     */
+    _handleHAVING(clause: string): void;
+    /**
+     * Build a conditions list
+     * @param type  Either where or having
+     * @param clause  The expressions following the type keyword
+     * @private
+     */
+    _handleConditions(type: 'where' | 'having', clause: string): void;
+    /**
+     * Handle GROUP BY statements
+     * @param clause  The clauses after the GROUP BY
+     * @private
+     */
+    _handleGROUP_BY(clause: string): void;
+    /**
+     * Handle ORDER BY statements
+     * @param clause  The clause after the ORDER BY
+     * @private
+     */
+    _handleORDER_BY(clause: string): void;
+    /**
+     * Handle LIMIT statements including "LIMIT #" and "LIMIT #, #"
+     * @param clause  The clause after the LIMIT
+     * @private
+     */
+    _handleLIMIT(clause: string): void;
+    /**
+     * Handle OFFSET statements
+     * @param clause  The number after the OFFSET
+     * @private
+     */
+    _handleOFFSET(clause: string): void;
+    /**
+     * Handle OFFSET statements
+     * @param clause  The number after the OFFSET
+     * @private
+     */
+    _handleFETCH_NEXT(clause: string): void;
+}