foxhound 2.0.19 → 2.0.21

package/docs/api/setDataElements.md

@@ -0,0 +1,95 @@
+# setDataElements
+
+Set which columns to include in the SELECT clause.
+
+## Signature
+
+```javascript
+tmpQuery.setDataElements(pDataElements)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pDataElements` | Array or String | Yes | Column name(s) to select |
+
+## Returns
+
+Returns `this` for chaining.
+
+## Description
+
+Sets the list of columns to include in the SELECT field list.  When not set (or set to `false`), the query selects all columns using `*`.
+
+If a string is passed, it is automatically wrapped in an array.
+
+## Examples
+
+### Select all columns (default)
+
+```javascript
+tmpQuery.setScope('Books').setDialect('MySQL').buildReadQuery();
+// => SELECT `Books`.* FROM `Books`;
+```
+
+### Select specific columns
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDataElements(['Title', 'Author', 'PublishedYear'])
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+// => SELECT `Title`, `Author`, `PublishedYear` FROM `Books`;
+```
+
+### Single column as string
+
+```javascript
+tmpQuery.setDataElements('Title');
+// Automatically converted to ['Title']
+```
+
+### Column aliases
+
+Pass an array pair `[column, alias]` to create a column alias:
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDataElements([
+		['Books.Title', 'BookTitle'],
+		['Books.Author', 'AuthorName']
+	])
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+// => SELECT `Books`.`Title` AS `BookTitle`, `Books`.`Author` AS `AuthorName`
+//    FROM `Books`;
+```
+
+### Wildcard with specific columns
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDataElements(['*', 'Authors.Name'])
+	.setDialect('PostgreSQL')
+	.buildReadQuery();
+
+// => SELECT *, "Authors"."Name" FROM "Books";
+```
+
+### Table-qualified wildcard
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDataElements(['Books.*', 'Authors.Name'])
+	.setDialect('PostgreSQL')
+	.buildReadQuery();
+
+// => SELECT "Books".*, "Authors"."Name" FROM "Books";
+```

package/docs/api/setDialect.md

@@ -0,0 +1,78 @@
+# setDialect
+
+Set the SQL dialect used for query generation.
+
+## Signature
+
+```javascript
+tmpQuery.setDialect(pDialectName)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pDialectName` | String | Yes | Name of the dialect |
+
+## Returns
+
+Returns `this` for chaining.
+
+## Available Dialects
+
+| Name | Target Database |
+|------|----------------|
+| `'MySQL'` | MySQL / MariaDB |
+| `'PostgreSQL'` | PostgreSQL 9.5+ |
+| `'MSSQL'` | Microsoft SQL Server |
+| `'SQLite'` | SQLite 3 |
+| `'ALASQL'` | ALASQL (in-memory JavaScript) |
+| `'English'` | Human-readable text (default) |
+| `'MeadowEndpoints'` | REST URL generation |
+| `'MongoDB'` | MongoDB query objects |
+| `'DGraph'` | DGraph graph queries |
+| `'Solr'` | Apache Solr search |
+
+## Description
+
+The dialect determines how FoxHound translates the internal query parameters into database-specific syntax.  This includes identifier quoting, parameter prefixes, pagination syntax, timestamp functions, and auto-identity handling.
+
+If an invalid dialect name is passed, FoxHound logs an error and falls back to the `English` dialect.
+
+## Examples
+
+### Basic usage
+
+```javascript
+tmpQuery.setDialect('MySQL');
+```
+
+### Same query, different dialects
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setScope('Books')
+	.addFilter('Genre', 'Fantasy')
+	.setCap(10);
+
+tmpQuery.setDialect('MySQL').buildReadQuery();
+console.log(tmpQuery.query.body);
+// => SELECT `Books`.* FROM `Books` WHERE `Books`.`Genre` = :Genre_w0 LIMIT 10;
+
+tmpQuery.setDialect('PostgreSQL').buildReadQuery();
+console.log(tmpQuery.query.body);
+// => SELECT "Books".* FROM "Books" WHERE "Genre" = :Genre_w0 LIMIT 10;
+
+tmpQuery.setDialect('MSSQL').buildReadQuery();
+console.log(tmpQuery.query.body);
+// => SELECT [Books].* FROM [Books] WHERE Genre = @Genre_w0
+//    OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY;
+```
+
+### Checking the active dialect
+
+```javascript
+tmpQuery.setDialect('PostgreSQL');
+console.log(tmpQuery.dialect.name);
+// => 'PostgreSQL'
+```

package/docs/api/setDistinct.md

@@ -0,0 +1,76 @@
+# setDistinct
+
+Enable or disable DISTINCT result filtering.
+
+## Signature
+
+```javascript
+tmpQuery.setDistinct(pDistinct)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pDistinct` | Boolean | Yes | `true` to enable DISTINCT |
+
+## Returns
+
+Returns `this` for chaining.
+
+## Description
+
+When enabled, the generated SELECT statement includes the `DISTINCT` keyword to return only unique rows.
+
+For Count queries with DISTINCT, FoxHound counts distinct values of the selected field list (or the AutoIdentity column from the schema if no specific fields are set).
+
+## Examples
+
+### DISTINCT select
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDataElements(['Genre'])
+	.setDistinct(true)
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+// => SELECT DISTINCT `Genre` FROM `Books`;
+```
+
+### DISTINCT count
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDataElements(['Author'])
+	.setDistinct(true)
+	.setDialect('MySQL')
+	.buildCountQuery();
+
+// => SELECT COUNT(DISTINCT `Author`) AS RowCount FROM `Books`;
+```
+
+### DISTINCT count with schema (no explicit fields)
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDistinct(true);
+
+tmpQuery.query.schema = [
+	{Column: 'IDBook', Type: 'AutoIdentity'},
+	{Column: 'Title', Type: 'String'}
+];
+
+tmpQuery.setDialect('MySQL').buildCountQuery();
+
+// => SELECT COUNT(DISTINCT `Books`.`IDBook`) AS RowCount FROM `Books`;
+```
+
+### Disable DISTINCT
+
+```javascript
+tmpQuery.setDistinct(false);
+```

