foxhound 2.0.18 → 2.0.20

package/README.md

@@ -2,12 +2,12 @@
 
 > A fluent query generation DSL for Node.js and the browser
 
-FoxHound is a database query builder that generates dialect-specific SQL from a single chainable API.  It keeps your application code database-agnostic while producing safe, parameterized queries for MySQL, Microsoft SQL Server, SQLite, and ALASQL.
+FoxHound is a database query builder that generates dialect-specific SQL from a single chainable API.  It keeps your application code database-agnostic while producing safe, parameterized queries for MySQL, PostgreSQL, Microsoft SQL Server, SQLite, and ALASQL.
 
 ## Features
 
 - **Chainable API** — every configuration method returns the query object for fluent composition
-- **Multiple Dialects** — generate SQL for MySQL, MSSQL, SQLite, ALASQL, or plain English from the same code
+- **Multiple Dialects** — generate SQL for MySQL, PostgreSQL, MSSQL, SQLite, ALASQL, or plain English from the same code
 - **Parameterized Queries** — user-supplied values are always bound as named parameters, preventing SQL injection
 - **Schema-Aware** — automatic management of identity columns, timestamps, user stamps, and soft-delete tracking
 - **Full CRUD + Count** — build CREATE, READ, UPDATE, DELETE, UNDELETE, and COUNT queries
@@ -70,6 +70,7 @@ Application Code
 | Dialect | Target | Identifier Quoting | Parameter Prefix | Pagination |
 |---------|--------|-------------------|-----------------|------------|
 | `MySQL` | MySQL / MariaDB | `` `backticks` `` | `:name` | `LIMIT offset, count` |
+| `PostgreSQL` | PostgreSQL 9.5+ | `"double quotes"` | `:name` | `LIMIT count OFFSET offset` |
 | `MSSQL` | Microsoft SQL Server | `[brackets]` | `@name` | `OFFSET/FETCH` |
 | `SQLite` | SQLite 3 | `` `backticks` `` | `:name` | `LIMIT count OFFSET offset` |
 | `ALASQL` | ALASQL (in-memory) | `` `backticks` `` | `:name` | `LIMIT count FETCH offset` |

package/docs/README.md

@@ -1,11 +1,13 @@
 # FoxHound
 
+> A fluent query generation DSL for Node.js and the browser
+
 FoxHound is a fluent query generation DSL for Node.js and the browser.  It produces dialect-specific SQL (or other query formats) from a single chainable API, keeping your application code database-agnostic while generating safe, parameterized queries.
 
 ## Features
 
 - **Chainable API** — every configuration method returns the query object, so you can compose queries in a single expression
-- **Multiple Dialects** — generate SQL for MySQL, Microsoft SQL Server, SQLite, ALASQL, or plain English, all from the same code
+- **Multiple Dialects** — generate SQL for MySQL, PostgreSQL, Microsoft SQL Server, SQLite, ALASQL, or plain English, all from the same code
 - **Parameterized Queries** — user-supplied values are always bound as named parameters, preventing SQL injection
 - **Schema-Aware** — when a schema is provided, FoxHound automatically manages identity columns, timestamps, user stamps, and soft-delete tracking
 - **Full CRUD + Count** — build CREATE, READ, UPDATE, DELETE, UNDELETE, and COUNT queries
