foxhound 2.0.13 → 2.0.16

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

package/docs/query-overrides.md

@@ -0,0 +1,88 @@
+# Query Overrides
+
+Query overrides let you supply a custom SQL template while still benefiting from FoxHound's automatic parameter binding, filter generation, and schema awareness.
+
+## How It Works
+
+A query override is an [underscore-style template](https://underscorejs.org/#template) string.  FoxHound generates the individual clauses (field list, where, joins, etc.) and then passes them into your template.
+
+## Setting a Query Override
+
+```javascript
+tmpQuery.parameters.queryOverride =
+    'SELECT <%= FieldList %> FROM <%= TableName %> <%= Join %> <%= Where %> <%= OrderBy %> <%= Limit %>';
+```
+
+Or via Meadow's raw query system:
+
+```javascript
+myMeadow.rawQueries.setQuery('Read',
+    'SELECT <%= FieldList %> FROM <%= TableName %> <%= Join %> <%= Where %> GROUP BY Genre <%= OrderBy %> <%= Limit %>');
+```
+
+## Available Template Variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `FieldList` | String | Comma-separated field list (e.g. `` `Title`, `Author` ``) |
+| `TableName` | String | Quoted table name (e.g. `` `Books` `` or `[Books]`) |
+| `Where` | String | Full WHERE clause including the keyword (e.g. `WHERE Genre = :Genre_w0`) |
+| `Join` | String | All JOIN clauses (e.g. `INNER JOIN Authors ON ...`) |
+| `OrderBy` | String | ORDER BY clause including the keyword |
+| `Limit` | String | Pagination clause (dialect-specific) |
+| `IndexHints` | String | Index hint clause (MySQL/MSSQL only) |
+| `Distinct` | String | The `DISTINCT` keyword if set, otherwise empty |
+| `_Params` | Object | The full Parameters object for advanced access |
+
+## Examples
+
+### GROUP BY
+
+```javascript
+tmpQuery.parameters.queryOverride =
+    'SELECT Genre, COUNT(*) as BookCount FROM <%= TableName %> <%= Where %> GROUP BY Genre <%= OrderBy %>';
+```
+
+### Subquery
+
+```javascript
+tmpQuery.parameters.queryOverride =
+    'SELECT <%= FieldList %> FROM <%= TableName %> <%= Where %> AND PublishedYear = (SELECT MAX(PublishedYear) FROM <%= TableName %>)';
+```
+
+### Custom Aggregation
+
+```javascript
+tmpQuery.parameters.queryOverride =
+    'SELECT Author, AVG(Rating) as AvgRating FROM <%= TableName %> <%= Where %> GROUP BY Author HAVING AVG(Rating) > 4.0 <%= OrderBy %>';
+```
+
+### Accessing Parameters
+
+The `_Params` variable gives you access to the full query state:
+
+```javascript
+tmpQuery.parameters.queryOverride =
+    'SELECT * FROM <%= TableName %> WHERE IDBook > <%= _Params.begin %>';
+```
+
+## Override Scope
+
+Query overrides apply to **Read** and **Count** operations only.  Create, Update, Delete, and Undelete operations always use the standard generation path.
+
+## Error Handling
+
+If a query override template fails to compile or execute, FoxHound catches the error, logs it to the console, and returns `false` for the query body.  This prevents template errors from crashing your application.
+
+## When to Use Query Overrides
+
+Query overrides are useful when you need:
+
+- `GROUP BY` clauses
+- Subqueries
+- Custom aggregations (`SUM`, `AVG`, `MAX`, `MIN`)
+- `HAVING` clauses
+- `UNION` queries
+- Any SQL feature not directly supported by FoxHound's fluent API
+
+For straightforward CRUD operations, the standard query builders are preferred — they are safer and more portable across dialects.

package/docs/schema.md

@@ -0,0 +1,93 @@
+# Schema Integration
+
+FoxHound is schema-aware — when a schema array is attached to a query, it uses the column type annotations to automatically manage identity columns, timestamps, user stamps, and soft-delete tracking.
+
+## Attaching a Schema
+
+The schema is set on the `query.schema` property, typically by Meadow before query generation:
+
+```javascript
+tmpQuery.query.schema = [
+    {Column: 'IDBook', Type: 'AutoIdentity'},
+    {Column: 'GUIDBook', Type: 'AutoGUID'},
+    {Column: 'Title', Type: 'String'},
+    {Column: 'Author', Type: 'String'},
+    {Column: 'PublishedYear', Type: 'Integer'},
+    {Column: 'CreateDate', Type: 'CreateDate'},
+    {Column: 'CreatingIDUser', Type: 'CreateIDUser'},
+    {Column: 'UpdateDate', Type: 'UpdateDate'},
+    {Column: 'UpdatingIDUser', Type: 'UpdateIDUser'},
+    {Column: 'Deleted', Type: 'Deleted'},
+    {Column: 'DeleteDate', Type: 'DeleteDate'},
+    {Column: 'DeletingIDUser', Type: 'DeleteIDUser'}
+];
+```
+
+## Schema Column Types
+
+| Type | Purpose | Create | Read | Update | Delete | Undelete |
+|------|---------|--------|------|--------|--------|----------|
+| `AutoIdentity` | Auto-increment primary key | `NULL` (DB assigns) | included | **skipped** | — | — |
+| `AutoGUID` | Auto-generated UUID | UUID or user value | included | included | — | — |
+| `CreateDate` | Row creation timestamp | `NOW()` | included | **skipped** | — | — |
+| `CreateIDUser` | Row creator user ID | `IDUser` | included | **skipped** | — | — |
+| `UpdateDate` | Last modification timestamp | `NOW()` | included | `NOW()` | `NOW()` | `NOW()` |
+| `UpdateIDUser` | Last modifier user ID | `IDUser` | included | `IDUser` | — | `IDUser` |
+| `Deleted` | Soft-delete flag | `0` | auto-filtered | — | set to `1` | set to `0` |
+| `DeleteDate` | Deletion timestamp | **skipped** | included | **skipped** | `NOW()` | — |
+| `DeleteIDUser` | Deleter user ID | **skipped** | included | **skipped** | `IDUser` | — |
+| `String` | Text data | parameterized | included | parameterized | — | — |
+| `Integer` | Numeric data | parameterized | included | parameterized | — | — |
+| `Decimal` | Decimal data | parameterized | included | parameterized | — | — |
+| `Boolean` | Boolean data | parameterized | included | parameterized | — | — |
+| `DateTime` | Date/time data | parameterized | included | parameterized | — | — |
+
+## How Schema Affects Each Operation
+
+### Create (INSERT)
+
+- `AutoIdentity` → inserts `NULL` (MySQL/SQLite) or is omitted (MSSQL)
+- `AutoGUID` → generates a UUID via Fable, unless the record has a valid GUID already
+- `CreateDate`, `UpdateDate` → inserts the current timestamp
+- `CreateIDUser`, `UpdateIDUser` → inserts the user ID from `setIDUser()`
+- `DeleteDate`, `DeleteIDUser` → **skipped** (when delete tracking is enabled)
+
+### Update
+
+- `AutoIdentity`, `CreateDate`, `CreateIDUser`, `DeleteDate`, `DeleteIDUser` → **skipped**
+- `UpdateDate` → set to current timestamp automatically
+- `UpdateIDUser` → set to the value from `setIDUser()`
+- All other columns → parameterized from the record
+
+### Delete (Soft)
+
+Only these columns are modified:
+- `Deleted` → set to `1`
+- `DeleteDate` → set to current timestamp
+- `UpdateDate` → set to current timestamp
+- `DeleteIDUser` → set to the value from `setIDUser()`
+
+### Undelete
+
+Only these columns are modified:
+- `Deleted` → set to `0`
+- `UpdateDate` → set to current timestamp
+- `UpdateIDUser` → set to the value from `setIDUser()`
+
+### Read / Count
+
+- Automatically adds `WHERE Deleted = 0` filter when a `Deleted` column type is in the schema
+- Uses the `AutoIdentity` column for `DISTINCT COUNT` operations when no specific fields are set
+
+## Disabling Auto-Management
+
+| Flag | Effect |
+|------|--------|
+| `setDisableAutoIdentity(true)` | Include identity values as-is (don't insert NULL) |
+| `setDisableAutoDateStamp(true)` | Don't auto-generate timestamps |
+| `setDisableAutoUserStamp(true)` | Don't auto-stamp user IDs |
+| `setDisableDeleteTracking(true)` | Include delete columns on insert; skip soft-delete filter on reads |
+
+## Stricture Integration
+
+Schemas are typically defined using [Stricture](https://github.com/stevenvelozo/stricture), a companion tool that generates schema definitions from a DDL-like JSON format.  Stricture produces the exact schema array format that FoxHound expects.

package/docs/sorting.md

@@ -0,0 +1,80 @@
+# Sorting
+
+FoxHound generates `ORDER BY` clauses from sort expressions.  Sorting applies to Read queries.
+
+## Adding a Sort
+
+The simplest way to add a sort is with `addSort()`:
+
+```javascript
+// Sort ascending by column name (default direction)
+tmpQuery.addSort('PublishedYear');
+
+// ORDER BY PublishedYear
+```
+
+For descending order, pass a sort object:
+
+```javascript
+tmpQuery.addSort({Column: 'PublishedYear', Direction: 'Descending'});
+
+// ORDER BY PublishedYear DESC
+```
+
+## Multiple Sort Columns
+
+Chain multiple `addSort()` calls to sort by several columns:
+
+```javascript
+tmpQuery
+    .addSort({Column: 'Genre', Direction: 'Ascending'})
+    .addSort({Column: 'PublishedYear', Direction: 'Descending'});
+
+// ORDER BY Genre, PublishedYear DESC
+```
+
+Columns without an explicit `Direction` (or with `Direction: 'Ascending'`) sort in ascending order — the SQL default.
+
+## Setting Sorts Directly
+
+For full control, use `setSort()` to replace the entire sort array:
+
+```javascript
+tmpQuery.setSort([
+    {Column: 'Genre', Direction: 'Ascending'},
+    {Column: 'Title', Direction: 'Ascending'}
+]);
+```
+
+You can also pass a single string (defaults to ascending):
+
+```javascript
+tmpQuery.setSort('Title');
+// ORDER BY Title
+```
+
+Or a single sort object:
+
+```javascript
+tmpQuery.setSort({Column: 'Title', Direction: 'Descending'});
+// ORDER BY Title DESC
+```
+
+## Sort Object Structure
+
+| Property | Type | Values | Description |
+|----------|------|--------|-------------|
+| `Column` | String | Any column name | Column to sort by |
+| `Direction` | String | `'Ascending'` or `'Descending'` | Sort direction |
+
+## Dialect Differences
+
+The `ORDER BY` clause syntax is consistent across all SQL dialects.  The main difference is in identifier quoting:
+
+- **MySQL** — `ORDER BY PublishedYear DESC`
+- **MSSQL** — `ORDER BY [PublishedYear] DESC`
+- **SQLite/ALASQL** — `ORDER BY \`PublishedYear\` DESC`
+
+## Interaction with Pagination
+
+In MSSQL, pagination with `OFFSET ... FETCH` requires an `ORDER BY` clause.  If you set a cap without a sort, you may need to add a sort on the primary key to ensure predictable results.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "foxhound",
-    "version": "2.0.13",
+    "version": "2.0.16",
     "description": "A Database Query generation library.",
     "main": "source/FoxHound.js",
     "scripts": {
@@ -47,9 +47,9 @@
     },
     "homepage": "https://github.com/stevenvelozo/foxhound",
     "devDependencies": {
-        "quackage": "^1.0.42"
+        "quackage": "^1.0.50"
     },
     "dependencies": {
-        "fable": "^3.1.18"
+        "fable": "^3.1.53"
     }
 }

package/source/dialects/SQLite/FoxHound-Dialect-SQLite.js

@@ -291,7 +291,7 @@ var FoxHoundDialectSQLite = function(pFable)
 		// If there is a begin record, we'll pass that in as well.
 		if (pParameters.begin !== false)
 		{
-			tmpLimit += ' FETCH ' + pParameters.begin;
+			tmpLimit += ' OFFSET ' + pParameters.begin;
 		}
 
 		return tmpLimit;

package/test/FoxHound-Dialect-SQLite_tests.js

@@ -158,7 +158,7 @@ suite
 						// This is the query generated by the SQLite dialect
 						_Fable.log.trace('Select Query', tmpQuery.query);
 						Expect(tmpQuery.query.body)
-							.to.equal('SELECT `Name`, `Age`, `Cost` FROM Animal WHERE `Age` = :Age_w0 ORDER BY `Age`, `Cost` LIMIT 10 FETCH 0;');
+							.to.equal('SELECT `Name`, `Age`, `Cost` FROM Animal WHERE `Age` = :Age_w0 ORDER BY `Age`, `Cost` LIMIT 10 OFFSET 0;');
 					}
 				);
 				test
