meadow 2.0.23 → 2.0.26

package/docs/api/rawQueries.md

@@ -0,0 +1,197 @@
+# rawQueries (Property)
+
+Access the raw query manager for overriding auto-generated SQL with custom
+query strings.
+
+## Signature
+
+```javascript
+var tmpRawQueries = meadow.rawQueries;
+```
+
+## Returns
+
+| Type | Description |
+|------|-------------|
+| `Object` | The Meadow-RawQuery manager instance |
+
+## Description
+
+The `rawQueries` property provides access to a manager that stores and
+retrieves raw query strings. When a raw query override is set for a particular
+operation tag, Meadow passes it to the provider as `queryOverride` instead of
+auto-generating the SQL from the FoxHound query.
+
+This is useful when you need hand-tuned SQL for performance, complex joins, or
+database-specific features that the query builder does not support.
+
+## Methods
+
+### setQuery
+
+```javascript
+meadow.rawQueries.setQuery(pQueryTag, pQueryString)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQueryTag` | `string` | The operation tag (e.g. `'Read'`, `'Reads'`, `'Count'`) |
+| `pQueryString` | `string` | The raw SQL query string |
+
+**Returns:** The Meadow instance (for chaining off the parent).
+
+Sets a raw query override for the given tag. When a CRUD method detects a raw
+query for its tag, it passes the string to the provider.
+
+### loadQuery
+
+```javascript
+meadow.rawQueries.loadQuery(pQueryTag, pFileName, fCallBack)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQueryTag` | `string` | The operation tag |
+| `pFileName` | `string` | Path to a file containing the SQL query |
+| `fCallBack` | `Function` | Callback: `function(pSuccess)` where `pSuccess` is `true` or `false` |
+
+**Returns:** The Meadow instance (for chaining off the parent).
+
+Loads a raw query from a file asynchronously using `fs.readFile`. On success,
+the file contents are stored as the raw query for the given tag. On error, the
+query is set to an empty string and `false` is passed to the callback.
+
+### getQuery
+
+```javascript
+meadow.rawQueries.getQuery(pQueryTag)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQueryTag` | `string` | The operation tag |
+
+**Returns:** The raw query string, or `false` if no override is set for that
+tag.
+
+### checkQuery
+
+```javascript
+meadow.rawQueries.checkQuery(pQueryTag)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQueryTag` | `string` | The operation tag |
+
+**Returns:** `true` if a raw query override exists for the tag, `false`
+otherwise.
+
+## Supported Override Tags
+
+| Tag | Used By | Description |
+|-----|---------|-------------|
+| `'Read'` | `doRead`, `doCreate` (read-back), `doUpdate` (read-back) | 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 |
+
+**Not supported for override:** `'Create'` and `'Update'` are not currently
+supported. The source notes that these overrides are too complex and the
+feature is deferred.
+
+You can also store arbitrary custom query tags for your own use, but only the
+tags listed above are automatically checked by Meadow's CRUD methods.
+
+## Examples
+
+### Override a read query
+
+```javascript
+meadow.rawQueries.setQuery('Read',
+	'SELECT b.*, a.Name AS AuthorName ' +
+	'FROM Book b ' +
+	'JOIN Author a ON b.IDAuthor = a.IDAuthor ' +
+	'WHERE b.IDBook = :IDBook AND b.Deleted = 0');
+
+var tmpQuery = meadow.query.addFilter('IDBook', 42);
+meadow.doRead(tmpQuery,
+	function (pError, pQuery, pRecord)
+	{
+		// Uses the custom join query instead of auto-generated SQL
+		console.log(pRecord);
+	});
+```
+
+### Override a reads query with pagination
+
+```javascript
+meadow.rawQueries.setQuery('Reads',
+	'SELECT b.IDBook, b.Title, COUNT(r.IDReview) AS ReviewCount ' +
+	'FROM Book b ' +
+	'LEFT JOIN Review r ON b.IDBook = r.IDBook ' +
+	'WHERE b.Deleted = 0 ' +
+	'GROUP BY b.IDBook, b.Title ' +
+	'ORDER BY ReviewCount DESC ' +
+	'LIMIT :Cap OFFSET :Begin');
+
+var tmpQuery = meadow.query.setCap(10).setBegin(0);
+meadow.doReads(tmpQuery,
+	function (pError, pQuery, pRecords)
+	{
+		console.log(pRecords);
+	});
+```
+
+### Load a query from a file
+
+```javascript
+meadow.rawQueries.loadQuery('Reads', __dirname + '/queries/BookList.sql',
+	function (pSuccess)
+	{
+		if (!pSuccess)
+		{
+			console.error('Failed to load query file');
+			return;
+		}
+
+		var tmpQuery = meadow.query;
+		meadow.doReads(tmpQuery,
+			function (pError, pQuery, pRecords)
+			{
+				console.log(pRecords);
+			});
+	});
+```
+
+### Check before using
+
+```javascript
+if (meadow.rawQueries.checkQuery('Count'))
+{
+	console.log('Custom count query:', meadow.rawQueries.getQuery('Count'));
+}
+else
+{
+	console.log('Using auto-generated count query');
+}
+```
+
+## Notes
+
+- Raw queries use FoxHound parameter placeholders (e.g. `:IDBook`, `:Cap`,
+  `:Begin`, `:IDUser`). The provider substitutes these with actual values at
+  execution time.
+
+- The `Read` override is shared between `doRead`, the read-back step of
+  `doCreate`, and the read-back step of `doUpdate`. Setting it affects all
+  three operations.
+
+- When a `loadQuery` file read fails, the query is set to an empty string
+  `''` (not `false`). This means FoxHound will receive an empty override
+  rather than generating a query. Be aware of this when handling file load
+  errors.
+
+- Raw query overrides are stored per-instance. Different Meadow instances
+  (even for the same scope) maintain independent raw query sets.

