foxhound 2.0.19 → 2.0.21

package/docs/api/addSort.md

@@ -0,0 +1,109 @@
+# addSort / setSort
+
+Add or replace sort expressions for the ORDER BY clause.
+
+## addSort
+
+Add a single sort expression to the existing sort array.
+
+### Signature
+
+```javascript
+tmpQuery.addSort(pSort)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pSort` | String or Object | Column name (ascending by default) or sort object |
+
+### Returns
+
+Returns `this` for chaining.
+
+### Examples
+
+#### Sort ascending by column name
+
+```javascript
+tmpQuery.addSort('PublishedYear');
+// ORDER BY PublishedYear
+```
+
+#### Sort descending
+
+```javascript
+tmpQuery.addSort({Column: 'PublishedYear', Direction: 'Descending'});
+// ORDER BY PublishedYear DESC
+```
+
+#### Multiple sort columns
+
+```javascript
+tmpQuery
+	.addSort({Column: 'Genre', Direction: 'Ascending'})
+	.addSort({Column: 'PublishedYear', Direction: 'Descending'});
+// ORDER BY Genre, PublishedYear DESC
+```
+
+## setSort
+
+Replace the entire sort array.
+
+### Signature
+
+```javascript
+tmpQuery.setSort(pSort)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pSort` | String, Object, or Array | Sort expression(s) |
+
+### Examples
+
+#### Single string
+
+```javascript
+tmpQuery.setSort('Title');
+// ORDER BY Title
+```
+
+#### Single object
+
+```javascript
+tmpQuery.setSort({Column: 'Title', Direction: 'Descending'});
+// ORDER BY Title DESC
+```
+
+#### Array of sort expressions
+
+```javascript
+tmpQuery.setSort([
+	{Column: 'Genre', Direction: 'Ascending'},
+	{Column: 'Title', Direction: 'Ascending'}
+]);
+// ORDER BY Genre, Title
+```
+
+## Sort Object Structure
+
+| Property | Type | Values | Description |
+|----------|------|--------|-------------|
+| `Column` | String | Any column name | Column to sort by |
+| `Direction` | String | `'Ascending'` or `'Descending'` | Sort direction (default: Ascending) |
+
+## Dialect Quoting
+
+Each dialect quotes the column name in ORDER BY according to its conventions:
+
+```javascript
+tmpQuery.addSort('PublishedYear');
+
+// MySQL:      ORDER BY PublishedYear
+// PostgreSQL: ORDER BY "PublishedYear"
+// MSSQL:      ORDER BY [PublishedYear]
+```

package/docs/api/behaviorFlags.md