@@ -181,7 +181,7 @@ suite
 						// This is the query generated by the SQLite dialect
 						_Fable.log.trace('Select Query', tmpQuery.query);
 						Expect(tmpQuery.query.body)
-							.to.equal('SELECT DISTINCT `Name`, `Age`, `Cost` FROM Animal WHERE `Age` = :Age_w0 ORDER BY `Age`, `Cost` LIMIT 10 FETCH 0;');
+							.to.equal('SELECT DISTINCT `Name`, `Age`, `Cost` FROM Animal WHERE `Age` = :Age_w0 ORDER BY `Age`, `Cost` LIMIT 10 OFFSET 0;');
 					}
 				);
 				test
@@ -229,7 +229,7 @@ suite
 						// This is the query generated by the SQLite dialect
 						_Fable.log.trace('Custom Select Query', tmpQuery.query);
 						Expect(tmpQuery.query.body)
-							.to.equal('SELECT `Name`, `Age` * 5, `Cost` FROM  Animal  WHERE `Age` = :Age_w0  LIMIT 10 FETCH 0;');
+							.to.equal('SELECT `Name`, `Age` * 5, `Cost` FROM  Animal  WHERE `Age` = :Age_w0  LIMIT 10 OFFSET 0;');
 					}
 				);
 				test