package/docs/api/reference.md

@@ -0,0 +1,117 @@
+# Meadow API Reference
+
+Meadow is a data access layer for the Retold ecosystem. It wraps database
+providers behind a consistent CRUD interface, with schema-driven marshalling,
+audit stamping, and role-based authorization.
+
+## Factory
+
+```javascript
+var libMeadow = require('meadow');
+var meadow = libMeadow.new(pFable, 'Book');
+```
+
+`require('meadow')` returns a constructor object. Call `.new(pFable, pScope)` to
+create an instance bound to a Fable service context and an entity scope.
+
+## CRUD Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| [doCreate](doCreate.md) | `doCreate(pQuery, fCallBack)` | Insert a record, read it back, return marshalled object |
+| [doRead](doRead.md) | `doRead(pQuery, fCallBack)` | Read a single record by filter |
+| [doReads](doReads.md) | `doReads(pQuery, fCallBack)` | Read multiple records with pagination and filtering |
+| [doUpdate](doUpdate.md) | `doUpdate(pQuery, fCallBack)` | Update a record by primary key, read it back |
+| [doDelete](doDelete.md) | `doDelete(pQuery, fCallBack)` | Soft-delete or hard-delete a record |
+| [doUndelete](doUndelete.md) | `doUndelete(pQuery, fCallBack)` | Restore a soft-deleted record |
+| [doCount](doCount.md) | `doCount(pQuery, fCallBack)` | Count records matching filters |
+
+All CRUD methods accept a FoxHound query object (obtained from `meadow.query`)
+and a Node-style callback. They return the Meadow instance for chaining.
+
+## Configuration Methods
+
+All configuration methods are chainable (they return `this`).
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| [setProvider](setProvider.md) | `setProvider(pProviderName)` | Set the database provider by name |
+| [setScope](setScope.md) | `setScope(pScope)` | Set the entity scope (table name) |
+| [setSchema](setSchema.md) | `setSchema(pSchema)` | Set the column schema array |
+| [setDefaultIdentifier](setDefaultIdentifier.md) | `setDefaultIdentifier(pDefaultIdentifier)` | Set the primary key column name |
+| [setIDUser](setIDUser.md) | `setIDUser(pIDUser)` | Set the user ID for audit stamps |
+| [setJsonSchema](setJsonSchema.md) | `setJsonSchema(pJsonSchema)` | Set JSON Schema for validation |
+| [setDefault](setDefault.md) | `setDefault(pDefault)` | Set the default object template |
+| [setAuthorizer](setAuthorizer.md) | `setAuthorizer(pAuthorizer)` | Set role-based authorization rules |
+| [setDomain](setDomain.md) | `setDomain(pDomain)` | Set the entity domain grouping |
+| [loadFromPackage](loadFromPackage.md) | `loadFromPackage(pPackage)` | Load schema from a JSON file path |
+| [loadFromPackage](loadFromPackage.md) | `loadFromPackageObject(pPackage)` | Load schema from a JS object |
+
+## Utility Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| [validateObject](validateObject.md) | `validateObject(pObject)` | Validate an object against JSON Schema |
+| [marshalRecordFromSourceToObject](marshalRecordFromSourceToObject.md) | `marshalRecordFromSourceToObject(pRecord)` | Convert a database row to a plain object |
+| [getRoleName](getRoleName.md) | `getRoleName(pRoleIndex)` | Get the role name for a numeric index |
+| logSlowQuery | `logSlowQuery(pProfileTime, pQuery)` | Log a warning for slow queries |
+
+## Properties
+
+All properties are read-only.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `scope` | `string` | The entity scope (table name) |
+| `schema` | `Array` | The column schema array |
+| `schemaFull` | `Object` | The full Meadow-Schema object (includes `validateObject`, `defaultObject`, `authorizer`) |
+| `jsonSchema` | `Object` | The JSON Schema object |
+| `defaultIdentifier` | `string` | The primary key column name (e.g. `'IDBook'`) |
+| `defaultGUIdentifier` | `string` | The GUID column name (e.g. `'GUIDBook'`) |
+| `userIdentifier` | `number` | The current user ID for audit stamps |
+| [query](query.md) | `Object` | A cloned FoxHound query with scope and schema pre-set |
+| [rawQueries](rawQueries.md) | `Object` | The raw query manager for SQL overrides |
+| `provider` | `Object` | The active database provider instance |
+| `providerName` | `string` | The name of the active provider (e.g. `'MySQL'`) |
+
+## Fable Services
+
+Meadow instances also expose the following properties inherited from the Fable
+service context:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `fable` | `Object` | The parent Fable instance |
+| `settings` | `Object` | The Fable settings object |
+| `log` | `Object` | The Fable logger |
+
+## Quick Start
+
+```javascript
+var libFable = require('fable');
+var libMeadow = require('meadow');
+
+var tmpFable = libFable.new({ MeadowProvider: 'MySQL' });
+var tmpMeadow = libMeadow.new(tmpFable, 'Book')
+	.setSchema([
+		{ Column: 'IDBook', Type: 'AutoIdentity' },
+		{ Column: 'GUIDBook', Type: 'AutoGUID' },
+		{ Column: 'Title', Type: 'String', Size: '128' },
+		{ Column: 'Created', Type: 'CreateDate' },
+		{ Column: 'CreatingIDUser', Type: 'CreateIDUser' },
+		{ Column: 'Modified', Type: 'UpdateDate' },
+		{ Column: 'ModifyingIDUser', Type: 'UpdateIDUser' },
+		{ Column: 'Deleted', Type: 'Deleted' },
+		{ Column: 'DeletingIDUser', Type: 'DeleteIDUser' },
+		{ Column: 'DeleteDate', Type: 'DeleteDate' }
+	])
+	.setIDUser(1);
+
+// Create a record
+var tmpQuery = tmpMeadow.query.addRecord({ Title: 'The Hobbit' });
+tmpMeadow.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		console.log('Created:', pRecord);
+	});
+```