@@ -0,0 +1,123 @@
+# Behavior Flags
+
+Control how FoxHound handles automatic column management.
+
+## Methods
+
+All behavior flag methods accept a boolean and return `this` for chaining.
+
+### setDisableAutoIdentity(pFlag)
+
+Disable automatic identity column handling on INSERT.
+
+```javascript
+tmpQuery.setDisableAutoIdentity(true);
+```
+
+When **false** (default): AutoIdentity columns insert `NULL` (MySQL/SQLite), `DEFAULT` (PostgreSQL), or are omitted (MSSQL), letting the database assign the ID.
+
+When **true**: The identity column value from the record is used as-is.
+
+```javascript
+// Force a specific ID value
+tmpQuery
+	.setDisableAutoIdentity(true)
+	.addRecord({IDBook: 999, Title: 'Custom ID Book'});
+
+tmpQuery.query.schema = [{Column: 'IDBook', Type: 'AutoIdentity'}, ...];
+tmpQuery.setDialect('MySQL').buildCreateQuery();
+
+// IDBook uses the provided value 999 instead of NULL
+```
+
+### setDisableAutoDateStamp(pFlag)
+
+Disable automatic timestamp generation.
+
+```javascript
+tmpQuery.setDisableAutoDateStamp(true);
+```
+
+When **false** (default): `CreateDate`, `UpdateDate`, and `DeleteDate` columns are automatically set to the current timestamp.
+
+When **true**: These columns use the value from the record object instead.
+
+```javascript
+// Set a custom date
+tmpQuery
+	.setDisableAutoDateStamp(true)
+	.addRecord({Title: 'Imported Book', CreateDate: '2020-01-15'});
+
+// CreateDate uses '2020-01-15' instead of NOW()
+```
+
+### setDisableAutoUserStamp(pFlag)
+
+Disable automatic user ID stamping.
+
+```javascript
+tmpQuery.setDisableAutoUserStamp(true);
+```
+
+When **false** (default): `CreateIDUser`, `UpdateIDUser`, and `DeleteIDUser` columns are set to the value from `setIDUser()`.
+
+When **true**: These columns use the value from the record object instead.
+
+### setDisableDeleteTracking(pFlag)
+
+Disable soft-delete behavior.
+
+```javascript
+tmpQuery.setDisableDeleteTracking(true);
+```
+
+When **false** (default):
+- `DELETE` generates an UPDATE that sets `Deleted = 1`
+- `DeleteDate` and `DeleteIDUser` columns are excluded from INSERT
+- Read and Count queries automatically add `WHERE Deleted = 0`
+
+When **true**:
+- `DELETE` generates a true `DELETE FROM` statement
+- `DeleteDate` and `DeleteIDUser` columns are included in INSERT
+- No automatic `Deleted` filter on Read/Count queries
+
+```javascript
+// Hard delete instead of soft delete
+tmpQuery
+	.setScope('TempRecords')
+	.addFilter('IDTemp', 99)
+	.setDisableDeleteTracking(true)
+	.setDialect('MySQL')
+	.buildDeleteQuery();
+
+// => DELETE FROM `TempRecords` WHERE IDTemp = :IDTemp_w0;
+```
+
+### setLogLevel(pLogLevel)
+
+Set query logging verbosity.
+
+```javascript
+tmpQuery.setLogLevel(3);
+```
+
+| Level | Behavior |
+|-------|----------|
+| `0` | No logging (default) |
+| `1` | Log generated queries |
+| `2` | Log queries and non-parameterized versions |
+| `3+` | Log everything including configuration steps |
+
+## Combining Flags
+
+Flags can be combined as needed:
+
+```javascript
+tmpQuery
+	.setDisableAutoIdentity(true)
+	.setDisableAutoDateStamp(true)
+	.setDisableAutoUserStamp(true)
+	.setDisableDeleteTracking(true);
+```
+
+This gives you full manual control over all column values — useful for data migration or import scenarios.

package/docs/api/buildQuery.md

@@ -0,0 +1,146 @@
+# Build Methods
+
+Generate SQL from the current query configuration.
+
+## 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 ...` |
+
+All build methods return `this` for chaining.
+
+## Accessing Results
+
+After calling a build method, the generated SQL and bound parameters are available on the `query` property:
+
+```javascript
+tmpQuery.buildReadQuery();
+
+console.log(tmpQuery.query.body);       // SQL string
+console.log(tmpQuery.query.parameters); // Bound parameter values
+```
+
+## buildCreateQuery
+
+Generate an INSERT statement.  Requires at least one record via `addRecord()`.
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('PostgreSQL')
+	.setScope('Books')
+	.addRecord({Title: 'Dune', Author: 'Frank Herbert'})
+	.buildCreateQuery();
+
+console.log(tmpQuery.query.body);
+// => INSERT INTO "Books" ( "Title", "Author")
+//    VALUES ( :Title_0, :Author_1) RETURNING *;
+```
+
+Returns `false` for `query.body` if no records are provided or the record is empty.
+
+## buildReadQuery
+
+Generate a SELECT statement.  Uses all configured filters, sorts, joins, and pagination.
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.setDataElements(['Title', 'Author'])
+	.addFilter('Genre', 'Fantasy')
+	.addSort('Title')
+	.setCap(25)
+	.buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Title`, `Author` FROM `Books`
+//    WHERE `Books`.`Genre` = :Genre_w0
+//    ORDER BY Title LIMIT 25;
+```
+
+## buildUpdateQuery
+
+Generate an UPDATE ... SET statement.  Requires at least one record and typically a filter for the WHERE clause.
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addFilter('IDBook', 42)
+	.addRecord({Title: 'Dune Messiah'})
+	.buildUpdateQuery();
+
+console.log(tmpQuery.query.body);
+// => UPDATE `Books` SET Title = :Title_0 WHERE IDBook = :IDBook_w0;
+```
+
+Returns `false` for `query.body` if no records are provided.
+
+## buildDeleteQuery
+
+Generate a soft-delete UPDATE or a hard DELETE.
+
+When a schema has a `Deleted` column type and delete tracking is enabled:
+
+```javascript
+// Soft delete — generates an UPDATE
+tmpQuery.buildDeleteQuery();
+// => UPDATE `Books` SET Deleted = 1, DeleteDate = NOW(3), ...
+```
+
+When no schema or delete tracking is disabled:
+
+```javascript
+// Hard delete — generates a DELETE
+tmpQuery.setDisableDeleteTracking(true).buildDeleteQuery();
+// => DELETE FROM `Books` WHERE IDBook = :IDBook_w0;
+```
+
+## buildUndeleteQuery
+
+Restore soft-deleted records by setting `Deleted = 0`.
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addFilter('IDBook', 42)
+	.setIDUser(5);
+
+tmpQuery.query.schema = _BookSchema;
+tmpQuery.buildUndeleteQuery();
+
+// => UPDATE `Books` SET Deleted = 0, UpdateDate = NOW(3),
+//    UpdateIDUser = :UpdateIDUser_1 WHERE IDBook = :IDBook_w0;
+```
+
+Returns `SELECT NULL;` if no Deleted column exists in the schema.
+
+## buildCountQuery
+
+Generate a SELECT COUNT(*) statement.
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addFilter('Genre', 'Fantasy')
+	.buildCountQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT COUNT(*) AS RowCount FROM `Books`
+//    WHERE `Books`.`Genre` = :Genre_w0;
+```
+
+With DISTINCT:
+
+```javascript
+tmpQuery.setDistinct(true).setDataElements(['Author']).buildCountQuery();
+// => SELECT COUNT(DISTINCT `Author`) AS RowCount FROM `Books` ...;
+```