@@ -22,30 +24,49 @@ $ npm install foxhound
 
 ```javascript
 var libFable = require('fable');
-var _Fable = new libFable({});
-
-var tmpQuery = _Fable.Utility.waterfall.FoxHound;
-// Or create a new query directly:
 var libFoxHound = require('foxhound');
+
+var _Fable = new libFable({});
 var tmpQuery = libFoxHound.new(_Fable);
 
-tmpQuery.setScope('Users')
-    .setCap(20)
-    .setDialect('MySQL')
-    .buildReadQuery();
+tmpQuery
+	.setScope('Books')
+	.setDataElements(['Title', 'Author', 'PublishedYear'])
+	.addFilter('Genre', 'Science Fiction')
+	.addSort({Column: 'PublishedYear', Direction: 'Descending'})
+	.setCap(25)
+	.setDialect('MySQL')
+	.buildReadQuery();
 
 console.log(tmpQuery.query.body);
-// => SELECT `Users`.* FROM `Users` LIMIT 20;
+// => SELECT `Title`, `Author`, `PublishedYear` FROM `Books`
+//    WHERE `Books`.`Genre` = :Genre_w0 ORDER BY PublishedYear DESC LIMIT 25;
+
+console.log(tmpQuery.query.parameters);
+// => { Genre_w0: 'Science Fiction' }
 ```
 
 ## How It Works
 
 1. **Create a Query** — instantiate via `foxhound.new(fable)` or through a Fable service
 2. **Configure** — chain methods to set scope (table), fields, filters, sorts, joins, and pagination
-3. **Set a Dialect** — call `.setDialect('MySQL')` (or MSSQL, SQLite, ALASQL, English)
+3. **Set a Dialect** — call `.setDialect('MySQL')` (or PostgreSQL, MSSQL, SQLite, ALASQL, English)
 4. **Build** — call a build method such as `.buildReadQuery()` to generate the SQL
 5. **Execute** — read the generated SQL from `.query.body` and bound parameters from `.query.parameters`
 
+## Documentation
+
+- [Quickstart](quickstart.md) — get up and running in five minutes
+- [Architecture](architecture.md) — understand FoxHound's internal design
+- [Filters](filters.md) — filter operators and logical grouping
+- [Sorting](sorting.md) — ORDER BY clause generation
+- [Joins](joins.md) — multi-table queries
+- [Pagination](pagination.md) — LIMIT/OFFSET across dialects
+- [Schema Integration](schema.md) — automatic column management
+- [Dialects](dialects/README.md) — dialect-specific features and differences
+- [API Reference](api/README.md) — complete function reference with code examples
+- [Query Overrides](query-overrides.md) — custom SQL templates
+
 ## Related Packages
 
 | Package | Purpose |

package/docs/_cover.md

@@ -5,7 +5,8 @@
 - Chainable API that generates dialect-specific SQL
 - Parameterized queries for safe, injection-free operation
 - Schema-aware with automatic identity, timestamp, and soft-delete management
-- Multiple dialects: MySQL, MSSQL, SQLite, ALASQL, and more
+- Multiple dialects: MySQL, PostgreSQL, MSSQL, SQLite, ALASQL, and more
 