package/docs/api/setIDUser.md

@@ -0,0 +1,80 @@
+# setIDUser
+
+Set the user ID for automatic audit column stamping.
+
+## Signature
+
+```javascript
+tmpQuery.setIDUser(pIDUser)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pIDUser` | Integer | Yes | User ID (must be >= 0) |
+
+## Returns
+
+Returns `this` for chaining.
+
+## Description
+
+Sets the user ID that FoxHound uses when auto-populating audit columns in schema-aware queries.  This value is applied to:
+
+- `CreateIDUser` columns on INSERT
+- `UpdateIDUser` columns on INSERT and UPDATE
+- `DeleteIDUser` columns on soft DELETE
+
+The value defaults to `0` if not set.
+
+## Examples
+
+### Basic usage
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.addRecord({Title: 'Dune', Author: 'Frank Herbert'})
+	.setIDUser(42);
+
+tmpQuery.query.schema = [
+	{Column: 'IDBook', Type: 'AutoIdentity'},
+	{Column: 'Title', Type: 'String'},
+	{Column: 'Author', Type: 'String'},
+	{Column: 'CreatingIDUser', Type: 'CreateIDUser'},
+	{Column: 'UpdatingIDUser', Type: 'UpdateIDUser'}
+];
+
+tmpQuery.setDialect('MySQL').buildCreateQuery();
+
+// CreatingIDUser => 42
+// UpdatingIDUser => 42
+```
+
+### With soft delete
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.addFilter('IDBook', 99)
+	.setIDUser(5);
+
+tmpQuery.query.schema = [
+	{Column: 'IDBook', Type: 'AutoIdentity'},
+	{Column: 'Deleted', Type: 'Deleted'},
+	{Column: 'DeleteDate', Type: 'DeleteDate'},
+	{Column: 'DeletingIDUser', Type: 'DeleteIDUser'},
+	{Column: 'UpdateDate', Type: 'UpdateDate'}
+];
+
+tmpQuery.setDialect('MySQL').buildDeleteQuery();
+
+// DeletingIDUser => 5
+```
+
+### Alternative: direct property access
+
+```javascript
+tmpQuery.query.IDUser = 42;
+```

