foxhound 2.0.26 → 2.0.28

package/docs/schema.md

@@ -1,6 +1,6 @@
 # Schema Integration
 
-FoxHound is schema-aware — when a schema array is attached to a query, it uses the column type annotations to automatically manage identity columns, timestamps, user stamps, and soft-delete tracking.
+FoxHound is schema-aware -- when a schema array is attached to a query, it uses the column type annotations to automatically manage identity columns, timestamps, user stamps, and soft-delete tracking.
 
 ## Attaching a Schema
 
@@ -29,22 +29,22 @@ tmpQuery.query.schema = [
 
 | Type | Purpose | Create | Read | Update | Delete | Undelete |
 |------|---------|--------|------|--------|--------|----------|
-| `AutoIdentity` | Auto-increment primary key | `NULL` (DB assigns) | included | **skipped** | — | — |
-| `AutoGUID` | Auto-generated UUID | UUID or user value | included | included | — | — |
-| `CreateDate` | Row creation timestamp | `NOW()` | included | **skipped** | — | — |
-| `CreateIDUser` | Row creator user ID | `IDUser` | included | **skipped** | — | — |
+| `AutoIdentity` | Auto-increment primary key | `NULL` (DB assigns) | included | **skipped** | -- | -- |
+| `AutoGUID` | Auto-generated UUID | UUID or user value | included | included | -- | -- |
+| `CreateDate` | Row creation timestamp | `NOW()` | included | **skipped** | -- | -- |
+| `CreateIDUser` | Row creator user ID | `IDUser` | included | **skipped** | -- | -- |
 | `UpdateDate` | Last modification timestamp | `NOW()` | included | `NOW()` | `NOW()` | `NOW()` |
-| `UpdateIDUser` | Last modifier user ID | `IDUser` | included | `IDUser` | — | `IDUser` |
-| `Deleted` | Soft-delete flag | `0` | auto-filtered | — | set to `1` | set to `0` |
-| `DeleteDate` | Deletion timestamp | **skipped** | included | **skipped** | `NOW()` | — |
-| `DeleteIDUser` | Deleter user ID | **skipped** | included | **skipped** | `IDUser` | — |
-| `String` | Text data | parameterized | included | parameterized | — | — |
-| `Integer` | Numeric data | parameterized | included | parameterized | — | — |
-| `Decimal` | Decimal data | parameterized | included | parameterized | — | — |
-| `Boolean` | Boolean data | parameterized | included | parameterized | — | — |
-| `DateTime` | Date/time data | parameterized | included | parameterized | — | — |
-| `JSON` | Structured JSON data | `JSON.stringify` | included | `JSON.stringify` | — | — |
-| `JSONProxy` | JSON with different SQL column name | `JSON.stringify` to `StorageColumn` | included | `JSON.stringify` to `StorageColumn` | — | — |
+| `UpdateIDUser` | Last modifier user ID | `IDUser` | included | `IDUser` | -- | `IDUser` |
+| `Deleted` | Soft-delete flag | `0` | auto-filtered | -- | set to `1` | set to `0` |
+| `DeleteDate` | Deletion timestamp | **skipped** | included | **skipped** | `NOW()` | -- |
+| `DeleteIDUser` | Deleter user ID | **skipped** | included | **skipped** | `IDUser` | -- |
+| `String` | Text data | parameterized | included | parameterized | -- | -- |
+| `Integer` | Numeric data | parameterized | included | parameterized | -- | -- |
+| `Decimal` | Decimal data | parameterized | included | parameterized | -- | -- |
+| `Boolean` | Boolean data | parameterized | included | parameterized | -- | -- |
+| `DateTime` | Date/time data | parameterized | included | parameterized | -- | -- |
+| `JSON` | Structured JSON data | `JSON.stringify` | included | `JSON.stringify` | -- | -- |
+| `JSONProxy` | JSON with different SQL column name | `JSON.stringify` to `StorageColumn` | included | `JSON.stringify` to `StorageColumn` | -- | -- |
 
 ## JSON and JSON Proxy Types
 
@@ -99,33 +99,33 @@ Nested paths are supported (e.g., `Metadata.dimensions.width`). JSON Proxy colum
 
 ### Create (INSERT)
 
-- `AutoIdentity` → inserts `NULL` (MySQL/SQLite) or is omitted (MSSQL)
-- `AutoGUID` → generates a UUID via Fable, unless the record has a valid GUID already
-- `CreateDate`, `UpdateDate` → inserts the current timestamp
-- `CreateIDUser`, `UpdateIDUser` → inserts the user ID from `setIDUser()`
-- `DeleteDate`, `DeleteIDUser` → **skipped** (when delete tracking is enabled)
+- `AutoIdentity` -> inserts `NULL` (MySQL/SQLite) or is omitted (MSSQL)
+- `AutoGUID` -> generates a UUID via Fable, unless the record has a valid GUID already
+- `CreateDate`, `UpdateDate` -> inserts the current timestamp
+- `CreateIDUser`, `UpdateIDUser` -> inserts the user ID from `setIDUser()`
+- `DeleteDate`, `DeleteIDUser` -> **skipped** (when delete tracking is enabled)
 
 ### Update
 
-- `AutoIdentity`, `CreateDate`, `CreateIDUser`, `DeleteDate`, `DeleteIDUser` → **skipped**
-- `UpdateDate` → set to current timestamp automatically
-- `UpdateIDUser` → set to the value from `setIDUser()`
-- All other columns → parameterized from the record
+- `AutoIdentity`, `CreateDate`, `CreateIDUser`, `DeleteDate`, `DeleteIDUser` -> **skipped**
+- `UpdateDate` -> set to current timestamp automatically
+- `UpdateIDUser` -> set to the value from `setIDUser()`
+- All other columns -> parameterized from the record
 
 ### Delete (Soft)
 
 Only these columns are modified:
-- `Deleted` → set to `1`
-- `DeleteDate` → set to current timestamp
-- `UpdateDate` → set to current timestamp
-- `DeleteIDUser` → set to the value from `setIDUser()`
+- `Deleted` -> set to `1`
+- `DeleteDate` -> set to current timestamp
+- `UpdateDate` -> set to current timestamp
+- `DeleteIDUser` -> set to the value from `setIDUser()`
 
 ### Undelete
 
 Only these columns are modified:
-- `Deleted` → set to `0`
-- `UpdateDate` → set to current timestamp
-- `UpdateIDUser` → set to the value from `setIDUser()`
+- `Deleted` -> set to `0`
+- `UpdateDate` -> set to current timestamp
+- `UpdateIDUser` -> set to the value from `setIDUser()`
 
 ### Read / Count
 
@@ -143,4 +143,4 @@ Only these columns are modified:
 
 ## Stricture Integration
 
-Schemas are typically defined using [Stricture](https://github.com/stevenvelozo/stricture), a companion tool that generates schema definitions from a DDL-like JSON format.  Stricture produces the exact schema array format that FoxHound expects.
+Schemas are typically defined using [Stricture](https://github.com/fable-retold/stricture), a companion tool that generates schema definitions from a DDL-like JSON format.  Stricture produces the exact schema array format that FoxHound expects.

package/docs/sorting.md

@@ -33,7 +33,7 @@ tmpQuery
 // ORDER BY Genre, PublishedYear DESC
 ```
 
-Columns without an explicit `Direction` (or with `Direction: 'Ascending'`) sort in ascending order — the SQL default.
+Columns without an explicit `Direction` (or with `Direction: 'Ascending'`) sort in ascending order -- the SQL default.
 
 ## Setting Sorts Directly
 
@@ -71,9 +71,9 @@ tmpQuery.setSort({Column: 'Title', Direction: 'Descending'});
 
 The `ORDER BY` clause syntax is consistent across all SQL dialects.  The main difference is in identifier quoting:
 
-- **MySQL** — `ORDER BY PublishedYear DESC`
-- **MSSQL** — `ORDER BY [PublishedYear] DESC`
-- **SQLite/ALASQL** — `ORDER BY \`PublishedYear\` DESC`
+- **MySQL** -- `ORDER BY PublishedYear DESC`
+- **MSSQL** -- `ORDER BY [PublishedYear] DESC`
+- **SQLite/ALASQL** -- `ORDER BY \`PublishedYear\` DESC`
 
 ## Interaction with Pagination
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "foxhound",
-    "version": "2.0.26",
+    "version": "2.0.28",
     "description": "A Database Query generation library.",
     "main": "source/FoxHound.js",
     "scripts": {
@@ -34,7 +34,7 @@
     },
     "repository": {
         "type": "git",
-        "url": "https://github.com/stevenvelozo/foxhound.git"
+        "url": "https://github.com/fable-retold/foxhound.git"
     },
     "keywords": [
         "orm",
@@ -44,14 +44,15 @@
     "author": "Steven Velozo <steven@velozo.com> (http://velozo.com/)",
     "license": "MIT",
     "bugs": {
-        "url": "https://github.com/stevenvelozo/foxhound/issues"
+        "url": "https://github.com/fable-retold/foxhound/issues"
     },
-    "homepage": "https://github.com/stevenvelozo/foxhound",
+    "homepage": "https://github.com/fable-retold/foxhound",
     "devDependencies": {
-        "quackage": "^1.0.63"
+        "pict-docuserve": "^1.4.12",
+        "quackage": "^1.3.0"
     },
     "dependencies": {
-        "fable": "^3.1.63",
+        "fable": "^3.1.75",
         "typescript": "^5.9.3"
     }
 }

package/source/Foxhound-Dialects.js

@@ -9,6 +9,7 @@ let getDialects = () =>
 	tmpDialects.MySQL = require('./dialects/MySQL/FoxHound-Dialect-MySQL.js');
 	tmpDialects.MSSQL = require('./dialects/MicrosoftSQL/FoxHound-Dialect-MSSQL.js');
 	tmpDialects.PostgreSQL = require('./dialects/PostgreSQL/FoxHound-Dialect-PostgreSQL.js');
+	tmpDialects.Oracle = require('./dialects/Oracle/FoxHound-Dialect-Oracle.js');
 	tmpDialects.MongoDB = require('./dialects/MongoDB/FoxHound-Dialect-MongoDB.js');
 	tmpDialects.DGraph = require('./dialects/DGraph/FoxHound-Dialect-DGraph.js');
 	tmpDialects.Solr = require('./dialects/Solr/FoxHound-Dialect-Solr.js');

package/source/dialects/MicrosoftSQL/FoxHound-Dialect-MSSQL.js

@@ -179,6 +179,51 @@ var FoxHoundDialectMSSQL = function(pFable)
 		return tmpFieldList;
 	};
 
+	/**
+	* Generate a field list for the outer SELECT of the legacy pagination
+	* wrapper.  The outer FROM is a subquery aliased as [_Paged], so the
+	* default "[Table].*" qualifier can't resolve there — we need either
+	* an explicit column list from the schema or a bare "*".
+	*
+	* If the caller set explicit dataElements, reuse them (they reference
+	* bare column names, which work fine against the subquery alias).
+	* Otherwise emit an explicit list from the schema to keep [_RowNum]
+	* from leaking.  As a last resort, fall back to "*" — callers without
+	* a schema will see [_RowNum] as an extra property on marshalled
+	* records but the query itself remains valid.
+	*
+	* @param: {Object} pParameters SQL Query Parameters
+	* @return: {String} Field list (prefixed with a single leading space)
+	*/
+	var generateOuterFieldListForLegacyPagination = function(pParameters)
+	{
+		var tmpDataElements = pParameters.dataElements;
+		if (Array.isArray(tmpDataElements) && tmpDataElements.length > 0)
+		{
+			// Reuse the caller-supplied list.  It emits unqualified column
+			// names ([Col], [Col] AS [Alias]) which resolve fine against
+			// the subquery alias.
+			return generateFieldList(pParameters);
+		}
+
+		var tmpSchema = Array.isArray(pParameters.query.schema) ? pParameters.query.schema : [];
+		if (tmpSchema.length > 0)
+		{
+			var tmpList = ' ';
+			for (var i = 0; i < tmpSchema.length; i++)
+			{
+				if (i > 0) tmpList += ', ';
+				tmpList += generateSafeFieldName(tmpSchema[i].Column);
+			}
+			return tmpList;
+		}
+
+		// No schema, no explicit dataElements — "*" is the best we can do.
+		// [_RowNum] will surface on marshalled records; downstream code can
+		// ignore it.  Schemas are the norm via Meadow so this is rare.
+		return ' *';
+	};
+
 	/**
 	* Ensure a field name is properly escaped.
 	*/
@@ -352,12 +397,41 @@ var FoxHoundDialectMSSQL = function(pFable)
 		return tmpWhere;
 	};
 
+	/**
+	* Find the table's AutoIdentity primary-key column from the schema, if any.
+	* Used as a deterministic default ORDER BY when the caller didn't set a
+	* sort — MSSQL pagination (both OFFSET/FETCH and ROW_NUMBER) requires an
+	* ORDER BY clause or it produces a syntax error.
+	*
+	* @param: {Object} pParameters SQL Query Parameters
+	* @return: {String|null} The column name, or null if none found
+	*/
+	var findPrimaryKeyColumn = function(pParameters)
+	{
+		var tmpSchema = Array.isArray(pParameters.query.schema) ? pParameters.query.schema : [];
+		for (var i = 0; i < tmpSchema.length; i++)
+		{
+			if (tmpSchema[i].Type === 'AutoIdentity')
+			{
+				return tmpSchema[i].Column;
+			}
+		}
+		return null;
+	};
+
 	/**
 	* Generate an ORDER BY clause from the sort array
 	*
 	* Each entry in the sort is an object like:
 	* {Column:'Color',Direction:'Descending'}
 	*
+	* When no sort is specified but the query has a cap (pagination is
+	* active), inject a default ORDER BY on the primary key so MSSQL
+	* doesn't reject the OFFSET/FETCH or ROW_NUMBER clause.  Without a
+	* schema the PK can't be inferred — fall back to `ORDER BY (SELECT 1)`
+	* which is legal for OFFSET/FETCH but not for ROW_NUMBER (the legacy
+	* pagination path handles that case by refusing to paginate).
+	*
 	* @method: generateOrderBy
 	* @param: {Object} pParameters SQL Query Parameters
 	* @return: {String} Returns the field list clause
@@ -367,6 +441,15 @@ var FoxHoundDialectMSSQL = function(pFable)
 		var tmpOrderBy = pParameters.sort;
 		if (!Array.isArray(tmpOrderBy) || tmpOrderBy.length < 1)
 		{
+			if (pParameters.cap)
+			{
+				var tmpPK = findPrimaryKeyColumn(pParameters);
+				if (tmpPK)
+				{
+					return ' ORDER BY ['+tmpPK+']';
+				}
+				return ' ORDER BY (SELECT 1)';
+			}
 			return '';
 		}
 
@@ -390,6 +473,12 @@ var FoxHoundDialectMSSQL = function(pFable)
 	/**
 	* Generate the limit clause
 	*
+	* When `legacyPagination` is set on pParameters the limit is emitted
+	* by the Read function using a ROW_NUMBER() subquery wrapper instead
+	* (OFFSET/FETCH NEXT requires SQL Server 2012+ / compatibility level
+	* 110+, which some customers don't have).  In that case this function
+	* returns an empty string.
+	*
 	* @method: generateLimit
 	* @param: {Object} pParameters SQL Query Parameters
 	* @return: {String} Returns the table limit clause
@@ -401,6 +490,13 @@ var FoxHoundDialectMSSQL = function(pFable)
 			return '';
 		}
 
+		if (pParameters.legacyPagination)
+		{
+			// The Read function wraps the query in a ROW_NUMBER() subquery
+			// instead of appending an OFFSET/FETCH tail clause.
+			return '';
+		}
+
 		var tmpLimit = ' OFFSET ';
 		// If there is a begin record, we'll pass that in as well.
 		if (pParameters.begin !== false)
@@ -1037,6 +1133,30 @@ var FoxHoundDialectMSSQL = function(pFable)
 			}
 		}
 
+		// Legacy pagination path — emit a ROW_NUMBER() wrapper instead of
+		// OFFSET/FETCH.  Required for SQL Server 2008 R2 and earlier, or
+		// for databases running at a compatibility level below 110 (2012).
+		// Enabled via pParameters.legacyPagination (forwarded from the
+		// meadow-connection-mssql provider's LegacyPagination config).
+		if (pParameters.legacyPagination && pParameters.cap)
+		{
+			var tmpBegin = (pParameters.begin !== false) ? pParameters.begin : 0;
+			var tmpEnd = tmpBegin + pParameters.cap;
+			// generateOrderBy always returns a usable ORDER BY when cap is
+			// set.  ROW_NUMBER()'s OVER() clause takes the same body but
+			// without the leading space.
+			var tmpOverClause = tmpOrderBy.replace(/^ /, '');
+			// The outer SELECT's FROM is the subquery alias, not the base
+			// table — so the default field list's "[Table].*" qualifier
+			// won't resolve at the outer level.  Compute an outer field
+			// list that works regardless of whether the caller supplied
+			// explicit dataElements or relied on the default.
+			var tmpOuterFieldList = generateOuterFieldListForLegacyPagination(pParameters);
+			// INDEX hints and JOINs live on the inner select (they apply
+			// to the base table).  [_RowNum] is confined to the subquery.
+			return `SELECT${tmpOptDistinct}${tmpOuterFieldList} FROM (SELECT${tmpFieldList}, ROW_NUMBER() OVER (${tmpOverClause}) AS [_RowNum] FROM${tmpTableName}${tmpIndexHints}${tmpJoin}${tmpWhere}) AS [_Paged] WHERE [_RowNum] > ${tmpBegin} AND [_RowNum] <= ${tmpEnd};`;
+		}
+
 		return `SELECT${tmpOptDistinct}${tmpFieldList} FROM${tmpTableName}${tmpIndexHints}${tmpJoin}${tmpWhere}${tmpOrderBy}${tmpLimit};`;
 	};