+[Get Started](quickstart.md)
+[API Reference](api/README.md)
 [GitHub](https://github.com/stevenvelozo/foxhound)
-[Get Started](#foxhound)

package/docs/_sidebar.md

@@ -1,6 +1,7 @@
 - Getting Started
 
-  - [Introduction](/)
+  - [Introduction](README.md)
+  - [Quickstart](quickstart.md)
   - [Architecture](architecture.md)
 
 - Query Building
@@ -23,10 +24,29 @@
 
   - [Dialects Overview](dialects/README.md)
   - [MySQL](dialects/mysql.md)
+  - [PostgreSQL](dialects/postgresql.md)
   - [MSSQL](dialects/mssql.md)
   - [SQLite](dialects/sqlite.md)
   - [ALASQL](dialects/alasql.md)
 
+- API Reference
+
+  - [API Overview](api/README.md)
+  - [setScope](api/setScope.md)
+  - [setDialect](api/setDialect.md)
+  - [setDataElements](api/setDataElements.md)
+  - [addFilter / setFilter](api/addFilter.md)
+  - [addSort / setSort](api/addSort.md)
+  - [addJoin / setJoin](api/addJoin.md)
+  - [setCap / setBegin](api/setCap.md)
+  - [addRecord](api/addRecord.md)
+  - [setIDUser](api/setIDUser.md)
+  - [setDistinct](api/setDistinct.md)
+  - [Build Methods](api/buildQuery.md)
+  - [clone / reset](api/clone.md)
+  - [Behavior Flags](api/behaviorFlags.md)
+  - [Query Overrides](api/queryOverrides.md)
+
 - Advanced
 
   - [Schema Integration](schema.md)

package/docs/_topbar.md

@@ -0,0 +1,7 @@
+# FoxHound
+
+- [Introduction](README.md)
+- [Quickstart](quickstart.md)
+- [API Reference](api/README.md)
+- [GitHub](https://github.com/stevenvelozo/foxhound)
+- [npm](https://www.npmjs.com/package/foxhound)

package/docs/api/README.md

@@ -0,0 +1,73 @@
+# API Reference
+
+Complete reference for every public method and property in FoxHound.
+
+## Creating a Query
+
+```javascript
+var libFable = require('fable');
+var libFoxHound = require('foxhound');
+
+var _Fable = new libFable({});
+var tmpQuery = libFoxHound.new(_Fable);
+```
+
+## Method Categories
+
+### Configuration
+
+These methods configure the query and return `this` for chaining.
+
+| Method | Purpose |
+|--------|---------|
+| [setScope(pScope)](api/setScope.md) | Set the target table or collection |
+| [setDialect(pDialectName)](api/setDialect.md) | Set the SQL dialect for output |
+| [setDataElements(pDataElements)](api/setDataElements.md) | Set which columns to select |
+| [setDistinct(pDistinct)](api/setDistinct.md) | Enable DISTINCT results |
+| [addFilter / setFilter](api/addFilter.md) | Add or set WHERE clause conditions |
+| [addSort / setSort](api/addSort.md) | Add or set ORDER BY expressions |
+| [addJoin / setJoin](api/addJoin.md) | Add or set JOIN expressions |
+| [setCap / setBegin](api/setCap.md) | Set pagination (LIMIT / OFFSET) |
+| [addRecord(pRecord)](api/addRecord.md) | Add a record for INSERT or UPDATE |
+| [setIDUser(pIDUser)](api/setIDUser.md) | Set the user ID for audit columns |
+| [Behavior Flags](api/behaviorFlags.md) | Disable auto-identity, timestamps, user stamps, delete tracking |
+
+### Query Building
+
+| Method | Purpose |
+|--------|---------|
+| [Build Methods](api/buildQuery.md) | buildCreateQuery, buildReadQuery, buildUpdateQuery, buildDeleteQuery, buildUndeleteQuery, buildCountQuery |
+
+### Utility
+
+| Method | Purpose |
+|--------|---------|
+| [clone / resetParameters / mergeParameters](api/clone.md) | Copy, reset, or merge query state |
+| [Query Overrides](api/queryOverrides.md) | Custom SQL templates for Read and Count |
+
+## Properties
+
+| Property | Type | Access | Description |
+|----------|------|--------|-------------|
+| `query` | Object | get/set | The generated query (`body`, `schema`, `records`, `parameters`) |
+| `result` | Object | get/set | Execution results (`executed`, `value`, `error`) |
+| `parameters` | Object | get/set | Full parameters state |
+| `dialect` | Object | get | Current dialect object |
+| `uuid` | String | get | Unique identifier for this query |
+| `logLevel` | Integer | get | Current log level |
+| `indexHints` | Array | get/set | Index hints for the database engine |
+
+## Chaining
+
+All configuration methods return `this`, enabling fluent composition:
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDataElements(['Title', 'Author'])
+	.addFilter('Genre', 'Fantasy')
+	.addSort('Title')
+	.setCap(25)
+	.setDialect('PostgreSQL')
+	.buildReadQuery();
+```

package/docs/api/addFilter.md

@@ -0,0 +1,170 @@
+# addFilter / setFilter
+
+Add or replace filter conditions for the WHERE clause.
+
+## addFilter
+
+Add a single filter expression to the existing filter array.
+
+### Signature
+
+```javascript
+tmpQuery.addFilter(pColumn, pValue, pOperator, pConnector, pParameter)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pColumn` | String | *(required)* | Column name |
+| `pValue` | Any | *(required)* | Value to compare against |
+| `pOperator` | String | `'='` | Comparison operator |
+| `pConnector` | String | `'AND'` | Logical connector (`AND`, `OR`, `NONE`) |
+| `pParameter` | String | `pColumn` | Parameter name for bound values |
+
+### Returns
+
+Returns `this` for chaining.
+
+### Examples
+
+#### Simple equality filter
+
+```javascript
+tmpQuery.addFilter('Genre', 'Science Fiction');
+// WHERE Genre = :Genre_w0
+```
+
+#### Greater than
+
+```javascript
+tmpQuery.addFilter('PublishedYear', 2000, '>');
+// WHERE PublishedYear > :PublishedYear_w0
+```
+
+#### OR connector
+
+```javascript
+tmpQuery
+	.addFilter('Genre', 'Science Fiction')
+	.addFilter('Genre', 'Fantasy', '=', 'OR');
+// WHERE Genre = :Genre_w0 OR Genre = :Genre_w1
+```
+
+#### LIKE operator
+
+```javascript
+tmpQuery.addFilter('Title', '%Dune%', 'LIKE');
+// WHERE Title LIKE :Title_w0
+```
+
+#### IN operator
+
+```javascript
+tmpQuery.addFilter('IDOffice', [10, 11, 15, 18], 'IN');
+// WHERE IDOffice IN ( :IDOffice_w0 )
+```
+
+#### NOT IN operator
+
+```javascript
+tmpQuery.addFilter('Status', ['Deleted', 'Archived'], 'NOT IN');
+// WHERE Status NOT IN ( :Status_w0 )
+```
+
+#### IS NULL / IS NOT NULL
+
+```javascript
+tmpQuery.addFilter('DeleteDate', '', 'IS NULL');
+// WHERE DeleteDate IS NULL
+
+tmpQuery.addFilter('Title', '', 'IS NOT NULL');
+// WHERE Title IS NOT NULL
+```
+
+#### Grouped conditions with parentheses
+
+```javascript
+tmpQuery
+	.addFilter('', '', '(')
+	.addFilter('Genre', 'Science Fiction')
+	.addFilter('Genre', 'Fantasy', '=', 'OR')
+	.addFilter('', '', ')')
+	.addFilter('PublishedYear', 2000, '>');
+// WHERE ( Genre = :Genre_w1 OR Genre = :Genre_w2 )
+//   AND PublishedYear > :PublishedYear_w4
+```
+
+#### Custom parameter name
+
+```javascript
+tmpQuery.addFilter('Books.Genre', 'Fantasy', '=', 'AND', 'BookGenre');
+// WHERE Books.Genre = :BookGenre_w0
+```
+
+## setFilter
+
+Replace the entire filter array.
+
+### Signature
+
+```javascript
+tmpQuery.setFilter(pFilter)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFilter` | Object or Array | Filter expression(s) |
+
+### Examples
+
+#### Single filter object
+
+```javascript
+tmpQuery.setFilter({
+	Column: 'Genre',
+	Operator: '=',
+	Value: 'Fantasy',
+	Connector: 'AND',
+	Parameter: 'Genre'
+});
+```
+
+#### Multiple filters
+
+```javascript
+tmpQuery.setFilter([
+	{Column: 'Genre', Operator: '=', Value: 'Fantasy', Connector: 'AND', Parameter: 'Genre'},
+	{Column: 'PublishedYear', Operator: '>', Value: 2000, Connector: 'AND', Parameter: 'PublishedYear'}
+]);
+```
+
+## Filter Object Structure
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Column` | String | Column name to filter on |
+| `Operator` | String | Comparison operator |
+| `Value` | Any | Value to compare against |
+| `Connector` | String | Logical connector: `AND`, `OR`, or `NONE` |
+| `Parameter` | String | Named parameter key |
+
+## Supported Operators
+
+| Operator | SQL | Description |
+|----------|-----|-------------|
+| `'='` | `=` | Equals (default) |
+| `'!='` | `!=` | Not equals |
+| `'>'` | `>` | Greater than |
+| `'>='` | `>=` | Greater than or equal |
+| `'<'` | `<` | Less than |
+| `'<='` | `<=` | Less than or equal |
+| `'LIKE'` | `LIKE` | Pattern match |
+| `'IN'` | `IN (...)` | Value in set |
+| `'NOT IN'` | `NOT IN (...)` | Value not in set |
+| `'IS NULL'` | `IS NULL` | Null check |
+| `'IS NOT NULL'` | `IS NOT NULL` | Not-null check |
+| `'('` | `(` | Open group |
+| `')'` | `)` | Close group |

package/docs/api/addJoin.md

@@ -0,0 +1,128 @@
+# addJoin / setJoin
+
+Add or replace JOIN expressions for multi-table queries.
+
+## addJoin
+
+Add a single join expression.
+
+### Signature
+
+```javascript
+tmpQuery.addJoin(pTable, pFrom, pTo, pType)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pTable` | String | *(required)* | Table to join |
+| `pFrom` | String | *(required)* | Column on the join table (must start with `pTable`) |
+| `pTo` | String | *(required)* | Column on the base table (must include a `.`) |
+| `pType` | String | `'INNER JOIN'` | Join type |
+
+### Returns
+
+Returns `this` for chaining.
+
+### Examples
+
+#### Inner join (default)
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.addJoin('Authors', 'Authors.IDAuthor', 'Books.IDAuthor')
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+// => SELECT `Books`.* FROM `Books`
+//    INNER JOIN Authors ON Authors.IDAuthor = Books.IDAuthor;
+```
+
+#### Left join
+
+```javascript
+tmpQuery.addJoin('Authors', 'Authors.IDAuthor', 'Books.IDAuthor', 'LEFT JOIN');
+
+// => ... LEFT JOIN Authors ON Authors.IDAuthor = Books.IDAuthor ...
+```
+
+#### Right join
+
+```javascript
+tmpQuery.addJoin('Reviews', 'Reviews.IDBook', 'Books.IDBook', 'RIGHT JOIN');
+
+// => ... RIGHT JOIN Reviews ON Reviews.IDBook = Books.IDBook ...
+```
+
+#### Multiple joins
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.addJoin('Authors', 'Authors.IDAuthor', 'Books.IDAuthor')
+	.addJoin('Publishers', 'Publishers.IDPublisher', 'Books.IDPublisher', 'LEFT JOIN')
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+// => SELECT `Books`.* FROM `Books`
+//    INNER JOIN Authors ON Authors.IDAuthor = Books.IDAuthor
+//    LEFT JOIN Publishers ON Publishers.IDPublisher = Books.IDPublisher;
+```
+
+## setJoin
+
+Replace the entire join array.
+
+### Signature
+
+```javascript
+tmpQuery.setJoin(pJoin)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pJoin` | Object or Array | Join expression(s) |
+
+### Examples
+
+#### Single join object
+
+```javascript
+tmpQuery.setJoin({
+	Type: 'INNER JOIN',
+	Table: 'Authors',
+	From: 'Authors.IDAuthor',
+	To: 'Books.IDAuthor'
+});
+```
+
+#### Array of joins
+
+```javascript
+tmpQuery.setJoin([
+	{Type: 'INNER JOIN', Table: 'Authors', From: 'Authors.IDAuthor', To: 'Books.IDAuthor'},
+	{Type: 'LEFT JOIN', Table: 'Publishers', From: 'Publishers.IDPublisher', To: 'Books.IDPublisher'}
+]);
+```
+
+## Join Object Structure
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Type` | String | Join type (e.g. `'INNER JOIN'`, `'LEFT JOIN'`, `'RIGHT JOIN'`) |
+| `Table` | String | Table to join |
+| `From` | String | Column on the join table |
+| `To` | String | Column on the base or another table |
+
+## Validation
+
+FoxHound validates join parameters:
+
+- `pTable` must be a string
+- `pFrom` must start with the join table name
+- `pTo` must include a dot (table-qualified column name)
+- Invalid joins are logged as warnings and silently skipped

package/docs/api/addRecord.md

@@ -0,0 +1,108 @@
+# addRecord
+
+Add a record for CREATE or UPDATE operations.
+
+## Signature
+
+```javascript
+tmpQuery.addRecord(pRecord)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pRecord` | Object | Yes | Key-value pairs of column names and values |
+
+## Returns
+
+Returns `this` for chaining.
+
+## Description
+
+Adds a record object to the query's record list.  The keys become column names and the values become parameterized values in the generated SQL.
+
+For CREATE operations, the record defines the column-value pairs for the INSERT statement.  For UPDATE operations, the record defines the SET clause (which columns to change and their new values).
+
+Only the first record in the list is used for query generation in the current implementation.
+
+Non-object values are silently ignored.
+
+## Examples
+
+### Insert a new record
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.addRecord({Title: 'Dune', Author: 'Frank Herbert', PublishedYear: 1965})
+	.setDialect('MySQL')
+	.buildCreateQuery();
+
+console.log(tmpQuery.query.body);
+// => INSERT INTO `Books` ( Title, Author, PublishedYear)
+//    VALUES ( :Title_0, :Author_1, :PublishedYear_2);
+
+console.log(tmpQuery.query.parameters);
+// => { Title_0: 'Dune', Author_1: 'Frank Herbert', PublishedYear_2: 1965 }
+```
+
+### Update a record
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.addFilter('IDBook', 42)
+	.addRecord({Title: 'Dune Messiah', PublishedYear: 1969})
+	.setDialect('MySQL')
+	.buildUpdateQuery();
+
+console.log(tmpQuery.query.body);
+// => UPDATE `Books` SET Title = :Title_0, PublishedYear = :PublishedYear_1
+//    WHERE IDBook = :IDBook_w0;
+```
+
+### With schema for automatic column management
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.addRecord({
+		IDBook: null,
+		Title: 'Neuromancer',
+		Author: 'William Gibson',
+		CreateDate: null,
+		CreatingIDUser: null,
+		UpdateDate: null,
+		UpdatingIDUser: null,
+		Deleted: 0
+	});
+
+tmpQuery.query.schema = [
+	{Column: 'IDBook', Type: 'AutoIdentity'},
+	{Column: 'Title', Type: 'String'},
+	{Column: 'Author', Type: 'String'},
+	{Column: 'CreateDate', Type: 'CreateDate'},
+	{Column: 'CreatingIDUser', Type: 'CreateIDUser'},
+	{Column: 'UpdateDate', Type: 'UpdateDate'},
+	{Column: 'UpdatingIDUser', Type: 'UpdateIDUser'},
+	{Column: 'Deleted', Type: 'Deleted'}
+];
+
+tmpQuery.query.IDUser = 5;
+tmpQuery.setDialect('MySQL').buildCreateQuery();
+
+// IDBook    => NULL (AutoIdentity)
+// CreateDate => NOW(3) (auto timestamp)
+// CreatingIDUser => 5 (auto user stamp)
+```
+
+### Empty record
+
+```javascript
+// No-op: buildCreateQuery() and buildUpdateQuery() return false
+tmpQuery.addRecord({});
+tmpQuery.buildCreateQuery();
+console.log(tmpQuery.query.body);
+// => false
+```