foxhound 2.0.12 → 2.0.15

package/docs/pagination.md

@@ -0,0 +1,82 @@
+# Pagination
+
+FoxHound provides dialect-aware pagination through the `setBegin()` and `setCap()` methods.
+
+## Basic Usage
+
+```javascript
+// Get the first 20 records
+tmpQuery
+    .setScope('Books')
+    .setCap(20)
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+// MySQL:  SELECT ... LIMIT 20;
+// MSSQL:  SELECT ... OFFSET 0 ROWS FETCH NEXT 20 ROWS ONLY;
+// SQLite: SELECT ... LIMIT 20;
+```
+
+## Offset Pagination
+
+```javascript
+// Skip the first 40 records, then get 20
+tmpQuery
+    .setScope('Books')
+    .setBegin(40)
+    .setCap(20)
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+// MySQL:  SELECT ... LIMIT 40, 20;
+// MSSQL:  SELECT ... OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY;
+// SQLite: SELECT ... LIMIT 20 OFFSET 40;
+```
+
+## Methods
+
+### setCap(pCapAmount)
+
+Set the maximum number of records to return.  Must be a non-negative integer.
+
+```javascript
+tmpQuery.setCap(50);   // Return at most 50 rows
+tmpQuery.setCap(false); // Remove the cap (return all rows)
+```
+
+### setBegin(pBeginAmount)
+
+Set the zero-based starting offset.  Must be a non-negative integer.
+
+```javascript
+tmpQuery.setBegin(100);  // Start at the 101st record
+tmpQuery.setBegin(false); // Remove the offset
+```
+
+## Page-Based Pagination Helper
+
+FoxHound doesn't include a built-in page number helper, but it's easy to calculate:
+
+```javascript
+var tmpPageSize = 20;
+var tmpPageNumber = 3; // Zero-based
+
+tmpQuery
+    .setBegin(tmpPageNumber * tmpPageSize)
+    .setCap(tmpPageSize);
+```
+
+## Dialect Syntax Comparison
+
+| Dialect | Cap Only | Cap + Begin |
+|---------|----------|-------------|
+| **MySQL** | `LIMIT 20` | `LIMIT 40, 20` |
+| **MSSQL** | `OFFSET 0 ROWS FETCH NEXT 20 ROWS ONLY` | `OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY` |
+| **SQLite** | `LIMIT 20` | `LIMIT 20 OFFSET 40` |
+| **ALASQL** | `LIMIT 20` | `LIMIT 20 FETCH 40` |
+
+> **Note:** MSSQL's `OFFSET ... FETCH` syntax requires an `ORDER BY` clause.  If you use pagination with MSSQL, be sure to add at least one sort column.
+
+## No Cap, No Pagination
+
+If `setCap()` is not called (or is set to `false`), no pagination clause is generated and all matching rows are returned.

package/docs/query/README.md

@@ -0,0 +1,115 @@
+# Query Building Overview
+
+FoxHound builds queries through a two-phase process: **configure** then **build**.
+
+## The Query Lifecycle
+
+```
+Configure  ──►  Build  ──►  Access Results
+```
+
+1. **Configure** — set the scope, fields, filters, sorts, joins, pagination, records, and dialect
+2. **Build** — call one of the `build*Query()` methods to generate the SQL
+3. **Access** — read `query.body` for the SQL string and `query.parameters` for bound values
+
+## Creating a Query Instance
+
+```javascript
+var libFoxHound = require('foxhound');
+var tmpQuery = libFoxHound.new(_Fable);
+```
+
+Or, when working through Meadow, the DAL provides a pre-configured query:
+
+```javascript
+var tmpQuery = myMeadow.query;
+```
+
+## Setting the Scope
+
+The scope is the primary table (or collection) the query targets:
+
+```javascript
+tmpQuery.setScope('Books');
+```
+
+## Setting the Dialect
+
+Before building, select which SQL dialect to produce:
+
+```javascript
+tmpQuery.setDialect('MySQL');   // MySQL
+tmpQuery.setDialect('MSSQL');   // Microsoft SQL Server
+tmpQuery.setDialect('SQLite');  // SQLite
+tmpQuery.setDialect('ALASQL');  // ALASQL (in-memory)
+tmpQuery.setDialect('English'); // Human-readable (default)
+```
+
+If no dialect is set, FoxHound defaults to `English`.
+
+## Build Methods
+
+| Method | Operation | SQL Pattern |
+|--------|-----------|-------------|
+| `buildCreateQuery()` | Insert a record | `INSERT INTO ... VALUES (...)` |
+| `buildReadQuery()` | Select records | `SELECT ... FROM ... WHERE ...` |
+| `buildUpdateQuery()` | Modify a record | `UPDATE ... SET ... WHERE ...` |
+| `buildDeleteQuery()` | Soft- or hard-delete | `UPDATE ... SET Deleted=1` or `DELETE FROM ...` |
+| `buildUndeleteQuery()` | Restore soft-deleted | `UPDATE ... SET Deleted=0` |
+| `buildCountQuery()` | Count matching rows | `SELECT COUNT(*) AS RowCount FROM ...` |
+
+Every build method returns `this` for chaining.
+
+## Reading the Output
+
+After building, the generated query is available on the `query` property:
+
+```javascript
+tmpQuery.setScope('Books')
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Books`.* FROM `Books`;
+
+console.log(tmpQuery.query.parameters);
+// => {} (no filters, so no bound parameters)
+```
+
+## Resetting & Cloning
+
+After a query is built, you can reset the parameters for reuse or clone the query to create a variant:
+
+```javascript
+// Reset to default parameters
+tmpQuery.resetParameters();
+
+// Clone — copies scope, begin, cap, schema, filters, sorts, and dataElements
+var tmpClone = tmpQuery.clone();
+```
+
+## Full Example
+
+```javascript
+var libFable = require('fable');
+var libFoxHound = require('foxhound');
+
+var _Fable = new libFable({});
+var tmpQuery = libFoxHound.new(_Fable);
+
+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 `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' }
+```