package/docs/api/setScope.md

@@ -0,0 +1,70 @@
+# setScope
+
+Set the primary table or collection for the query.
+
+## Signature
+
+```javascript
+tmpQuery.setScope(pScope)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pScope` | String | Yes | Table or collection name |
+
+## Returns
+
+Returns `this` for chaining.
+
+## Description
+
+The scope defines which table (or collection, in NoSQL dialects) the query targets.  This is required for all query types — it appears as the `FROM` clause in SELECT, `INSERT INTO` in CREATE, `UPDATE` in UPDATE, and `DELETE FROM` in DELETE.
+
+FoxHound validates that the input is a string.  Non-string values are ignored and an error is logged.
+
+## Examples
+
+### Basic usage
+
+```javascript
+tmpQuery.setScope('Books');
+```
+
+### With dialect quoting
+
+Each dialect quotes the scope name according to its conventions:
+
+```javascript
+// MySQL
+tmpQuery.setScope('Books').setDialect('MySQL').buildReadQuery();
+// => SELECT `Books`.* FROM `Books`;
+
+// PostgreSQL
+tmpQuery.setScope('Books').setDialect('PostgreSQL').buildReadQuery();
+// => SELECT "Books".* FROM "Books";
+
+// MSSQL
+tmpQuery.setScope('Books').setDialect('MSSQL').buildReadQuery();
+// => SELECT [Books].* FROM [Books];
+```
+
+### Pre-quoted scope
+
+If the scope is already quoted for your dialect, FoxHound preserves it:
+
+```javascript
+tmpQuery.setScope('"MySchema"."Books"');
+// PostgreSQL will use: "MySchema"."Books"
+```
+
+### Chaining
+
+```javascript
+tmpQuery
+	.setScope('Books')
+	.setDataElements(['Title', 'Author'])
+	.setDialect('MySQL')
+	.buildReadQuery();
+```

package/docs/architecture.md

@@ -4,36 +4,76 @@ FoxHound follows a clean separation between query configuration, dialect-specifi
 
 ## Overview
 
+```mermaid
+graph TD
+    A[Application Code] -->|configure| B[FoxHound Core]
+    B -->|setDialect| C{Dialect Engine}
+    C -->|MySQL| D[MySQL Generator]
+    C -->|PostgreSQL| E[PostgreSQL Generator]
+    C -->|MSSQL| F[MSSQL Generator]
+    C -->|SQLite| G[SQLite Generator]
+    C -->|ALASQL| H[ALASQL Generator]
+    C -->|English| I[English Generator]
+    D --> J[Query Output]
+    E --> J
+    F --> J
+    G --> J
+    H --> J
+    I --> J
+    J -->|query.body| K[SQL String]
+    J -->|query.parameters| L[Bound Values]
 ```
