foxhound 2.0.12 → 2.0.15

package/docs/dialects/alasql.md

@@ -0,0 +1,84 @@
+# ALASQL Dialect
+
+The ALASQL dialect generates SQL compatible with [ALASQL](https://github.com/AlaSQL/alasql), a JavaScript SQL database for browser and Node.js that works with in-memory data.
+
+## Overview
+
+ALASQL is ideal for:
+
+- Browser-side data querying
+- In-memory datasets
+- Client-side filtering and aggregation
+- Prototyping without a database server
+
+## Identifier Quoting
+
+ALASQL uses backtick quoting for identifiers (same as SQLite):
+
+```sql
+SELECT * FROM Books WHERE `Genre` = :Genre_w0;
+```
+
+Table names are used as plain identifiers without quoting.
+
+## Named Parameters
+
+The ALASQL dialect uses `:name` syntax for named parameters:
+
+```sql
+SELECT `Title`, `Author` FROM Books WHERE `Genre` = :Genre_w0 ORDER BY `Title`;
+```
+
+## Timestamp Function
+
+The ALASQL dialect generates `NOW()` for timestamp columns.  Depending on your ALASQL configuration, you may need to register a custom `NOW()` function.
+
+## Pagination
+
+ALASQL uses `LIMIT ... FETCH` syntax:
+
+```sql
+-- Cap only
+SELECT * FROM Books LIMIT 20;
+
+-- Cap with offset
+SELECT * FROM Books LIMIT 20 FETCH 40;
+```
+
+> **Note:** The `FETCH` keyword here is ALASQL-specific and represents the starting offset.  This differs from the standard SQL `FETCH NEXT` clause used by MSSQL.
+
+## Joins
+
+Like SQLite, the ALASQL dialect does not include built-in join generation.  For queries that require joins, use a [query override](query-overrides.md).
+
+## Similarities to SQLite
+
+The ALASQL dialect shares most of its implementation with the SQLite dialect:
+
+- Same identifier quoting (backticks)
+- Same parameter syntax (`:name`)
+- Same column escaping logic
+- Same schema-aware column handling
+- Same soft-delete behavior
+
+The primary differences are:
+
+| Feature | SQLite | ALASQL |
+|---------|--------|--------|
+| Pagination | `LIMIT n OFFSET m` | `LIMIT n FETCH m` |
+| Runtime | Native C library via better-sqlite3 | Pure JavaScript |
+| Use case | Embedded/file databases | In-memory/browser |
+
+## Query Overrides
+
+The ALASQL dialect supports the same template variables as SQLite:
+
+| Variable | Description |
+|----------|-------------|
+| `<%= FieldList %>` | Generated column list |
+| `<%= TableName %>` | Table name |
+| `<%= Where %>` | WHERE clause |
+| `<%= OrderBy %>` | ORDER BY clause |
+| `<%= Limit %>` | LIMIT/FETCH clause |
+| `<%= Distinct %>` | DISTINCT keyword (if set) |
+| `<%= _Params %>` | Full parameters object |

package/docs/dialects/mssql.md

@@ -0,0 +1,95 @@
+# MSSQL Dialect
+
+The MSSQL dialect generates SQL compatible with Microsoft SQL Server.
+
+## Identifier Quoting
+
+MSSQL uses square bracket quoting for identifiers:
+
+```sql
+SELECT [Books].* FROM [Books] WHERE [Genre] = @Genre_w0;
+```
+
+## Named Parameters
+
+The MSSQL dialect uses `@name` syntax for named parameters:
+
+```sql
+INSERT INTO [Books] ( [Title], [Author]) VALUES ( @Title_0, @Author_1);
+```
+
+## Parameter Types
+
+MSSQL requires typed parameters for prepared statements.  FoxHound automatically generates type information in `query.parameterTypes` based on the schema:
+
+| Schema Type | MSSQL Parameter Type |
+|------------|---------------------|
+| `AutoIdentity`, `CreateIDUser`, `UpdateIDUser`, `DeleteIDUser`, `Integer` | `Int` |
+| `Deleted`, `Boolean` | `TinyInt` |
+| `Decimal` | `Decimal` |
+| `String`, `AutoGUID` | `VarChar` |
+| `CreateDate`, `UpdateDate`, `DeleteDate`, `DateTime` | `DateTime` |
+
+## Timestamp Function
+
+MSSQL uses `GETUTCDATE()` for timestamp generation, providing UTC timestamps for consistency across time zones.
+
+## Pagination
+
+MSSQL uses `OFFSET ... FETCH` syntax (requires an `ORDER BY` clause):
+
+```sql
+-- Cap only
+SELECT * FROM [Books] ORDER BY [IDBook] OFFSET 0 ROWS FETCH NEXT 20 ROWS ONLY;
+
+-- Cap with offset
+SELECT * FROM [Books] ORDER BY [IDBook] OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY;
+```
+
+> **Important:** You must include at least one sort column when using pagination with MSSQL, as the `OFFSET ... FETCH` clause requires an `ORDER BY`.
+
+## Index Hints
+
+The MSSQL dialect supports `WITH(INDEX(...))` hints:
+
+```javascript
+tmpQuery.indexHints = ['IX_Genre'];
+```
+
+```sql
+SELECT [Books].* FROM [Books] WITH(INDEX(IX_Genre)) WHERE ...;
+```
+
+## Joins
+
+```sql
+INNER JOIN [Authors] ON Authors.IDAuthor = Books.IDAuthor
+```
+
+## AutoIdentity on INSERT
+
+Unlike MySQL, the MSSQL dialect omits the `AutoIdentity` column entirely from INSERT statements (rather than inserting NULL).  This avoids errors with SQL Server's identity column behavior.
+
+## Count Alias
+
+The MSSQL dialect uses `Row_Count` instead of `RowCount` as the count alias, because `RowCount` can conflict with SQL Server reserved keywords:
+
+```sql
+SELECT COUNT(*) AS Row_Count FROM [Books];
+```
+
+## Query Overrides
+
+The MSSQL dialect supports the same template variables as MySQL:
+
+| Variable | Description |
+|----------|-------------|
+| `<%= FieldList %>` | Generated column list |
+| `<%= TableName %>` | Table name with bracket quoting |
+| `<%= Where %>` | WHERE clause |
+| `<%= Join %>` | JOIN clauses |
+| `<%= OrderBy %>` | ORDER BY clause |
+| `<%= Limit %>` | OFFSET/FETCH clause |
+| `<%= IndexHints %>` | WITH(INDEX(...)) clause |
+| `<%= Distinct %>` | DISTINCT keyword (if set) |
+| `<%= _Params %>` | Full parameters object |

package/docs/dialects/mysql.md

@@ -0,0 +1,99 @@
+# MySQL Dialect
+
+The MySQL dialect generates SQL compatible with MySQL and MariaDB.
+
+## Identifier Quoting
+
+MySQL uses backtick quoting for identifiers:
+
+```sql
+SELECT `Books`.* FROM `Books` WHERE `Books`.`Genre` = :Genre_w0;
+```
+
+FoxHound properly handles table-qualified field names, quoting each segment separately:
+
+```sql
+`Books`.`Title`
+```
+
+## Named Parameters
+
+The MySQL dialect uses `:name` syntax for named parameters:
+
+```sql
+INSERT INTO `Books` ( Title, Author) VALUES ( :Title_0, :Author_1);
+```
+
+The bound values are stored in `query.parameters` as a plain object:
+
+```javascript
+{ Title_0: 'Dune', Author_1: 'Frank Herbert' }
+```
+
+## Timestamp Function
+
+MySQL uses `NOW(3)` to capture the current timestamp with millisecond precision.  This is used for `CreateDate`, `UpdateDate`, `DeleteDate`, and related schema types.
+
+## Pagination
+
+MySQL uses `LIMIT` syntax:
+
+```sql
+-- Cap only
+SELECT * FROM `Books` LIMIT 20;
+
+-- Cap with offset
+SELECT * FROM `Books` LIMIT 40, 20;
+```
+
+## Index Hints
+
+The MySQL dialect supports `USE INDEX` hints:
+
+```javascript
+tmpQuery.indexHints = ['idx_genre'];
+```
+
+```sql
+SELECT `Books`.* FROM `Books` USE INDEX (idx_genre) WHERE ...;
+```
+
+## Joins
+
+```sql
+INNER JOIN Authors ON Authors.IDAuthor = Books.IDAuthor
+LEFT JOIN Publishers ON Publishers.IDPublisher = Books.IDPublisher
+```
+
+## DISTINCT
+
+```sql
+SELECT DISTINCT `Genre` FROM `Books`;
+SELECT COUNT(DISTINCT `Books`.`IDBook`) AS RowCount FROM `Books`;
+```
+
+## Soft Delete
+
+When a schema has a `Deleted` column type, the Delete operation generates an UPDATE:
+
+```sql
+UPDATE `Books` SET Deleted = 1, DeleteDate = NOW(3),
+  UpdateDate = NOW(3), DeleteIDUser = :DeleteIDUser_3
+  WHERE `Books`.`IDBook` = :IDBook_w0;
+```
+
+## Query Overrides
+
+The MySQL dialect supports underscore-style templates for Read and Count queries.  The available template variables are:
+
+| Variable | Description |
+|----------|-------------|
+| `<%= FieldList %>` | Generated column list |
+| `<%= TableName %>` | Table name with backtick quoting |
+| `<%= Where %>` | WHERE clause (including the keyword) |
+| `<%= Join %>` | JOIN clauses |
+| `<%= OrderBy %>` | ORDER BY clause |
+| `<%= Limit %>` | LIMIT clause |
+| `<%= IndexHints %>` | USE INDEX clause |
+| `<%= Distinct %>` | DISTINCT keyword (if set) |
+| `<%= _Params %>` | Full parameters object |

package/docs/dialects/sqlite.md

@@ -0,0 +1,82 @@
+# SQLite Dialect
+
+The SQLite dialect generates SQL compatible with SQLite 3.  It is used together with the Meadow SQLite provider (which uses the `better-sqlite3` driver).
+
+## Identifier Quoting
+
+SQLite uses backtick quoting for identifiers to avoid conflicts with SQLite's many reserved keywords:
+
+```sql
+SELECT * FROM Books WHERE `Genre` = :Genre_w0;
+```
+
+Table names are not quoted in the SQLite dialect — they are used as plain identifiers.
+
+## Named Parameters
+
+The SQLite dialect uses `:name` syntax for named parameters, which `better-sqlite3` supports natively:
+
+```sql
+INSERT INTO Books ( `IDBook`, `Title`, `Author`) VALUES ( NULL, :Title_1, :Author_2);
+```
+
+## Timestamp Function
+
+The SQLite dialect generates `NOW()` in its SQL output.  Because SQLite does not have a `NOW()` function, the Meadow SQLite provider replaces this at execution time with `datetime('now')`.
+
+## Pagination
+
+SQLite uses `LIMIT ... OFFSET` syntax:
+
+```sql
+-- Cap only
+SELECT * FROM Books LIMIT 20;
+
+-- Cap with offset
+SELECT * FROM Books LIMIT 20 OFFSET 40;
+```
+
+## Joins
+
+The SQLite dialect generates Read queries without join support in the standard code path.  For queries that require joins, use a [query override](query-overrides.md).
+
+## DISTINCT
+
+```sql
+SELECT DISTINCT `Genre` FROM Books;
+SELECT COUNT(DISTINCT IDBook) AS RowCount FROM Books;
+```
+
+## Soft Delete
+
+Works the same as other dialects — when a `Deleted` column is present in the schema, Delete generates an UPDATE:
+
+```sql
+UPDATE Books SET `Deleted` = 1, `DeleteDate` = NOW(),
+  `UpdateDate` = NOW(), `DeleteIDUser` = :DeleteIDUser_3
+  WHERE `IDBook` = :IDBook_w0;
+```
+
+The `NOW()` calls are replaced with `datetime('now')` by the Meadow SQLite provider before execution.
+
+## Provider Considerations
+
+When using the Meadow SQLite provider with `better-sqlite3`:
+
+- **Boolean coercion** — `better-sqlite3` only accepts numbers, strings, bigints, buffers, and null. The provider automatically converts boolean values (`true`/`false`) to integers (`1`/`0`)
+- **Undefined coercion** — undefined values are converted to `null`
+- **Synchronous execution** — `better-sqlite3` is synchronous, but the Meadow provider wraps calls in an async-compatible callback pattern
+
+## Query Overrides
+
+The SQLite dialect supports underscore-style templates for Read and Count queries:
+
+| Variable | Description |
+|----------|-------------|
+| `<%= FieldList %>` | Generated column list |
+| `<%= TableName %>` | Table name |
+| `<%= Where %>` | WHERE clause |
+| `<%= OrderBy %>` | ORDER BY clause |
+| `<%= Limit %>` | LIMIT/OFFSET clause |
+| `<%= Distinct %>` | DISTINCT keyword (if set) |
+| `<%= _Params %>` | Full parameters object |

package/docs/filters.md

@@ -0,0 +1,171 @@
+# Filters
+
+Filters are the WHERE clause of your query.  FoxHound supports a rich set of comparison operators, logical connectors, and grouping expressions.
+
+## Adding a Filter
+
+The simplest way to add a filter is with `addFilter()`:
+
+```javascript
+tmpQuery.addFilter('Genre', 'Science Fiction');
+// WHERE Genre = :Genre_w0
+```
+
+The full signature is:
+
+```javascript
+addFilter(pColumn, pValue, pOperator, pConnector, pParameter)
+```
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `pColumn` | *(required)* | Column name |
+| `pValue` | *(required)* | Value to compare against |
+| `pOperator` | `'='` | Comparison operator |
+| `pConnector` | `'AND'` | Logical connector to the previous filter |
+| `pParameter` | `pColumn` | Parameter name (auto-generated, usually leave as default) |
+
+## Comparison 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 a set |
+| `'NOT IN'` | `NOT IN (...)` | Value not in a set |
+| `'IS NULL'` | `IS NULL` | Null check (no value needed) |
+| `'IS NOT NULL'` | `IS NOT NULL` | Not-null check (no value needed) |
+
+## Logical Connectors
+
+| Connector | Description |
+|-----------|-------------|
+| `'AND'` | Both conditions must be true (default) |
+| `'OR'` | Either condition may be true |
+| `'NONE'` | No connector (used internally) |
+
+## Examples
+
+### Multiple Filters
+
+```javascript
+tmpQuery
+    .addFilter('Genre', 'Science Fiction')
+    .addFilter('PublishedYear', 2000, '>');
+
+// WHERE Genre = :Genre_w0 AND PublishedYear > :PublishedYear_w1
+```
+
+### 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('Status', 'Active,Pending', 'IN');
+
+// WHERE Status IN ( :Status_w0 )
+```
+
+### IS NULL / IS NOT NULL
+
+```javascript
+tmpQuery.addFilter('DeleteDate', '', 'IS NULL');
+tmpQuery.addFilter('Title', '', 'IS NOT NULL');
+
+// WHERE DeleteDate IS NULL AND Title IS NOT NULL
+```
+
+### Grouped Conditions (Parentheses)
+
+Use the `(` and `)` operators to create logical groups:
+
+```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
+```
+
+## Setting Filters Directly
+
+For full control, you can set the entire filter array at once with `setFilter()`:
+
+```javascript
+tmpQuery.setFilter([
+    {Column: 'Genre', Operator: '=', Value: 'Science Fiction', Connector: 'AND', Parameter: 'Genre'},
+    {Column: 'PublishedYear', Operator: '>', Value: 2000, Connector: 'AND', Parameter: 'PublishedYear'}
+]);
+```
+
+## Filter Object Structure
+
+Each filter in the array is an object with these properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Column` | String | The column to filter on |
+| `Operator` | String | Comparison operator |
+| `Value` | Any | The value to compare against |
+| `Connector` | String | Logical connector (`AND`, `OR`, `NONE`) |
+| `Parameter` | String | Named parameter key |
+
+## URL Serialization Format
+
+When filters are passed through URL query strings (as in Meadow endpoints), they use a serialized format:
+
+```
+FBV~Genre~EQ~Science Fiction~FBV~PublishedYear~GT~2000
+```
+
+The instruction types are:
+
+| Code | Meaning |
+|------|---------|
+| `FBV` | Filter By Value |
+| `FBL` | Filter By List (comma-separated values) |
+| `FOP` | Filter Open Parenthesis |
+| `FCP` | Filter Close Parenthesis |
+| `FSF` | Filter Sort Field |
+| `FCC` | Filter Constraint Cap |
+| `FCB` | Filter Constraint Begin |
+
+The operator codes are:
+
+| Code | Operator |
+|------|----------|
+| `EQ` | `=` |
+| `NE` | `!=` |
+| `GT` | `>` |
+| `GE` | `>=` |
+| `LT` | `<` |
+| `LE` | `<=` |
+| `LK` | `LIKE` |
+
+## Soft-Delete Auto-Filter
+
+When a schema with a `Deleted` column type is present and delete tracking is not disabled, FoxHound automatically appends a `WHERE Deleted = 0` filter to all Read and Count queries.  If you explicitly add a filter on the `Deleted` column, the automatic filter is suppressed.

package/docs/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="Documentation powered by pict-docuserve">
+
+		<title>Documentation</title>
+
+		<!-- Application Stylesheet -->
+		<link href="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/css/docuserve.css" rel="stylesheet">
+		<!-- KaTeX stylesheet for LaTeX equation rendering -->
+		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+//<![CDATA[
+		Pict.safeOnDocumentReady(() => { Pict.safeLoadPictApplication(PictDocuserve, 2)});
+//]]>
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Mermaid diagram rendering -->
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({ startOnLoad: false, theme: 'default' });</script>
+		<!-- KaTeX for LaTeX equation rendering -->
+		<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
+		<!-- Load the Docuserve PICT Application Bundle from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>

package/docs/joins.md

@@ -0,0 +1,101 @@
+# Joins
+
+FoxHound supports table joins for Read and Count queries, allowing you to query across related tables.
+
+## Adding a Join
+
+Use `addJoin()` to add a join to your query:
+
+```javascript
+tmpQuery.addJoin('Authors', 'Authors.IDAuthor', 'Books.IDAuthor');
+```
+
+The full signature is:
+
+```javascript
+addJoin(pTable, pFrom, pTo, pType)
+```
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `pTable` | *(required)* | The table to join |
+| `pFrom` | *(required)* | Column on the join table (must start with `pTable`) |
+| `pTo` | *(required)* | Column on another table (must include a `.`) |
+| `pType` | `'INNER JOIN'` | Join type |
+
+## Join Types
+
+You can specify any SQL join type:
+
+```javascript
+// Inner join (default)
+tmpQuery.addJoin('Authors', 'Authors.IDAuthor', 'Books.IDAuthor');
+
+// Left join
+tmpQuery.addJoin('Authors', 'Authors.IDAuthor', 'Books.IDAuthor', 'LEFT JOIN');
+
+// Right join
+tmpQuery.addJoin('Reviews', 'Reviews.IDBook', 'Books.IDBook', 'RIGHT JOIN');
+```
+
+## Multiple Joins
+
+Chain multiple `addJoin()` calls:
+
+```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;
+```
+
+## Setting Joins Directly
+
+Use `setJoin()` to replace the entire join array:
+
+```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'}
+]);
+```
+
+Or a single join object:
+
+```javascript
+tmpQuery.setJoin({Type: 'INNER JOIN', Table: 'Authors', From: 'Authors.IDAuthor', To: 'Books.IDAuthor'});
+```
+
+## Join Object Structure
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Type` | String | Join type (e.g. `'INNER JOIN'`, `'LEFT JOIN'`) |
+| `Table` | String | Table to join |
+| `From` | String | Column on the join table |
+| `To` | String | Column on the base or another table |
+
+## Validation
+
+FoxHound performs basic validation on join parameters:
+
+- `pTable` must be a string
+- `pFrom` and `pTo` must be defined
+- `pFrom` must start with the join table name
+- `pTo` must include a dot (table-qualified field name)
+
+Invalid joins are logged as warnings and silently skipped.
+
+## Dialect Differences
+
+- **MySQL** — `INNER JOIN Authors ON Authors.IDAuthor = Books.IDAuthor`
+- **MSSQL** — `INNER JOIN [Authors] ON Authors.IDAuthor = Books.IDAuthor`
+- **SQLite/ALASQL** — joins are supported in Read queries but not generated (the SQLite and ALASQL dialects do not include a `generateJoins` function; joins work through query overrides)
+
+> **Note:** The SQLite and ALASQL dialects are primarily designed for simpler single-table queries.  For complex join scenarios, consider using a query override or the MySQL/MSSQL dialect.