package/docs/query/count.md

@@ -0,0 +1,81 @@
+# Count Query
+
+The Count operation generates a `SELECT COUNT(*)` statement to efficiently count matching rows without returning the full result set.
+
+## Basic Usage
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .setDialect('MySQL')
+    .buildCountQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT COUNT(*) AS RowCount FROM `Books`;
+```
+
+## With Filters
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .addFilter('Genre', 'Science Fiction')
+    .setDialect('MySQL')
+    .buildCountQuery();
+
+// => SELECT COUNT(*) AS RowCount FROM `Books`
+//    WHERE `Books`.`Genre` = :Genre_w0;
+```
+
+## DISTINCT Count
+
+When `setDistinct(true)` is used, the count query counts only unique combinations of the selected fields:
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .setDataElements(['Author'])
+    .setDistinct(true)
+    .setDialect('MySQL')
+    .buildCountQuery();
+
+// => SELECT COUNT(DISTINCT `Author`) AS RowCount FROM `Books`;
+```
+
+If no fields or schema are available when distinct is requested, FoxHound falls back to a standard `COUNT(*)`.
+
+## With Joins
+
+Count queries support joins, so you can count records across related tables:
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .addJoin('Authors', 'Authors.IDAuthor', 'Books.IDAuthor')
+    .addFilter('Authors.Country', 'USA')
+    .setDialect('MySQL')
+    .buildCountQuery();
+
+// => SELECT COUNT(*) AS RowCount FROM `Books`
+//    INNER JOIN Authors ON Authors.IDAuthor = Books.IDAuthor
+//    WHERE Authors.Country = :Country_w0;
+```
+
+## Soft-Delete Awareness
+
+Just like Read queries, Count queries automatically exclude soft-deleted records when a schema with a `Deleted` column is present.
+
+## Query Overrides
+
+Count queries support query overrides with the same template variables as Read queries.  The `OrderBy` and `Limit` variables are always empty strings for count operations.
+
+## Dialect Differences
+
+| Dialect | Count Alias |
+|---------|-------------|
+| MySQL | `RowCount` |
+| MSSQL | `Row_Count` |
+| SQLite | `RowCount` |
+| ALASQL | `RowCount` |
+
+The alias differs for MSSQL because `RowCount` is a reserved keyword in some SQL Server configurations.

package/docs/query/create.md

@@ -0,0 +1,66 @@
+# Create Query
+
+The Create operation generates an `INSERT INTO` statement from a record object.
+
+## Basic Usage
+
+```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 }
+```
+
+## Schema-Aware Behavior
+
+When a schema is attached to the query, FoxHound automatically handles special column types during INSERT:
+
+| Schema Type | Behavior |
+|------------|----------|
+| `AutoIdentity` | Inserts `NULL` (lets the database assign the ID) |
+| `AutoGUID` | Generates a UUID via Fable, unless the record already has a valid GUID |
+| `CreateDate` | Inserts the current timestamp (`NOW(3)` for MySQL, `GETUTCDATE()` for MSSQL) |
+| `CreateIDUser` | Inserts the user ID from `setIDUser()` |
+| `UpdateDate` | Inserts the current timestamp |
+| `UpdateIDUser` | Inserts the user ID |
+| `DeleteDate` | Skipped on insert (when delete tracking is enabled) |
+| `DeleteIDUser` | Skipped on insert (when delete tracking is enabled) |
+| `Deleted` | Included normally (typically defaults to `0`) |
+
+## Setting the User
+
+To stamp which user created the record:
+
+```javascript
+tmpQuery.setIDUser(42);
+```
+
+This value is used for any `CreateIDUser`, `UpdateIDUser`, or `DeleteIDUser` schema columns.
+
+## Disabling Auto-Management
+
+You can disable automatic column management when you need full control:
+
+```javascript
+tmpQuery.setDisableAutoIdentity(true);   // Include identity column value as-is
+tmpQuery.setDisableAutoDateStamp(true);   // Don't auto-generate timestamps
+tmpQuery.setDisableAutoUserStamp(true);   // Don't auto-stamp user IDs
+tmpQuery.setDisableDeleteTracking(true);  // Include delete columns on insert
+```
+
+## Dialect Differences
+
+The INSERT syntax is largely the same across dialects, with a few differences:
+
+- **MySQL** — uses backtick-quoted identifiers and `:name` parameters
+- **MSSQL** — uses bracket-quoted identifiers, `@name` parameters, and skips the AutoIdentity column entirely (rather than inserting NULL)
+- **SQLite** — uses backtick-quoted identifiers and `:name` parameters
+- **ALASQL** — same as SQLite

