meadow 2.0.22 → 2.0.26

package/docs/quick-start.md

@@ -0,0 +1,384 @@
+# Quick Start
+
+This guide walks you through installing Meadow, connecting to a database, and performing every core CRUD operation.
+
+## Installation
+
+Meadow requires [Fable](https://github.com/stevenvelozo/fable) as its runtime container and a connection module for your chosen database. Install all three:
+
+```bash
+npm install meadow fable meadow-connection-mysql
+```
+
+Replace `meadow-connection-mysql` with the connection module that matches your database. Available connection modules include `meadow-connection-mssql`, `meadow-connection-sqlite`, `meadow-connection-rocksdb`, and others.
+
+## Creating a Fable Instance
+
+Fable provides configuration, logging, and dependency injection. Create a Fable instance with your database connection settings:
+
+```javascript
+var libFable = require('fable');
+
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'MySQL',
+		MySQL:
+		{
+			Server: 'localhost',
+			Port: 3306,
+			User: 'root',
+			Password: 'my-secret-pw',
+			Database: 'bookstore',
+			ConnectionPoolLimit: 20
+		}
+	});
+```
+
+## Registering a Connection Provider
+
+Before Meadow can execute queries, the database connection pool must be registered on the Fable instance. Each connection module attaches its pool to a well-known property on Fable.
+
+For MySQL using `meadow-connection-mysql`:
+
+```javascript
+var libMeadowConnectionMySQL = require('meadow-connection-mysql');
+
+var tmpConnectionProvider = libMeadowConnectionMySQL.new(_Fable);
+tmpConnectionProvider.connect(
+	function (pError)
+	{
+		if (pError)
+		{
+			console.log('Connection error:', pError);
+			return;
+		}
+		console.log('Connected to MySQL');
+		// Meadow is now ready to execute queries
+	});
+```
+
+For the legacy approach, you can also create a pool manually:
+
+```javascript
+var libMySQL = require('mysql2');
+
+_Fable.MeadowMySQLConnectionPool = libMySQL.createPool(
+	{
+		connectionLimit: _Fable.settings.MySQL.ConnectionPoolLimit,
+		host: _Fable.settings.MySQL.Server,
+		port: _Fable.settings.MySQL.Port,
+		user: _Fable.settings.MySQL.User,
+		password: _Fable.settings.MySQL.Password,
+		database: _Fable.settings.MySQL.Database,
+		namedPlaceholders: true
+	});
+```
+
+## Creating a Meadow DAL
+
+Create a new Meadow data access layer (DAL) for an entity by calling `meadow.new()` with a Fable instance and an entity scope name:
+
+```javascript
+var libMeadow = require('meadow');
+
+var tmpBookDAL = libMeadow.new(_Fable, 'Book');
+```
+
+The scope name (here `'Book'`) determines the database table name for queries and establishes naming conventions for the default identifier column (`IDBook`) and GUID column (`GUIDBook`).
+
+## Setting Provider, Default Identifier, and Schema
+
+Chain configuration calls to set up the provider, default identifier, and schema:
+
+```javascript
+var tmpBookDAL = libMeadow.new(_Fable, 'Book')
+	.setProvider('MySQL')
+	.setDefaultIdentifier('IDBook')
+	.setSchema(
+		[
+			{ Column: 'IDBook', Type: 'AutoIdentity' },
+			{ Column: 'GUIDBook', Type: 'AutoGUID' },
+			{ Column: 'Title', Type: 'String', Size: '255' },
+			{ Column: 'Author', Type: 'String', Size: '128' },
+			{ Column: 'YearPublished', Type: 'Number' },
+			{ 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' }
+		])
+	.setDefault(
+		{
+			IDBook: null,
+			GUIDBook: '',
+			Title: '',
+			Author: '',
+			YearPublished: 0,
+			CreateDate: false,
+			CreatingIDUser: 0,
+			UpdateDate: false,
+			UpdatingIDUser: 0,
+			Deleted: 0,
+			DeleteDate: false,
+			DeletingIDUser: 0
+		});
+```
+
+If you do not call `setProvider()` explicitly, Meadow uses the `MeadowProvider` value from Fable settings (defaulting to `'None'`).
+
+## CRUD Walkthrough
+
+Every CRUD operation follows the same pattern: obtain a query from `meadow.query`, configure it, then pass it to a `do*` method with a callback.
+
+### Create a Record
+
+```javascript
+var tmpQuery = tmpBookDAL.query
+	.addRecord(
+		{
+			Title: 'Dune',
+			Author: 'Frank Herbert',
+			YearPublished: 1965
+		});
+
+tmpBookDAL.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		if (pError)
+		{
+			console.log('Create error:', pError);
+			return;
+		}
+		console.log('Created book:', pRecord.IDBook, '-', pRecord.Title);
+	});
+```
+
+The create behavior performs three steps internally: checks GUID uniqueness (if a GUID is provided), inserts the record, and reads it back. The callback receives the fully marshalled record with its new auto-generated `IDBook`.
+
+### Read a Single Record
+
+```javascript
+var tmpQuery = tmpBookDAL.query
+	.addFilter('IDBook', 1);
+
+tmpBookDAL.doRead(tmpQuery,
+	function (pError, pQuery, pRecord)
+	{
+		if (pError)
+		{
+			console.log('Read error:', pError);
+			return;
+		}
+		if (!pRecord)
+		{
+			console.log('No record found');
+			return;
+		}
+		console.log('Read:', pRecord.Title, 'by', pRecord.Author);
+	});
+```
+
+### Update a Record
+
+```javascript
+var tmpQuery = tmpBookDAL.query
+	.addRecord(
+		{
+			IDBook: 1,
+			Title: 'Dune (Revised Edition)',
+			Author: 'Frank Herbert'
+		});
+
+tmpBookDAL.doUpdate(tmpQuery,
+	function (pError, pUpdateQuery, pReadQuery, pRecord)
+	{
+		if (pError)
+		{
+			console.log('Update error:', pError);
+			return;
+		}
+		console.log('Updated:', pRecord.Title);
+	});
+```
+
+The update behavior automatically adds a filter on the default identifier from the record, executes the update, then reads the record back and returns the marshalled result. The `UpdateDate` and `UpdatingIDUser` columns are automatically stamped.
+
+### List Records (Reads)
+
+```javascript
+var tmpQuery = tmpBookDAL.query
+	.setCap(25)
+	.setBegin(0)
+	.addSort({ Column: 'Title', Direction: 'ASC' });
+
+tmpBookDAL.doReads(tmpQuery,
+	function (pError, pQuery, pRecords)
+	{
+		if (pError)
+		{
+			console.log('Reads error:', pError);
+			return;
+		}
+		console.log('Found', pRecords.length, 'books');
+		for (var i = 0; i < pRecords.length; i++)
+		{
+			console.log(' -', pRecords[i].Title);
+		}
+	});
+```
+
+### Count Records
+
+```javascript
+var tmpQuery = tmpBookDAL.query
+	.addFilter('Author', 'Frank Herbert');
+
+tmpBookDAL.doCount(tmpQuery,
+	function (pError, pQuery, pCount)
+	{
+		if (pError)
+		{
+			console.log('Count error:', pError);
+			return;
+		}
+		console.log('Frank Herbert has', pCount, 'books');
+	});
+```
+
+### Soft Delete a Record
+
+```javascript
+var tmpQuery = tmpBookDAL.query
+	.addFilter('IDBook', 1);
+
+tmpBookDAL.doDelete(tmpQuery,
+	function (pError, pQuery, pResult)
+	{
+		if (pError)
+		{
+			console.log('Delete error:', pError);
+			return;
+		}
+		console.log('Soft-deleted book, affected rows:', pResult);
+	});
+```
+
+When the schema contains a `Deleted` column of type `'Deleted'`, the delete operation generates an `UPDATE` statement that sets `Deleted = 1` rather than issuing a `DELETE` statement. Subsequent queries automatically filter out deleted records.
+
+### Undelete a Record
+
+```javascript
+var tmpQuery = tmpBookDAL.query
+	.addFilter('IDBook', 1);
+
+tmpBookDAL.doUndelete(tmpQuery,
+	function (pError, pQuery, pResult)
+	{
+		if (pError)
+		{
+			console.log('Undelete error:', pError);
+			return;
+		}
+		console.log('Restored book, affected rows:', pResult);
+	});
+```
+
+Undelete sets `Deleted = 0`, making the record visible in normal queries again.
+
+## Setting User Identity
+
+Meadow automatically stamps user identity into `CreateIDUser`, `UpdateIDUser`, and `DeleteIDUser` columns. Set the acting user on the DAL instance:
+
+```javascript
+tmpBookDAL.setIDUser(42);
+```
+
+You can also set user identity on a per-query basis:
+
+```javascript
+var tmpQuery = tmpBookDAL.query;
+tmpQuery.query.IDUser = 42;
+```
+
+## Loading from a Package File
+
+Instead of configuring scope, schema, default object, and JSON schema individually, you can define everything in a single JSON package file and load it:
+
+```javascript
+var tmpBookDAL = libMeadow.new(_Fable)
+	.loadFromPackage(__dirname + '/Book.json');
+```
+
+The package file structure:
+
+```json
+{
+	"Scope": "Book",
+	"DefaultIdentifier": "IDBook",
+	"Schema": [
+		{ "Column": "IDBook", "Type": "AutoIdentity" },
+		{ "Column": "GUIDBook", "Type": "AutoGUID" },
+		{ "Column": "Title", "Type": "String", "Size": "255" },
+		{ "Column": "Author", "Type": "String", "Size": "128" },
+		{ "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" }
+	],
+	"DefaultObject": {
+		"IDBook": null,
+		"GUIDBook": "",
+		"Title": "",
+		"Author": "",
+		"CreateDate": false,
+		"CreatingIDUser": 0,
+		"UpdateDate": false,
+		"UpdatingIDUser": 0,
+		"Deleted": 0,
+		"DeleteDate": false,
+		"DeletingIDUser": 0
+	},
+	"JsonSchema": {
+		"title": "Book",
+		"description": "A book in the library.",
+		"type": "object",
+		"properties": {
+			"IDBook": {
+				"description": "The unique identifier for a book",
+				"type": "integer"
+			},
+			"Title": {
+				"description": "The title of the book",
+				"type": "string"
+			},
+			"Author": {
+				"description": "The author of the book",
+				"type": "string"
+			}
+		},
+		"required": ["IDBook", "Title"]
+	}
+}
+```
+
+You can also load from an in-memory object using `loadFromPackageObject()`:
+
+```javascript
+var tmpBookDAL = libMeadow.new(_Fable)
+	.loadFromPackageObject(
+		{
+			Scope: 'Book',
+			DefaultIdentifier: 'IDBook',
+			Schema:
+			[
+				{ Column: 'IDBook', Type: 'AutoIdentity' },
+				{ Column: 'GUIDBook', Type: 'AutoGUID' },
+				{ Column: 'Title', Type: 'String', Size: '255' }
+			]
+		});
+```

package/docs/raw-queries.md

@@ -0,0 +1,193 @@
+# Raw Queries
+
+Raw queries let you bypass FoxHound's query generation and provide your own SQL strings directly. This is an escape hatch for complex queries -- JOINs, subqueries, custom reports, and anything the DSL does not natively support.
+
+## What Raw Queries Are
+
+When Meadow executes a CRUD operation, FoxHound normally generates the SQL query body from your filters, sort directives, and schema. A raw query override replaces that generated SQL with a string you provide. The override is stored by tag name and is automatically applied when the corresponding behavior runs.
+
+Raw queries are managed through the `meadow.rawQueries` object, which is an instance of `Meadow-RawQuery`.
+
+## Setting a Raw Query
+
+Use `setQuery` to register a SQL override string by tag name:
+
+```javascript
+var tmpBookDAL = libMeadow.new(_Fable, 'Book')
+	.setProvider('MySQL')
+	.setDefaultIdentifier('IDBook')
+	.setSchema(tmpBookSchema);
+
+tmpBookDAL.rawQueries.setQuery('Reads',
+	'SELECT b.IDBook, b.Title, b.Author, a.Name AS AuthorName ' +
+	'FROM Book b ' +
+	'INNER JOIN Author a ON b.IDAuthor = a.IDAuthor ' +
+	'WHERE b.Deleted = 0');
+```
+
+After setting this override, every `doReads` call on this DAL uses your custom SQL instead of the auto-generated query.
+
+The `setQuery` method returns the Meadow instance, so you can chain it if desired.
+
+## Loading a Raw Query from a File
+
+Use `loadQuery` to read a SQL override from a file on disk. This is useful for keeping complex queries in their own `.sql` files:
+
+```javascript
+tmpBookDAL.rawQueries.loadQuery('Reads', __dirname + '/queries/BookReads.sql',
+	function (pSuccess)
+	{
+		if (pSuccess)
+		{
+			console.log('Custom Reads query loaded');
+		}
+		else
+		{
+			console.log('Failed to load custom Reads query');
+		}
+	});
+```
+
+The callback receives `true` if the file was loaded successfully, or `false` if there was an error. On failure, the query tag is set to an empty string (which means FoxHound will generate an empty query body rather than falling back to auto-generation).
+
+## Retrieving a Raw Query
+
+Use `getQuery` to retrieve a previously stored raw query by tag:
+
+```javascript
+var tmpSQL = tmpBookDAL.rawQueries.getQuery('Reads');
+// Returns the SQL string, or false if no query is set for this tag
+```
+
+## Checking if a Raw Query Exists
+
+Use `checkQuery` to test whether a query has been registered for a given tag:
+
+```javascript
+if (tmpBookDAL.rawQueries.checkQuery('Reads'))
+{
+	console.log('Custom Reads query is set');
+}
+else
+{
+	console.log('Using auto-generated Reads query');
+}
+```
+
+Returns `true` if a query has been set for the tag, `false` otherwise.
+
+## Override Tags
+
+Meadow behaviors check for raw query overrides using specific tag names. The following tags are recognized:
+
+| Tag | Behavior | Description |
+|-----|----------|-------------|
+| `Read` | `doRead` | Override the single-record read query |
+| `Reads` | `doReads` | Override the multi-record read query |
+| `Delete` | `doDelete` | Override the delete query |
+| `Undelete` | `doUndelete` | Override the undelete query |
+| `Count` | `doCount` | Override the count query |
+
+Additionally, the `Read` override is also used during `doCreate` and `doUpdate` when they read the record back after writing. This means setting a `Read` override affects the read-back step of create and update operations as well.
+
+### Create and Update Do Not Support Raw Query Overrides
+
+The `Create` and `Update` tags are **not** supported for raw query overrides. The insert and update SQL generation involves complex parameter binding and column mapping that is tightly coupled to FoxHound's query builder. Attempting to set a `Create` or `Update` override will have no effect.
+
+If you need custom insert or update behavior, consider using the provider's database connection directly for those specific operations.
+
+## Examples
+
+### JOIN Query for Reads
+
+Create a file `queries/BookWithAuthor.sql`:
+
+```sql
+SELECT
+	b.IDBook,
+	b.GUIDBook,
+	b.Title,
+	b.YearPublished,
+	b.CreateDate,
+	b.CreatingIDUser,
+	b.UpdateDate,
+	b.UpdatingIDUser,
+	b.Deleted,
+	b.DeleteDate,
+	b.DeletingIDUser,
+	a.Name AS AuthorName,
+	a.Country AS AuthorCountry
+FROM Book b
+	LEFT JOIN Author a ON b.IDAuthor = a.IDAuthor
+WHERE b.Deleted = 0
+ORDER BY b.Title ASC
+```
+
+Load and use it:
+
+```javascript
+tmpBookDAL.rawQueries.loadQuery('Reads', __dirname + '/queries/BookWithAuthor.sql',
+	function (pSuccess)
+	{
+		tmpBookDAL.doReads(tmpBookDAL.query.setCap(50),
+			function (pError, pQuery, pRecords)
+			{
+				for (var i = 0; i < pRecords.length; i++)
+				{
+					console.log(pRecords[i].Title, 'by', pRecords[i].AuthorName);
+				}
+			});
+	});
+```
+
+### Custom Count Query
+
+```javascript
+tmpBookDAL.rawQueries.setQuery('Count',
+	'SELECT COUNT(DISTINCT Author) AS RowCount ' +
+	'FROM Book ' +
+	'WHERE Deleted = 0');
+
+tmpBookDAL.doCount(tmpBookDAL.query,
+	function (pError, pQuery, pCount)
+	{
+		console.log('Unique authors:', pCount);
+	});
+```
+
+Note that the count query must return a result with a `RowCount` column for the MySQL provider (or `Row_Count` for MSSQL) so the provider can extract the numeric value.
+
+### Custom Read Override for Single Records
+
+```javascript
+tmpBookDAL.rawQueries.setQuery('Read',
+	'SELECT b.*, GROUP_CONCAT(t.TagName) AS Tags ' +
+	'FROM Book b ' +
+	'LEFT JOIN BookTag bt ON b.IDBook = bt.IDBook ' +
+	'LEFT JOIN Tag t ON bt.IDTag = t.IDTag ' +
+	'WHERE b.IDBook = :IDBook AND b.Deleted = 0 ' +
+	'GROUP BY b.IDBook');
+
+tmpBookDAL.doRead(tmpBookDAL.query.addFilter('IDBook', 42),
+	function (pError, pQuery, pRecord)
+	{
+		console.log(pRecord.Title, '- Tags:', pRecord.Tags);
+	});
+```
+
+### Using Arbitrary Tags
+
+You can store any number of custom queries under arbitrary tag names for your own use, even though Meadow only checks the standard tags automatically:
+
+```javascript
+tmpBookDAL.rawQueries.setQuery('TopAuthors',
+	'SELECT Author, COUNT(*) AS BookCount ' +
+	'FROM Book ' +
+	'WHERE Deleted = 0 ' +
+	'GROUP BY Author ' +
+	'ORDER BY BookCount DESC ' +
+	'LIMIT 10');
+
+// Retrieve later for manual use
+var tmpSQL = tmpBookDAL.rawQueries.getQuery('TopAuthors');
+```

package/docs/retold-catalog.json

@@ -1,5 +1,5 @@
 {
-	"Generated": "2026-02-18T01:05:03.079Z",
+	"Generated": "2026-03-02T02:11:44.637Z",
 	"GitHubOrg": "stevenvelozo",
 	"DefaultBranch": "master",
 	"Groups": [
@@ -55,6 +55,16 @@
 			"Key": "dist",
 			"Description": "",
 			"Modules": [
+				{
+					"Name": "FableTest-RocksDB",
+					"Repo": "FableTest-RocksDB",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				},
 				{
 					"Name": "indoctrinate_content_staging",
 					"Repo": "indoctrinate_content_staging",
@@ -72,6 +82,52 @@
 			"Key": "docs",
 			"Description": "",
 			"Modules": [
+				{
+					"Name": "api",
+					"Repo": "api",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"api/doCount.md",
+						"api/doCreate.md",
+						"api/doDelete.md",
+						"api/doRead.md",
+						"api/doReads.md",
+						"api/doUndelete.md",
+						"api/doUpdate.md",
+						"api/getRoleName.md",
+						"api/loadFromPackage.md",
+						"api/marshalRecordFromSourceToObject.md",
+						"api/query.md",
+						"api/rawQueries.md",
+						"api/reference.md",
+						"api/setAuthorizer.md",
+						"api/setDefault.md",
+						"api/setDefaultIdentifier.md",
+						"api/setDomain.md",
+						"api/setIDUser.md",
+						"api/setJsonSchema.md",
+						"api/setProvider.md",
+						"api/setSchema.md",
+						"api/setScope.md",
+						"api/validateObject.md"
+					]
+				},
+				{
+					"Name": "css",
+					"Repo": "css",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"css/docuserve.css"
+					]
+				},
 				{
 					"Name": "providers",
 					"Repo": "providers",
@@ -83,8 +139,12 @@
 					"DocFiles": [
 						"providers/README.md",
 						"providers/alasql.md",
+						"providers/meadow-endpoints.md",
+						"providers/mongodb.md",
 						"providers/mssql.md",
 						"providers/mysql.md",
+						"providers/postgresql.md",
+						"providers/rocksdb.md",
 						"providers/sqlite.md"
 					]
 				},