foxhound 2.0.19 → 2.0.21

package/docs/dialects/postgresql.md

@@ -0,0 +1,126 @@
+# PostgreSQL Dialect
+
+The PostgreSQL dialect generates SQL compatible with PostgreSQL 9.5 and later.
+
+## Identifier Quoting
+
+PostgreSQL uses double-quote quoting for identifiers, which preserves case sensitivity.  Without double quotes, PostgreSQL folds all identifiers to lowercase.  FoxHound quotes all column and table names to ensure case-sensitive operation:
+
+```sql
+SELECT "Title", "Author" FROM "Books" WHERE "Genre" = :Genre_w0;
+```
+
+Table-qualified field names are quoted on each segment:
+
+```sql
+"Books"."Title"
+```
+
+## Named Parameters
+
+The PostgreSQL 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
+
+PostgreSQL uses `NOW()` for timestamp generation.  Unlike MySQL's `NOW(3)`, PostgreSQL's `NOW()` natively provides microsecond precision.
+
+## Pagination
+
+PostgreSQL uses `LIMIT ... OFFSET` syntax:
+
+```sql
+-- Cap only
+SELECT "Books".* FROM "Books" LIMIT 20;
+
+-- Cap with offset
+SELECT "Books".* FROM "Books" LIMIT 20 OFFSET 40;
+```
+
+## AutoIdentity on INSERT
+
+The PostgreSQL dialect uses `DEFAULT` for AutoIdentity columns on INSERT, allowing PostgreSQL `SERIAL` or `IDENTITY` columns to auto-assign values:
+
+```sql
+INSERT INTO "Books" ( "IDBook", "Title") VALUES ( DEFAULT, :Title_1) RETURNING *;
+```
+
+## RETURNING Clause
+
+All INSERT statements include `RETURNING *`, which returns the full inserted row — including any auto-generated values like serial IDs and default timestamps.
+
+## 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";
+```
+
+## Case Sensitivity
+
+PostgreSQL treats unquoted identifiers as case-insensitive (folded to lowercase).  The FoxHound PostgreSQL dialect wraps all column and table names in double quotes to preserve the exact case of your schema definitions.  This is important when your schema uses mixed-case column names like `IDBook`, `CreateDate`, or `UpdatingIDUser`.
+
+If your PostgreSQL tables were created with quoted identifiers:
+
+```sql
+CREATE TABLE "Books" (
+    "IDBook" SERIAL PRIMARY KEY,
+    "Title" VARCHAR(255),
+    "PublishedYear" INTEGER
+);
+```
+
+Then FoxHound's quoted queries will match these column names correctly.
+
+## Soft Delete
+
+When a schema has a `Deleted` column type, the Delete operation generates an UPDATE:
+
+```sql
+UPDATE "Books" SET "Deleted" = 1, "DeleteDate" = NOW(),
+  "UpdateDate" = NOW(), "DeleteIDUser" = :DeleteIDUser_3
+  WHERE "IDBook" = :IDBook_w0;
+```
+
+## Query Overrides
+
+The PostgreSQL dialect supports underscore-style templates for Read and Count queries:
+
+| Variable | Description |
+|----------|-------------|
+| `<%= FieldList %>` | Generated column list with double-quote quoting |
+| `<%= TableName %>` | Table name with double-quote quoting |
+| `<%= Where %>` | WHERE clause (including the keyword) |
+| `<%= Join %>` | JOIN clauses |
+| `<%= OrderBy %>` | ORDER BY clause |
+| `<%= Limit %>` | LIMIT/OFFSET clause |
+| `<%= Distinct %>` | DISTINCT keyword (if set) |
+| `<%= _Params %>` | Full parameters object |
+
+## Comparison with Other Dialects
+
+| Feature | PostgreSQL | MySQL | MSSQL |
+|---------|-----------|-------|-------|
+| Identifier quoting | `"double quotes"` | `` `backticks` `` | `[brackets]` |
+| Parameter prefix | `:name` | `:name` | `@name` |
+| Timestamp function | `NOW()` | `NOW(3)` | `GETUTCDATE()` |
+| AutoIdentity INSERT | `DEFAULT` | `NULL` | column omitted |
+| INSERT return | `RETURNING *` | none | none |
+| Pagination | `LIMIT n OFFSET m` | `LIMIT m, n` | `OFFSET m ROWS FETCH NEXT n ROWS ONLY` |
+| Case sensitivity | case-sensitive (quoted) | case-insensitive | case-insensitive |

package/docs/quickstart.md

@@ -0,0 +1,196 @@
+# Quickstart
+
+Get up and running with FoxHound in under five minutes.
+
+## Installation
+
+```bash
+npm install foxhound fable
+```
+
+FoxHound requires [Fable](https://github.com/stevenvelozo/fable) as a peer dependency for logging, UUID generation, and utility functions.
+
+## Your First Query
+
+```javascript
+var libFable = require('fable');
+var libFoxHound = require('foxhound');
+
+// Create a Fable instance (provides logging, UUIDs, and utilities)
+var _Fable = new libFable({Product: 'MyApp'});
+
+// Create a new FoxHound query
+var tmpQuery = libFoxHound.new(_Fable);
+
+// Build a simple SELECT
+tmpQuery
+	.setScope('Books')
+	.setDialect('MySQL')
+	.buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Books`.* FROM `Books`;
+```
+
+## Selecting Specific Columns
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.setDataElements(['Title', 'Author', 'PublishedYear'])
+	.buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Title`, `Author`, `PublishedYear` FROM `Books`;
+```
+
+## Adding Filters
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.setDataElements(['Title', 'Author'])
+	.addFilter('Genre', 'Science Fiction')
+	.addFilter('PublishedYear', 2000, '>')
+	.buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Title`, `Author` FROM `Books`
+//    WHERE `Books`.`Genre` = :Genre_w0
+//    AND `Books`.`PublishedYear` > :PublishedYear_w1;
+
+console.log(tmpQuery.query.parameters);
+// => { Genre_w0: 'Science Fiction', PublishedYear_w1: 2000 }
+```
+
+## Sorting and Pagination
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addSort({Column: 'PublishedYear', Direction: 'Descending'})
+	.setCap(25)
+	.setBegin(0)
+	.buildReadQuery();
+
+console.log(tmpQuery.query.body);
+// => SELECT `Books`.* FROM `Books`
+//    ORDER BY PublishedYear DESC LIMIT 0, 25;
+```
+
+## Creating a Record
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addRecord({Title: 'Dune', Author: 'Frank Herbert', PublishedYear: 1965})
+	.buildCreateQuery();
+
+console.log(tmpQuery.query.body);
+// => INSERT INTO `Books` ( Title, Author, PublishedYear)
+//    VALUES ( :Title_0, :Author_1, :PublishedYear_2);
+
+console.log(tmpQuery.query.parameters);
+// => { Title_0: 'Dune', Author_1: 'Frank Herbert', PublishedYear_2: 1965 }
+```
+
+## Updating a Record
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addFilter('IDBook', 42)
+	.addRecord({Title: 'Dune Messiah', PublishedYear: 1969})
+	.buildUpdateQuery();
+
+console.log(tmpQuery.query.body);
+// => UPDATE `Books` SET Title = :Title_0, PublishedYear = :PublishedYear_1
+//    WHERE IDBook = :IDBook_w0;
+```
+
+## Deleting a Record
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addFilter('IDBook', 42)
+	.buildDeleteQuery();
+
+console.log(tmpQuery.query.body);
+// => DELETE FROM `Books` WHERE IDBook = :IDBook_w0;
+```
+
+## Switching Dialects
+
+The same query configuration works across all dialects:
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setScope('Books')
+	.setDataElements(['Title', 'Author'])
+	.addFilter('Genre', 'Fantasy')
+	.setCap(10);
+
+// MySQL
+tmpQuery.setDialect('MySQL').buildReadQuery();
+console.log(tmpQuery.query.body);
+// => SELECT `Title`, `Author` FROM `Books`
+//    WHERE `Books`.`Genre` = :Genre_w0 LIMIT 10;
+
+// PostgreSQL
+tmpQuery.setDialect('PostgreSQL').buildReadQuery();
+console.log(tmpQuery.query.body);
+// => SELECT "Title", "Author" FROM "Books"
+//    WHERE "Genre" = :Genre_w0 LIMIT 10;
+
+// MSSQL
+tmpQuery.setDialect('MSSQL').buildReadQuery();
+console.log(tmpQuery.query.body);
+// => SELECT [Title], [Author] FROM [Books]
+//    WHERE Genre = @Genre_w0 OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY;
+```
+
+## Using with a Schema
+
+Attaching a schema enables automatic management of identity, timestamp, and soft-delete columns:
+
+```javascript
+var tmpQuery = libFoxHound.new(_Fable)
+	.setDialect('MySQL')
+	.setScope('Books')
+	.addRecord({IDBook: null, Title: 'Neuromancer', Author: 'William Gibson'});
+
+tmpQuery.query.schema = [
+	{Column: 'IDBook', Type: 'AutoIdentity'},
+	{Column: 'Title', Type: 'String'},
+	{Column: 'Author', Type: 'String'},
+	{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'}
+];
+tmpQuery.query.IDUser = 5;
+
+tmpQuery.buildCreateQuery();
+
+console.log(tmpQuery.query.body);
+// => INSERT INTO `Books` ( IDBook, Title, Author, CreateDate, ...)
+//    VALUES ( NULL, :Title_1, :Author_2, NOW(3), ...);
+```
+
+## Next Steps
+
+- [Architecture](architecture.md) — understand FoxHound's internal design
+- [Filters](filters.md) — learn about filter operators and grouping
+- [Schema Integration](schema.md) — use schemas for automatic column management
+- [Dialects](dialects/README.md) — explore dialect-specific features
+- [API Reference](api/README.md) — complete function reference

package/docs/retold-catalog.json

@@ -1,5 +1,5 @@
 {
-	"Generated": "2026-02-18T01:02:40.710Z",
+	"Generated": "2026-03-03T14:33:09.873Z",
 	"GitHubOrg": "stevenvelozo",
 	"DefaultBranch": "master",
 	"Groups": [
@@ -69,6 +69,44 @@
 			"Key": "docs",
 			"Description": "",
 			"Modules": [
+				{
+					"Name": "api",
+					"Repo": "api",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"api/README.md",
+						"api/addFilter.md",
+						"api/addJoin.md",
+						"api/addRecord.md",
+						"api/addSort.md",
+						"api/behaviorFlags.md",
+						"api/buildQuery.md",
+						"api/clone.md",
+						"api/queryOverrides.md",
+						"api/setCap.md",
+						"api/setDataElements.md",
+						"api/setDialect.md",
+						"api/setDistinct.md",
+						"api/setIDUser.md",
+						"api/setScope.md"
+					]
+				},
+				{
+					"Name": "css",
+					"Repo": "css",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"css/docuserve.css"
+					]
+				},
 				{
 					"Name": "dialects",
 					"Repo": "dialects",
@@ -82,6 +120,7 @@
 						"dialects/alasql.md",
 						"dialects/mssql.md",
 						"dialects/mysql.md",
+						"dialects/postgresql.md",
 						"dialects/sqlite.md"
 					]
 				},