package/docs/query/delete.md

@@ -0,0 +1,82 @@
+# Delete Query
+
+FoxHound supports two modes of deletion: **soft delete** (the default when a schema has a `Deleted` column) and **hard delete** (a true `DELETE FROM` statement).
+
+## Soft Delete (Default)
+
+When a schema with a `Deleted` column type is present, the delete operation generates an UPDATE that sets the deleted flag:
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .addFilter('IDBook', 42)
+    .setIDUser(5)
+    .setDialect('MySQL')
+    .buildDeleteQuery();
+
+// => UPDATE `Books` SET Deleted = 1, DeleteDate = NOW(3),
+//    UpdateDate = NOW(3), DeleteIDUser = :DeleteIDUser_3
+//    WHERE `Books`.`IDBook` = :IDBook_w0;
+```
+
+The soft delete automatically manages these schema columns:
+
+| Schema Type | Behavior on Delete |
+|------------|-------------------|
+| `Deleted` | Set to `1` |
+| `DeleteDate` | Set to current timestamp |
+| `UpdateDate` | Set to current timestamp (delete is an update) |
+| `DeleteIDUser` | Set to the value from `setIDUser()` |
+
+## Hard Delete
+
+When there is no `Deleted` column in the schema, or when delete tracking is disabled, FoxHound generates a true DELETE:
+
+```javascript
+tmpQuery
+    .setScope('TempRecords')
+    .addFilter('IDTemp', 99)
+    .setDisableDeleteTracking(true)
+    .setDialect('MySQL')
+    .buildDeleteQuery();
+
+// => DELETE FROM `TempRecords` WHERE `TempRecords`.`IDTemp` = :IDTemp_w0;
+```
+
+## Undelete
+
+FoxHound also supports restoring soft-deleted records:
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .addFilter('IDBook', 42)
+    .setIDUser(5)
+    .setDialect('MySQL')
+    .buildUndeleteQuery();
+
+// => UPDATE `Books` SET Deleted = 0, UpdateDate = NOW(3),
+//    UpdateIDUser = :UpdateIDUser_1
+//    WHERE `Books`.`IDBook` = :IDBook_w0;
+```
+
+The undelete operation sets:
+
+| Schema Type | Behavior on Undelete |
+|------------|---------------------|
+| `Deleted` | Set to `0` |
+| `UpdateDate` | Set to current timestamp |
+| `UpdateIDUser` | Set to the value from `setIDUser()` |
+
+If the schema has no `Deleted` column, `buildUndeleteQuery()` produces a no-op (`SELECT NULL;`).
+
+## Dialect Differences
+
+The soft-delete and undelete operations use the same timestamp functions as other operations:
+
+| Dialect | Timestamp Function |
+|---------|-------------------|
+| MySQL | `NOW(3)` |
+| MSSQL | `GETUTCDATE()` |
+| SQLite | `NOW()` (replaced by the provider with `datetime('now')`) |
+| ALASQL | `NOW()` |

package/docs/query/read.md