package/docs/api/setAuthorizer.md

@@ -0,0 +1,103 @@
+# setAuthorizer
+
+Set the role-based authorization rules for this Meadow instance.
+
+## Signature
+
+```javascript
+meadow.setAuthorizer(pAuthorizer)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pAuthorizer` | `Object` | An object mapping role names to operation permissions |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setAuthorizer` sets the authorization rules used by Meadow-Endpoints to
+enforce role-based access control on CRUD operations. Each key in the object is
+a role name, and each value is an object mapping operations to permission
+strings.
+
+The authorizer is stored on the schema object and is accessible via
+`meadow.schemaFull.authorizer`.
+
+## Authorizer Structure
+
+```javascript
+{
+	"Role Name": {
+		"Create": "Allow" | "Deny" | <custom>,
+		"Read": "Allow" | "Deny" | <custom>,
+		"Reads": "Allow" | "Deny" | <custom>,
+		"Update": "Allow" | "Deny" | <custom>,
+		"Delete": "Allow" | "Deny" | <custom>,
+		"Undelete": "Allow" | "Deny" | <custom>,
+		"Count": "Allow" | "Deny" | <custom>
+	}
+}
+```
+
+## Examples
+
+### Basic role configuration
+
+```javascript
+meadow.setAuthorizer({
+	"Unauthenticated": {
+		"Create": "Deny",
+		"Read": "Allow",
+		"Reads": "Allow",
+		"Update": "Deny",
+		"Delete": "Deny",
+		"Undelete": "Deny",
+		"Count": "Allow"
+	},
+	"User": {
+		"Create": "Allow",
+		"Read": "Allow",
+		"Reads": "Allow",
+		"Update": "Allow",
+		"Delete": "Allow",
+		"Undelete": "Deny",
+		"Count": "Allow"
+	},
+	"Administrator": {
+		"Create": "Allow",
+		"Read": "Allow",
+		"Reads": "Allow",
+		"Update": "Allow",
+		"Delete": "Allow",
+		"Undelete": "Allow",
+		"Count": "Allow"
+	}
+});
+```
+
+### Access after setting
+
+```javascript
+console.log(meadow.schemaFull.authorizer);
+// { "Unauthenticated": { ... }, "User": { ... }, ... }
+```
+
+## Notes
+
+- If `pAuthorizer` is not an object, it falls back to an empty object `{}`.
+
+- The authorizer is primarily consumed by Meadow-Endpoints, which checks
+  permissions before executing CRUD operations on HTTP routes. Meadow itself
+  does not enforce authorization during direct `doCreate`, `doRead`, etc. calls.
+
+- Role names should match the names returned by `getRoleName()`. The default
+  role names are: `'Unauthenticated'`, `'User'`, `'Manager'`, `'Director'`,
+  `'Executive'`, `'Administrator'`.
+
+- When loading from a package file or object, the `Authorization` property of
+  the package is passed to `setAuthorizer` automatically.

package/docs/api/setDefault.md

@@ -0,0 +1,90 @@
+# setDefault
+
+Set the default object template used when creating and marshalling records.
+
+## Signature
+
+```javascript
+meadow.setDefault(pDefault)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pDefault` | `Object` | A plain object with default values for all columns |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setDefault` sets the template object that is used in two places:
+
+1. **During `doCreate`** -- The default object is merged with the submitted
+   record before insertion, ensuring that all schema columns have values even if
+   the caller omitted them.
+
+2. **During marshalling** -- When `marshalRecordFromSourceToObject` converts a
+   database row to a plain object, it starts with a copy of the default object
+   and overlays the provider-marshalled values.
+
+This ensures consistent object shapes throughout the application, regardless of
+whether the database returned null columns or the caller submitted a partial
+record.
+
+## Examples
+
+### Set default values
+
+```javascript
+meadow.setDefault({
+	IDBook: 0,
+	GUIDBook: '',
+	Title: '',
+	Author: 'Unknown',
+	PageCount: 0,
+	Created: '',
+	CreatingIDUser: 0,
+	Modified: '',
+	ModifyingIDUser: 0,
+	Deleted: 0,
+	DeletingIDUser: 0,
+	DeleteDate: ''
+});
+```
+
+### Effect on create
+
+```javascript
+meadow.setDefault({ Title: 'Untitled', Author: 'Unknown', PageCount: 0 });
+
+var tmpQuery = meadow.query
+	.addRecord({ Title: 'Dune' });
+
+meadow.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		// pRecord.Author will be 'Unknown' (from defaults)
+		// pRecord.Title will be 'Dune' (from submitted record)
+		// pRecord.PageCount will be 0 (from defaults)
+		console.log(pRecord);
+	});
+```
+
+### Access via schemaFull
+
+```javascript
+console.log(meadow.schemaFull.defaultObject);
+// { IDBook: 0, GUIDBook: '', Title: '', ... }
+```
+
+## Notes
+
+- If `pDefault` is not an object, it falls back to an empty object `{}`.
+
+- The default object is accessible through `meadow.schemaFull.defaultObject`.
+
+- When loading from a package file or object, the `DefaultObject` property
+  of the package is passed to `setDefault` automatically.