package/docs/api/clone.md

@@ -0,0 +1,115 @@
+# clone / resetParameters / mergeParameters
+
+Utility methods for managing query state.
+
+## clone
+
+Create an independent copy of the current query.
+
+### Signature
+
+```javascript
+var tmpClone = tmpQuery.clone();
+```
+
+### Returns
+
+Returns a new FoxHound query instance with copies of the current scope, begin, cap, schema, dataElements, sorts, and filters.
+
+### Description
+
+Cloning is useful when you need to build multiple similar queries from the same base configuration.  The cloned query has its own independent state — changes to the clone do not affect the original.
+
+### Example
+
+```javascript
+var tmpBase = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addFilter('Genre', 'Fantasy');
+
+// Clone and customize for a read
+var tmpRead = tmpBase.clone();
+tmpRead.setCap(10).buildReadQuery();
+
+// Clone and customize for a count
+var tmpCount = tmpBase.clone();
+tmpCount.buildCountQuery();
+
+console.log(tmpRead.query.body);
+// => SELECT `Books`.* FROM `Books` WHERE ... LIMIT 10;
+
+console.log(tmpCount.query.body);
+// => SELECT COUNT(*) AS RowCount FROM `Books` WHERE ...;
+```
+
+## resetParameters
+
+Reset the query to its default state.
+
+### Signature
+
+```javascript
+tmpQuery.resetParameters()
+```
+
+### Returns
+
+Returns `this` for chaining.
+
+### Description
+
+Re-initializes all parameters (scope, filters, sorts, joins, cap, begin, records, etc.) to their default values.  This is useful for reusing a query object for a new query.
+
+### Example
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.addFilter('Genre', 'Fantasy')
+	.buildReadQuery();
+
+// Reset and build a new query
+tmpQuery.resetParameters();
+tmpQuery
+	.setScope('Authors')
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Authors`.* FROM `Authors`;
+```
+
+## mergeParameters
+
+Merge an object of parameters into the current state.
+
+### Signature
+
+```javascript
+tmpQuery.mergeParameters(pFromParameters)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFromParameters` | Object | Object with parameter values to merge |
+
+### Returns
+
+Returns `this` for chaining.
+
+### Description
+
+Performs a shallow merge of the provided object into the current parameters.  This is useful for applying a set of parameter overrides at once.
+
+### Example
+
+```javascript
+tmpQuery.mergeParameters({
+	cap: 50,
+	begin: 0,
+	scope: 'Books'
+});
+```

package/docs/api/queryOverrides.md