@@ -0,0 +1,138 @@
+# Read Query
+
+The Read operation generates a `SELECT` statement with support for field selection, filtering, sorting, joins, pagination, and query overrides.
+
+## Basic Usage
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Books`.* FROM `Books`;
+```
+
+## Selecting Specific Columns
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .setDataElements(['Title', 'Author', 'PublishedYear'])
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+// => SELECT `Title`, `Author`, `PublishedYear` FROM `Books`;
+```
+
+You can also use column aliases with array pairs:
+
+```javascript
+tmpQuery.setDataElements([
+    ['Books.Title', 'BookTitle'],
+    ['Books.Author', 'AuthorName']
+]);
+
+// => SELECT `Books`.`Title` AS `BookTitle`, `Books`.`Author` AS `AuthorName` FROM `Books`;
+```
+
+## DISTINCT Results
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .setDataElements(['Genre'])
+    .setDistinct(true)
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+// => SELECT DISTINCT `Genre` FROM `Books`;
+```
+
+## With Filters
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .addFilter('Genre', 'Science Fiction')
+    .addFilter('PublishedYear', 2000, '>')
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+// => SELECT `Books`.* FROM `Books`
+//    WHERE `Books`.`Genre` = :Genre_w0
+//    AND `Books`.`PublishedYear` > :PublishedYear_w1;
+```
+
+See the [Filters](filters.md) page for full filter documentation.
+
+## With Sorting
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .addSort({Column: 'PublishedYear', Direction: 'Descending'})
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+// => SELECT `Books`.* FROM `Books` ORDER BY PublishedYear DESC;
+```
+
+See the [Sorting](sorting.md) page for full sort documentation.
+
+## With Joins
+
+```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;
+```
+
+See the [Joins](joins.md) page for full join documentation.
+
+## With Pagination
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .setBegin(20)
+    .setCap(10)
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+// => SELECT `Books`.* FROM `Books` LIMIT 20, 10;
+```
+
+See the [Pagination](pagination.md) page for dialect-specific pagination details.
+
+## With Index Hints
+
+MySQL and MSSQL support index hints:
+
+```javascript
+tmpQuery.indexHints = ['idx_genre', 'idx_year'];
+
+// MySQL:  SELECT ... FROM `Books` USE INDEX (idx_genre,idx_year) ...
+// MSSQL:  SELECT ... FROM [Books] WITH(INDEX(idx_genre,idx_year)) ...
+```
+
+## Query Overrides
+
+You can supply a custom query template while still benefiting from automatic parameter binding:
+
+```javascript
+tmpQuery.parameters.queryOverride =
+    'SELECT <%= FieldList %> FROM <%= TableName %> <%= Where %> <%= OrderBy %> <%= Limit %>';
+```
+
+See [Query Overrides](query-overrides.md) for details on available template variables.
+
+## Soft-Delete Awareness
+
+When a schema with a `Deleted` column is present and delete tracking is enabled (the default), Read queries automatically add a `WHERE Deleted = 0` filter so that soft-deleted records are excluded.

package/docs/query/update.md

@@ -0,0 +1,56 @@
+# Update Query
+
+The Update operation generates an `UPDATE ... SET ... WHERE ...` statement from a record object and filter criteria.
+
+## Basic Usage
+
+```javascript
+tmpQuery
+    .setScope('Books')
+    .addFilter('IDBook', 42)
+    .addRecord({Title: 'Dune Messiah', PublishedYear: 1969})
+    .setIDUser(5)
+    .setDialect('MySQL')
+    .buildUpdateQuery();
+
+console.log(tmpQuery.query.body);
+// => UPDATE `Books` SET Title = :Title_0, PublishedYear = :PublishedYear_1
+//    WHERE `Books`.`IDBook` = :IDBook_w0;
+
+console.log(tmpQuery.query.parameters);
+// => { Title_0: 'Dune Messiah', PublishedYear_1: 1969, IDBook_w0: 42 }
+```
+
+## Schema-Aware Behavior
+
+When a schema is present, FoxHound manages certain columns automatically:
+
+| Schema Type | Behavior on Update |
+|------------|-------------------|
+| `AutoIdentity` | **Skipped** — never updated |
+| `CreateDate` | **Skipped** — set only on insert |
+| `CreateIDUser` | **Skipped** — set only on insert |
+| `UpdateDate` | Set to current timestamp automatically |
+| `UpdateIDUser` | Set to the value from `setIDUser()` |
+| `DeleteDate` | **Skipped** — managed by delete operations |
+| `DeleteIDUser` | **Skipped** — managed by delete operations |
+
+## Disabling Auto-Management
+
+```javascript
+tmpQuery.setDisableAutoDateStamp(true);   // Don't auto-set UpdateDate
+tmpQuery.setDisableAutoUserStamp(true);   // Don't auto-set UpdateIDUser
+```
+
+## Important Notes
+
+- The record passed to `addRecord()` should contain only the columns you want to change — FoxHound generates SET clauses for each key in the record object
+- Always include a filter (usually on the primary key) to avoid updating all rows
+- If the record object is empty or no records have been added, `buildUpdateQuery()` returns `false` for the query body
+
+## Dialect Differences
+
+- **MySQL** — backtick-quoted identifiers, `:name` parameters
+- **MSSQL** — bracket-quoted identifiers, `@name` parameters; special handling for `UpdateDate` with `disableAutoDateStamp`
+- **SQLite** — backtick-quoted identifiers, `:name` parameters
+- **ALASQL** — same as SQLite