-┌─────────────────────────────────────┐
-│          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 │
-└─────────────────────────────────────┘
+
+## Query Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant FH as FoxHound
+    participant D as Dialect
+    participant P as Parameters
+
+    App->>FH: libFoxHound.new(_Fable)
+    FH->>P: Initialize Parameters
+    App->>FH: setScope('Books')
+    App->>FH: addFilter('Genre', 'Sci-Fi')
+    App->>FH: setDialect('MySQL')
+    App->>FH: buildReadQuery()
+    FH->>D: Read(parameters)
+    D->>D: generateFieldList()
+    D->>D: generateWhere()
+    D->>D: generateOrderBy()
+    D->>D: generateLimit()
+    D-->>FH: SQL string
+    FH->>P: Store in query.body
+    App->>FH: query.body
+    FH-->>App: SELECT `Books`.* FROM `Books` WHERE ...
+```
+
+## Component Architecture
+
+```mermaid
+graph LR
+    subgraph FoxHound Core
+        A[FoxHound.js] --> B[Parameters.js]
+        A --> C[Foxhound-Dialects.js]
+    end
+
+    subgraph Dialect Modules
+        C --> D[MySQL]
+        C --> E[PostgreSQL]
+        C --> F[MSSQL]
+        C --> G[SQLite]
+        C --> H[ALASQL]
+        C --> I[English]
+        C --> J[MeadowEndpoints]
+    end
+
+    subgraph External
+        K[Fable] --> A
+        L[Meadow] --> A
+        M[Stricture] --> B
+    end
 ```
 
 ## Factory Pattern
@@ -70,12 +110,42 @@ All query state lives in a single `Parameters` object:
 
 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
+```mermaid
+classDiagram
+    class Dialect {
+        +Create(pParameters) String
+        +Read(pParameters) String
+        +Update(pParameters) String
+        +Delete(pParameters) String
+        +Undelete(pParameters) String
+        +Count(pParameters) String
+        +name String
+    }
+
+    class MySQL {
+        +backtick quoting
+        +colon parameters
+        +NOW 3 timestamps
+    }
+
+    class PostgreSQL {
+        +double-quote quoting
+        +colon parameters
+        +NOW timestamps
+        +RETURNING clause
+    }
+
+    class MSSQL {
+        +bracket quoting
+        +at-sign parameters
+        +GETUTCDATE timestamps
+        +OFFSET FETCH pagination
+    }
+
+    Dialect <|-- MySQL
+    Dialect <|-- PostgreSQL
+    Dialect <|-- MSSQL
+```
 
 The dialect handles all syntax differences: quoting identifiers, parameter prefixes, pagination syntax, date functions, and identity column handling.
 
@@ -85,13 +155,13 @@ 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();
+	.setScope('Orders')
+	.setDataElements(['OrderID', 'Total', 'Status'])
+	.addFilter('Status', 'Pending')
+	.addSort({Column: 'Total', Direction: 'Descending'})
+	.setCap(50)
+	.setDialect('MySQL')
+	.buildReadQuery();
 ```
 
 ## Fable Integration
@@ -102,3 +172,25 @@ FoxHound depends on Fable for:
 - **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
+
+## Schema-Aware Generation
+
+```mermaid
+flowchart TD
+    A[Record Object] --> B{Schema Attached?}
+    B -->|No| C[All columns parameterized]
+    B -->|Yes| D[Check each column type]
+    D --> E{AutoIdentity?}
+    E -->|Yes| F[NULL / DEFAULT / Skip]
+    D --> G{CreateDate?}
+    G -->|Yes| H[NOW timestamp]
+    D --> I{Deleted?}
+    I -->|Yes| J[Auto-filter on Read]
+    D --> K{Default?}
+    K -->|Yes| L[Parameterized value]
+    C --> M[Generate SQL]
+    F --> M
+    H --> M
+    J --> M
+    L --> M
+```

package/docs/dialects/README.md

@@ -7,6 +7,7 @@ FoxHound uses a dialect strategy pattern to generate database-specific SQL from
 | Dialect | Target | Identifier Quoting | Parameter Prefix | Pagination |
 |---------|--------|-------------------|-----------------|------------|
 | [MySQL](dialects/mysql.md) | MySQL / MariaDB | `` `backticks` `` | `:name` | `LIMIT offset, count` |
+| [PostgreSQL](dialects/postgresql.md) | PostgreSQL 9.5+ | `"double quotes"` | `:name` | `LIMIT count OFFSET offset` |
 | [MSSQL](dialects/mssql.md) | Microsoft SQL Server | `[brackets]` | `@name` | `OFFSET n ROWS FETCH NEXT m ROWS ONLY` |
 | [SQLite](dialects/sqlite.md) | SQLite 3 | `` `backticks` `` | `:name` | `LIMIT count OFFSET offset` |
 | [ALASQL](dialects/alasql.md) | ALASQL (in-memory) | `` `backticks` `` | `:name` | `LIMIT count FETCH offset` |
@@ -54,6 +55,7 @@ All SQL dialects share these behaviors:
 | Use Case | Recommended Dialect |
 |----------|-------------------|
 | Production MySQL/MariaDB | `MySQL` |
+| Production PostgreSQL | `PostgreSQL` |
 | Production SQL Server | `MSSQL` |
 | Embedded/file-based database | `SQLite` |
 | Browser-side or in-memory queries | `ALASQL` |