@@ -252,7 +252,7 @@ suite
 						// This is the query generated by the SQLite dialect
 						_Fable.log.trace('Custom Select Query', tmpQuery.query);
 						Expect(tmpQuery.query.body)
-							.to.equal('SELECT `Name`, `Age` * 5, `Cost` FROM  Animal  WHERE `Age` = :Age_w0  LIMIT 10 FETCH 0;');
+							.to.equal('SELECT `Name`, `Age` * 5, `Cost` FROM  Animal  WHERE `Age` = :Age_w0  LIMIT 10 OFFSET 0;');
 					}
 				);
 				test

package/test/Foxhound-Dialect-MSSQL_tests.js

@@ -770,7 +770,7 @@ suite
 						// This is the query generated by the MSSQL dialect
 						_Fable.log.trace('Update Query', tmpQuery.query);
 						Expect(tmpQuery.query.body)
-							.to.equal('UPDATE [Animal] SET [GUIDAnimal] = @GUIDAnimal_0, [Name] = @Name_1, [Age] = @Age_2 WHERE [IDAnimal] = @IDAnimal_w0;');
+							.to.equal('UPDATE [Animal] SET [GUIDAnimal] = @GUIDAnimal_0, [UpdateDate] = @MANUAL_UpdateDate, [Name] = @Name_2, [Age] = @Age_3 WHERE [IDAnimal] = @IDAnimal_w0;');
 					}
 				);
 				test