foxhound 2.0.13 → 2.0.16

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to Retold
+
+We welcome contributions to Retold and its modules. This guide covers the expectations and process for contributing.
+
+## Code of Conduct
+
+The Retold community values **empathy**, **equity**, **kindness**, and **thoughtfulness**. We expect all participants to treat each other with respect, assume good intent, and engage constructively. These values apply to all interactions: pull requests, issues, discussions, and code review.
+
+## How to Contribute
+
+### Pull Requests
+
+Pull requests are the preferred method for contributing changes. To submit one:
+
+1. Fork the module repository you want to change
+2. Create a branch for your work
+3. Make your changes, following the code style of the module you are editing
+4. Ensure your changes have test coverage (see below)
+5. Open a pull request against the module's main branch
+
+**Submitting a pull request does not guarantee it will be accepted.** Maintainers review contributions for fit, quality, and alignment with the project's direction. A PR may be declined, or you may be asked to revise it. This is normal and not a reflection on the quality of your effort.
+
+### Reporting Issues
+
+If you find a bug or have a feature suggestion, open an issue on the relevant module's repository. Include enough detail to reproduce the problem or understand the proposal.
+
+## Test Coverage
+
+Every commit must include test coverage for the changes it introduces. Retold modules use Mocha in TDD style. Before submitting:
+
+- **Write tests** for any new functionality or bug fixes
+- **Run the existing test suite** with `npm test` and confirm all tests pass
+- **Check coverage** with `npm run coverage` if the module supports it
+
+Pull requests that break existing tests or lack coverage for new code will not be merged.
+
+## Code Style
+
+Follow the conventions of the module you are working in. The general Retold style is:
+
+- **Tabs** for indentation, never spaces
+- **Plain JavaScript** only (no TypeScript)
+- **Allman-style braces** (opening brace on its own line)
+- **Variable naming:** `pVariable` for parameters, `tmpVariable` for temporaries, `libSomething` for imports
+
+When in doubt, match what the surrounding code does.
+
+## Repository Structure
+
+Each module is its own git repository. The [retold](https://github.com/stevenvelozo/retold) repository tracks module organization but does not contain module source code. Direct your pull request to the specific module repository where your change belongs.

package/README.md

@@ -1,65 +1,147 @@
 # FoxHound
 
-The FoxHound javascript query generator, for node.js and the browser.
-
-
-### Getting Started
-
-    $ npm install foxhound --save
-
-Then...
-
-    var foxhound = require('foxhound');
-    var my_awesome_query = foxhound.scope('Users').cap(20).generate().query.body;
-    console.log(my_awesome_query);
+> 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.
+
+## 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
+- **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
+- **Query Overrides** — underscore-style templates for custom SQL while retaining automatic parameter binding
+- **Filtering & Sorting** — rich filter expressions with multiple operators, logical grouping, and multi-column sorting
+- **Joins & Pagination** — INNER, LEFT, and custom joins plus dialect-aware LIMIT/OFFSET pagination
+- **Fable Integration** — operates as a Fable service, inheriting configuration, logging, and UUID generation
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libFoxHound = require('foxhound');
+
+const _Fable = new libFable({});
+const 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' }
+```
 
-The default query dialect is english, so, node should output:
+## Installation
 
-    Please give me 20 of your Users.  Thank you!
+```bash
+npm install foxhound
+```
 
-This is not very useful for anything other than testing, so, we might want to change the dialect and try again:
+## How It Works
 
-    var foxhound = require('foxhound');
-    var my_awesome_query = foxhound.scope('Users').cap(20).setDialect('MySQL').generate().query.body;
-    console.log(my_awesome_query);
+FoxHound follows a configure-then-build pattern.  You create a query instance, chain configuration methods to set the table, columns, filters, sorts, and dialect, then call a build method to generate the SQL.
 
-Which now will output:
+```
+Application Code
+  └── FoxHound Query
+        ├── setScope('Books')         → target table
+        ├── addFilter('Genre', '...')  → WHERE clause
+        ├── addSort('Title')          → ORDER BY clause
+        ├── setCap(25)                → LIMIT clause
+        ├── setDialect('MySQL')       → output format
+        └── buildReadQuery()          → SQL generation
+              ├── query.body          → SQL string
+              └── query.parameters    → bound values
+```
 
-    SELECT * FROM Users LIMIT 20;
+## Dialects
+
+| Dialect | Target | Identifier Quoting | Parameter Prefix | Pagination |
+|---------|--------|-------------------|-----------------|------------|
+| `MySQL` | MySQL / MariaDB | `` `backticks` `` | `:name` | `LIMIT offset, count` |
+| `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` |
+| `English` | Human-readable | none | none | prose |
+| `MeadowEndpoints` | REST URLs | none | none | query string |
+
+## Schema Types
+
+When a schema is attached, FoxHound automatically manages special columns:
+
+| Type | Description |
+|------|-------------|
+| `AutoIdentity` | Auto-increment primary key — `NULL` on insert, skipped on update |
+| `AutoGUID` | Automatically generated UUID on insert |
+| `CreateDate` / `CreateIDUser` | Auto-populated on insert only |
+| `UpdateDate` / `UpdateIDUser` | Auto-populated on insert and update |
+| `DeleteDate` / `DeleteIDUser` | Auto-populated on soft delete |
+| `Deleted` | Soft-delete flag — auto-filtered in reads |
+
+## Filter Operators
+
+| Operator | SQL | Description |
+|----------|-----|-------------|
+| `=` | `=` | Equals (default) |
+| `!=` | `!=` | Not equals |
+| `>`, `>=`, `<`, `<=` | `>`, `>=`, `<`, `<=` | Comparison |
+| `LIKE` | `LIKE` | Pattern match |
+| `IN`, `NOT IN` | `IN (...)`, `NOT IN (...)` | Set membership |
+| `IS NULL`, `IS NOT NULL` | `IS NULL`, `IS NOT NULL` | Null checks |
+| `(`, `)` | `(`, `)` | Logical grouping |
+
+## Testing
+
+```bash
+npm test
+npm run coverage
+```
 
-### Testing
+## Docker Development Environment
 
-    $ npm test
-    $ npm run coverage
+1. Build the image:
 
-### Docker Development Environment
+```bash
+npm run docker-dev-build
+```
 
+2. Run the container:
 
-1. Run this command to build this image:
-```
-docker build ./ -t retold/foxhound:local
+```bash
+npm run docker-dev-run
 ```
 
-alternatively you can use npm to run this
+3. Open http://localhost:24238/ — the password is "retold"
 
+## Documentation
 
-```
-npm run docker-dev-build-image
-```
+Detailed documentation is available in the `docs/` folder and can be served locally:
 
-2. Run this command to build the local container:
-```
-docker run -it --name foxhound-dev -p 127.0.0.1:12346:8080 -v "$PWD/.config:/home/coder/.config"  -v "$PWD:/home/coder/foxhound" -u "$(id -u):$(id -g)" -e "DOCKER_USER=$USER" retold/foxhound:local
+```bash
+npx docsify-cli serve docs
 ```
 
-alternatively you can use npm to run this
+## Related Packages
 
-```
-npm run docker-dev-run
-```
+- [meadow](https://github.com/stevenvelozo/meadow) - Data access and ORM
+- [stricture](https://github.com/stevenvelozo/stricture) - Schema definition language
+- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+
+## License
 
-3. Go to http://localhost:12346/ in a web browser
+MIT
 
-4. The password is "retold"
+## Contributing
 
-5. Right now you (may) need to delete the `node_modules` folders and regenerate it for Linux.
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).

package/docs/.nojekyll

@@ -0,0 +1 @@
+

package/docs/README.md

@@ -0,0 +1,63 @@
+# FoxHound
+
+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
+- **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
+- **Query Overrides** — supply an underscore-style template to customize query generation while still benefiting from automatic parameter binding
+- **Filtering & Sorting** — rich filter expressions with multiple operators, logical grouping, and multi-column sorting
+- **Joins & Pagination** — INNER, LEFT, and custom joins plus dialect-aware LIMIT/OFFSET pagination
+- **Fable Integration** — operates as a Fable service, inheriting configuration, logging, and UUID generation
+
+## Quick Start
+
+```
+$ 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 tmpQuery = libFoxHound.new(_Fable);
+
+tmpQuery.setScope('Users')
+    .setCap(20)
+    .setDialect('MySQL')
+    .buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Users`.* FROM `Users` LIMIT 20;
+```
+
+## 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)
+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`
+
+## Related Packages
+
+| Package | Purpose |
+|---------|---------|
+| [fable](https://github.com/stevenvelozo/fable) | Core service framework (required dependency) |
+| [meadow](https://github.com/stevenvelozo/meadow) | Data access layer that uses FoxHound for query generation |
+| [stricture](https://github.com/stevenvelozo/stricture) | Schema definition tool that produces FoxHound-compatible schema arrays |
+| [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) | REST endpoint generator built on Meadow + FoxHound |
+
+## Testing
+
+```
+$ npm test
+$ npm run coverage
+```

package/docs/_sidebar.md

@@ -0,0 +1,34 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Architecture](architecture.md)
+
+- Query Building
+
+  - [Query Overview](query/README.md)
+  - [Create](query/create.md)
+  - [Read](query/read.md)
+  - [Update](query/update.md)
+  - [Delete](query/delete.md)
+  - [Count](query/count.md)
+
+- Filtering & Sorting
+
+  - [Filters](filters.md)
+  - [Sorting](sorting.md)
+  - [Joins](joins.md)
+  - [Pagination](pagination.md)
+
+- Dialects
+
+  - [Dialects Overview](dialects/README.md)
+  - [MySQL](dialects/mysql.md)
+  - [MSSQL](dialects/mssql.md)
+  - [SQLite](dialects/sqlite.md)
+  - [ALASQL](dialects/alasql.md)
+
+- Advanced
+
+  - [Schema Integration](schema.md)
+  - [Query Overrides](query-overrides.md)
+  - [Configuration Reference](configuration.md)

package/docs/architecture.md

@@ -0,0 +1,104 @@
+# Architecture
+
+FoxHound follows a clean separation between query configuration, dialect-specific generation, and result handling.
+
+## Overview
+
+```
+┌─────────────────────────────────────┐
+│          Application Code           │
+│   query.setScope('Books')           │
+│        .addFilter('Genre','Sci-Fi') │
+│        .setDialect('MySQL')         │
+│        .buildReadQuery()            │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│         FoxHound Core               │
+│  - Parameters object (state)        │
+│  - Chainable configuration API      │
+│  - Dialect selection & delegation   │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│         Dialect Engine              │
+│  MySQL │ MSSQL │ SQLite │ ALASQL   │
+│  - Generates SQL string            │
+│  - Populates named parameters      │
+│  - Applies schema-aware logic      │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│         Query Output                │
+│  query.body       → SQL string      │
+│  query.parameters → bound values    │
+│  query.schema     → column metadata │
+└─────────────────────────────────────┘
+```
+
+## Factory Pattern
+
+FoxHound uses a factory constructor pattern.  The module exports a bare constructor; you create instances by calling `.new()` with a Fable service context:
+
+```javascript
+var libFoxHound = require('foxhound');
+var tmpQuery = libFoxHound.new(_Fable);
+```
+
+Every query instance gets its own UUID and independent parameter state, so multiple queries can be built concurrently without interference.
+
+## Parameters Object
+
+All query state lives in a single `Parameters` object:
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `scope` | String | Table or collection name |
+| `dataElements` | Array | Column/field list |
+| `begin` | Integer | Pagination start offset |
+| `cap` | Integer | Maximum rows to return |
+| `filter` | Array | Filter expression objects |
+| `sort` | Array | Sort expression objects |
+| `join` | Array | Join expression objects |
+| `query` | Object | Generated query body, schema, records, and bound parameters |
+| `queryOverride` | String | Custom query template |
+| `indexHints` | Array | Index hints for the database engine |
+| `userID` | Integer | The acting user (for audit stamps) |
+| `result` | Object | Execution results (value, error, executed flag) |
+
+## Dialect Strategy
+
+Each dialect is a module that exports a factory function accepting a Fable instance.  The returned object exposes six methods that each accept a Parameters object and return a SQL string:
+
+- `Create(pParameters)` — INSERT statement
+- `Read(pParameters)` — SELECT statement
+- `Update(pParameters)` — UPDATE statement
+- `Delete(pParameters)` — UPDATE (soft) or DELETE (hard)
+- `Undelete(pParameters)` — UPDATE to restore soft-deleted rows
+- `Count(pParameters)` — SELECT COUNT statement
+
+The dialect handles all syntax differences: quoting identifiers, parameter prefixes, pagination syntax, date functions, and identity column handling.
+
+## Chainable API
+
+Every setter method returns `this`, enabling fluent composition:
+
+```javascript
+tmpQuery
+    .setScope('Orders')
+    .setDataElements(['OrderID', 'Total', 'Status'])
+    .addFilter('Status', 'Pending')
+    .addSort({Column: 'Total', Direction: 'Descending'})
+    .setCap(50)
+    .setDialect('MySQL')
+    .buildReadQuery();
+```
+
+## Fable Integration
+
+FoxHound depends on Fable for:
+
+- **UUID Generation** — each query and record gets a unique identifier via `_Fable.getUUID()`
+- **Logging** — filter, scope, and query errors are logged through `_Fable.log`
+- **Utility Functions** — `_Fable.Utility.extend()` for parameter merging and `_Fable.Utility.template()` for query overrides
+- **Configuration** — inherits any relevant settings from the Fable config

package/docs/configuration.md

@@ -0,0 +1,217 @@
+# Configuration Reference
+
+This page documents all FoxHound configuration methods, properties, and their accepted values.
+
+## Query Configuration Methods
+
+All setter methods return `this` for chaining.
+
+### setScope(pScope)
+
+Set the primary table or collection for the query.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pScope` | String | Table name |
+
+```javascript
+tmpQuery.setScope('Books');
+```
+
+### setDialect(pDialectName)
+
+Set the SQL dialect for query generation.
+
+| Parameter | Type | Values |
+|-----------|------|--------|
+| `pDialectName` | String | `'MySQL'`, `'MSSQL'`, `'SQLite'`, `'ALASQL'`, `'English'`, `'MeadowEndpoints'` |
+
+```javascript
+tmpQuery.setDialect('MySQL');
+```
+
+### setDataElements(pDataElements)
+
+Set the columns to select.  Pass `false` or omit to select all columns (`*`).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pDataElements` | Array or String | Column name(s) |
+
+```javascript
+tmpQuery.setDataElements(['Title', 'Author']);
+tmpQuery.setDataElements('Title'); // Wraps in array automatically
+```
+
+### setDistinct(pDistinct)
+
+Enable or disable DISTINCT results.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pDistinct` | Boolean | `true` to enable DISTINCT |
+
+### setBegin(pBeginAmount)
+
+Set the pagination starting offset.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pBeginAmount` | Integer ≥ 0 | Zero-based row offset |
+
+### setCap(pCapAmount)
+
+Set the maximum number of rows to return.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pCapAmount` | Integer ≥ 0 | Maximum row count |
+
+### addFilter(pColumn, pValue, pOperator, pConnector, pParameter)
+
+Add a filter expression.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `pColumn` | *(required)* | Column name |
+| `pValue` | *(required)* | Comparison value |
+| `pOperator` | `'='` | Operator (`=`, `!=`, `>`, `>=`, `<`, `<=`, `LIKE`, `IN`, `NOT IN`, `IS NULL`, `IS NOT NULL`, `(`, `)`) |
+| `pConnector` | `'AND'` | Logical connector (`AND`, `OR`, `NONE`) |
+| `pParameter` | `pColumn` | Parameter name |
+
+### setFilter(pFilter)
+
+Replace the entire filter array.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFilter` | Array or Object | Filter expression(s) |
+
+### addSort(pSort)
+
+Add a sort expression.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pSort` | String or Object | Column name or `{Column, Direction}` |
+
+### setSort(pSort)
+
+Replace the entire sort array.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pSort` | String, Object, or Array | Sort expression(s) |
+
+### addJoin(pTable, pFrom, pTo, pType)
+
+Add a join expression.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `pTable` | *(required)* | Table to join |
+| `pFrom` | *(required)* | Column on join table |
+| `pTo` | *(required)* | Column on base table |
+| `pType` | `'INNER JOIN'` | Join type |
+
+### setJoin(pJoin)
+
+Replace the entire join array.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pJoin` | Object or Array | Join expression(s) |
+
+### addRecord(pRecord)
+
+Add a record for CREATE or UPDATE operations.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pRecord` | Object | Key-value pairs of column names and values |
+
+### setIDUser(pIDUser)
+
+Set the user ID for audit stamp columns.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pIDUser` | Integer ≥ 0 | User ID |
+
+### setDisableAutoIdentity(pFlag)
+
+Disable automatic identity column handling.
+
+### setDisableAutoDateStamp(pFlag)
+
+Disable automatic timestamp generation.
+
+### setDisableAutoUserStamp(pFlag)
+
+Disable automatic user ID stamping.
+
+### setDisableDeleteTracking(pFlag)
+
+Disable soft-delete behavior.
+
+### setLogLevel(pLogLevel)
+
+Set the query logging verbosity.
+
+| Level | Behavior |
+|-------|----------|
+| `0` | No logging (default) |
+| `1` | Log generated queries |
+| `2` | Log queries and non-parameterized versions |
+| `3` | Log everything |
+
+## 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 |
+
+## Utility Methods
+
+### clone()
+
+Create a new FoxHound query with the same scope, begin, cap, schema, dataElements, sorts, and filters.
+
+```javascript
+var tmpClone = tmpQuery.clone();
+```
+
+### resetParameters()
+
+Reset the query to its default state.
+
+```javascript
+tmpQuery.resetParameters();
+```
+
+### mergeParameters(pFromParameters)
+
+Merge an object of parameters into the current state.
+
+```javascript
+tmpQuery.mergeParameters({cap: 50, begin: 0});
+```
+
+## Build Methods
+
+| Method | Generates |
+|--------|-----------|
+| `buildCreateQuery()` | INSERT statement |
+| `buildReadQuery()` | SELECT statement |
+| `buildUpdateQuery()` | UPDATE statement |
+| `buildDeleteQuery()` | DELETE or soft-delete UPDATE |
+| `buildUndeleteQuery()` | Restore soft-deleted rows |
+| `buildCountQuery()` | SELECT COUNT statement |
+
+All build methods return `this` for chaining.  The generated SQL is available at `query.body` and bound parameters at `query.parameters`.

package/docs/cover.md

@@ -0,0 +1,11 @@
+# FoxHound <small>2</small>
+
+> A fluent query generation DSL for Node.js and the browser
+
+- 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
+
+[GitHub](https://github.com/stevenvelozo/foxhound)
+[Get Started](#foxhound)