@@ -0,0 +1,82 @@
+# Query Overrides
+
+Supply custom SQL templates for Read and Count queries while retaining automatic parameter binding.
+
+## Setting a Query Override
+
+```javascript
+tmpQuery.parameters.queryOverride =
+	'SELECT <%= FieldList %> FROM <%= TableName %> <%= Where %> GROUP BY Genre <%= 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 %>');
+```
+
+## How It Works
+
+A query override is an underscore-style template string.  FoxHound generates the individual clauses (field list, WHERE, JOINs, etc.) and then passes them into your template as variables.
+
+## Template Variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `<%= FieldList %>` | String | Comma-separated field list (with dialect-specific quoting) |
+| `<%= TableName %>` | String | Quoted table name |
+| `<%= Where %>` | String | Full WHERE clause including the keyword, or empty string |
+| `<%= Join %>` | String | All JOIN clauses, or empty string |
+| `<%= OrderBy %>` | String | ORDER BY clause including the keyword, or empty string |
+| `<%= Limit %>` | String | Pagination clause (dialect-specific), or empty string |
+| `<%= IndexHints %>` | String | Index hint clause (MySQL/MSSQL), or empty string |
+| `<%= Distinct %>` | String | The `DISTINCT` keyword if set, or empty string |
+| `<%= _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 the full parameters object
+
+```javascript
+tmpQuery.parameters.queryOverride =
+	'SELECT * FROM <%= TableName %> WHERE IDBook > <%= _Params.begin %>';
+```
+
+## Scope
+
+Query overrides apply to **Read** and **Count** operations only.  Create, Update, Delete, and Undelete always use the standard generation path.
+
+## Error Handling
+
+If a query override template fails to compile or execute, FoxHound catches the error, logs it, and returns `false` for the query body.
+
+## When to Use
+
+- `GROUP BY` clauses
+- Subqueries
+- Custom aggregations (`SUM`, `AVG`, `MAX`, `MIN`)
+- `HAVING` clauses
+- `UNION` queries
+- Any SQL feature not directly supported by the fluent API

package/docs/api/setCap.md

@@ -0,0 +1,115 @@
+# setCap / setBegin
+
+Set pagination limits and offsets.
+
+## setCap
+
+Set the maximum number of rows to return (LIMIT).
+
+### Signature
+
+```javascript
+tmpQuery.setCap(pCapAmount)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pCapAmount` | Integer or false | Maximum row count (must be >= 0), or `false` to remove |
+
+### Returns
+
+Returns `this` for chaining.
+
+### Examples
+
+```javascript
+// Return at most 50 rows
+tmpQuery.setCap(50);
+
+// Remove the cap (return all rows)
+tmpQuery.setCap(false);
+```
+
+## setBegin
+
+Set the zero-based starting offset (OFFSET / SKIP).
+
+### Signature
+
+```javascript
+tmpQuery.setBegin(pBeginAmount)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pBeginAmount` | Integer or false | Zero-based row offset (must be >= 0), or `false` to remove |
+
+### Returns
+
+Returns `this` for chaining.
+
+### Examples
+
+```javascript
+// Start at the 101st record
+tmpQuery.setBegin(100);
+
+// Remove the offset
+tmpQuery.setBegin(false);
+```
+
+## Pagination Examples
+
+### First page
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setCap(20)
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+// MySQL:      SELECT ... LIMIT 20;
+// PostgreSQL: SELECT ... LIMIT 20;
+// MSSQL:      SELECT ... OFFSET 0 ROWS FETCH NEXT 20 ROWS ONLY;
+```
+
+### Second page
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setBegin(20)
+	.setCap(20)
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+// MySQL:      SELECT ... LIMIT 20, 20;
+// PostgreSQL: SELECT ... LIMIT 20 OFFSET 20;
+// MSSQL:      SELECT ... OFFSET 20 ROWS FETCH NEXT 20 ROWS ONLY;
+```
+
+### Page-based helper
+
+```javascript
+var tmpPageSize = 20;
+var tmpPageNumber = 3; // zero-based
+
+tmpQuery
+	.setBegin(tmpPageNumber * tmpPageSize)
+	.setCap(tmpPageSize);
+```
+
+## Dialect Syntax
+
+| Dialect | Cap Only | Cap + Offset |
+|---------|----------|--------------|
+| MySQL | `LIMIT 20` | `LIMIT 40, 20` |
+| PostgreSQL | `LIMIT 20` | `LIMIT 20 OFFSET 40` |
+| 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` |