package/docs/api/setDefaultIdentifier.md

@@ -0,0 +1,84 @@
+# setDefaultIdentifier
+
+Set the primary key column name for this Meadow instance.
+
+## Signature
+
+```javascript
+meadow.setDefaultIdentifier(pDefaultIdentifier)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pDefaultIdentifier` | `string` | The primary key column name (e.g. `'IDBook'`) |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setDefaultIdentifier` sets the primary key column name used for automated
+queries. It also derives the GUID identifier by prepending `'GU'` to the value.
+For example, setting the identifier to `'IDBook'` automatically sets the GUID
+identifier to `'GUIDBook'`.
+
+After setting the identifier, `updateProviderState()` is called to synchronize
+with the active provider.
+
+By default, the identifier is derived from the scope at construction time:
+`'ID' + scope` (e.g., scope `'Book'` produces identifier `'IDBook'`).
+
+## Examples
+
+### Default behavior
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book');
+console.log(meadow.defaultIdentifier);   // 'IDBook'
+console.log(meadow.defaultGUIdentifier); // 'GUIDBook'
+```
+
+### Custom identifier
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book')
+	.setDefaultIdentifier('BookID');
+
+console.log(meadow.defaultIdentifier);   // 'BookID'
+console.log(meadow.defaultGUIdentifier); // 'GUBookID'
+```
+
+### Use with non-standard naming
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'UserProfile')
+	.setDefaultIdentifier('ProfileID');
+
+// doUpdate will require records to have a 'ProfileID' property
+var tmpQuery = meadow.query
+	.addRecord({ ProfileID: 5, DisplayName: 'Alice' });
+
+meadow.doUpdate(tmpQuery,
+	function (pError, pUpdateQuery, pReadQuery, pRecord)
+	{
+		console.log(pRecord);
+	});
+```
+
+## Notes
+
+- The GUID identifier is always `'GU' + pDefaultIdentifier`. This is a fixed
+  convention and cannot be set independently.
+
+- The default identifier is used by `doUpdate` to determine which column
+  identifies the record to update. If the record does not contain this column,
+  the update is aborted.
+
+- The default identifier is also used by `doCreate` to read back the newly
+  created record after insertion.
+
+- Changing the default identifier calls `updateProviderState()` to synchronize
+  with the active provider.

package/docs/api/setDomain.md

@@ -0,0 +1,56 @@
+# setDomain
+
+Set the entity domain for organizational grouping.
+
+## Signature
+
+```javascript
+meadow.setDomain(pDomain)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pDomain` | `string` | The domain name for this entity |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setDomain` sets an organizational grouping label for the Meadow instance.
+Domains allow multiple entities to be grouped logically, which is useful in
+multi-tenant or modular applications.
+
+The default domain is `'Default'`.
+
+## Examples
+
+### Set a custom domain
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book')
+	.setDomain('Library');
+```
+
+### Set domain from a package
+
+```javascript
+// In a package JSON file:
+// { "Scope": "Book", "Domain": "Library", ... }
+
+var meadow = libMeadow.new(tmpFable)
+	.loadFromPackage('./Book.json');
+// Domain is set to 'Library' from the package
+```
+
+## Notes
+
+- The domain is a free-form string with no restrictions on content.
+
+- The default value is `'Default'` if not explicitly set.
+
+- When loading from a package file or object, the `Domain` property of the
+  package is passed to `setDomain` automatically.