meadow 2.0.23 → 2.0.26

package/docs/api/doUndelete.md

@@ -0,0 +1,98 @@
+# doUndelete
+
+Restore a soft-deleted record by setting its `Deleted` flag back to `0`.
+
+## Signature
+
+```javascript
+meadow.doUndelete(pQuery, fCallBack)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQuery` | `Object` | A FoxHound query object with filters identifying the record(s) to restore |
+| `fCallBack` | `Function` | Callback invoked when the operation completes |
+
+## Callback
+
+```javascript
+function (pError, pQuery, pCount)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pError` | `string\|null` | Error message, or falsy on success |
+| `pQuery` | `Object` | The FoxHound query used for the undelete operation |
+| `pCount` | `number` | The number of affected records |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`doUndelete` executes a single-step asynchronous waterfall:
+
+1. **Undelete** -- If an `Undelete` raw query override is set via
+   `rawQueries.setQuery('Undelete', ...)`, it is used. Otherwise, the
+   provider's `Undelete` method executes the query, issuing
+   `UPDATE {Scope} SET Deleted=0 WHERE ...`.
+
+The `DeleteDate` and `DeletingIDUser` columns are preserved as historical
+records of the previous deletion. They are **not** cleared during an undelete
+operation.
+
+## Examples
+
+### Undelete by primary key
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('IDBook', 42)
+	.setDisableDeleteTracking(true);
+
+meadow.doUndelete(tmpQuery,
+	function (pError, pQuery, pCount)
+	{
+		if (pError)
+		{
+			console.error('Undelete failed:', pError);
+			return;
+		}
+		console.log('Restored', pCount, 'record(s)');
+	});
+```
+
+### Undelete with a custom raw query
+
+```javascript
+meadow.rawQueries.setQuery('Undelete',
+	'UPDATE Book SET Deleted=0 WHERE IDBook = :IDBook AND DeletingIDUser = :IDUser');
+
+var tmpQuery = meadow.query
+	.addFilter('IDBook', 42);
+
+meadow.doUndelete(tmpQuery,
+	function (pError, pQuery, pCount)
+	{
+		console.log('Custom undelete affected', pCount, 'record(s)');
+	});
+```
+
+## Notes
+
+- `doUndelete` only applies to schemas that use soft deletion (those with a
+  `Deleted` column). It has no effect on schemas configured for hard deletion.
+
+- The `DeleteDate` and `DeletingIDUser` values remain on the record after
+  undelete. This preserves the audit history of when and by whom the record was
+  previously deleted.
+
+- You may need to use `setDisableDeleteTracking(true)` on the query when
+  building filters that target soft-deleted records, since the default behavior
+  excludes records where `Deleted = 1`.
+
+- The `Undelete` raw query override applies to this method. Set it via
+  `meadow.rawQueries.setQuery('Undelete', pQueryString)`.

package/docs/api/doUpdate.md

@@ -0,0 +1,129 @@
+# doUpdate
+
+Update an existing record in the data source, read it back, and return the
+marshalled result.
+
+## Signature
+
+```javascript
+meadow.doUpdate(pQuery, fCallBack)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQuery` | `Object` | A FoxHound query object with a record containing the primary key and fields to update |
+| `fCallBack` | `Function` | Callback invoked when the operation completes |
+
+## Callback
+
+```javascript
+function (pError, pUpdateQuery, pReadQuery, pRecord)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pError` | `string\|null` | Error message, or falsy on success |
+| `pUpdateQuery` | `Object` | The FoxHound query used for the UPDATE operation |
+| `pReadQuery` | `Object` | The FoxHound query used for the read-back operation |
+| `pRecord` | `Object\|false` | The marshalled record after update, or `false` on failure |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`doUpdate` executes a four-step asynchronous waterfall:
+
+1. **Validate and prepare** -- Confirms that `pQuery.query.records` exists and
+   that the first record contains the `defaultIdentifier` column (e.g.
+   `IDBook`). The `IDUser` is set automatically from either `pQuery.userID` or
+   `meadow.userIdentifier` when not already present. Schema columns with type
+   `UpdateDate` and `UpdateIDUser` are reset to `false` so the provider can
+   auto-populate them (unless `disableAutoDateStamp` or `disableAutoUserStamp`
+   is set on the query). A filter is added for the primary key value, and a
+   safety check aborts if no filters are present.
+
+2. **Update** -- The provider's `Update` method executes the update query.
+
+3. **Read back** -- The updated record is read from the data source using the
+   same filters. If a `Read` raw query override is set, it is used.
+
+4. **Marshal** -- The raw database row is converted to a plain JavaScript
+   object via `marshalRecordFromSourceToObject`.
+
+## Examples
+
+### Basic update
+
+```javascript
+var tmpQuery = meadow.query
+	.addRecord({ IDBook: 42, Title: 'The Hobbit (Revised)' });
+
+meadow.doUpdate(tmpQuery,
+	function (pError, pUpdateQuery, pReadQuery, pRecord)
+	{
+		if (pError)
+		{
+			console.error('Update failed:', pError);
+			return;
+		}
+		console.log('Updated title:', pRecord.Title);
+	});
+```
+
+### Partial update
+
+```javascript
+// Only update the Author column; other columns are untouched
+var tmpQuery = meadow.query
+	.addRecord({ IDBook: 42, Author: 'J.R.R. Tolkien' });
+
+meadow.doUpdate(tmpQuery,
+	function (pError, pUpdateQuery, pReadQuery, pRecord)
+	{
+		console.log('Full record after update:', pRecord);
+	});
+```
+
+### Update with explicit user ID
+
+```javascript
+var tmpQuery = meadow.query
+	.setIDUser(7)
+	.addRecord({ IDBook: 42, Title: 'Updated Title' });
+
+meadow.doUpdate(tmpQuery,
+	function (pError, pUpdateQuery, pReadQuery, pRecord)
+	{
+		// ModifyingIDUser will be 7
+		console.log(pRecord.ModifyingIDUser);
+	});
+```
+
+## Notes
+
+- The record **must** include the `defaultIdentifier` column (e.g. `IDBook`).
+  Without it, the callback receives `'Automated update missing default
+  identifier'`.
+
+- **Safety check**: If no filters are present on the query after adding the
+  primary key filter, the update is aborted with
+  `'Automated update missing filters... aborting!'`. This prevents accidental
+  updates to every row in the table.
+
+- `Update` raw query overrides are **not** supported. The source notes this
+  feature is deferred due to complexity. However, `Read` raw query overrides
+  **are** used during the read-back step.
+
+- Schema columns with type `UpdateDate` are reset before the update so the
+  provider can populate them with the current timestamp. Columns with type
+  `UpdateIDUser` are reset so the provider can stamp the current user. This
+  automatic behavior can be disabled per-query with `disableAutoDateStamp` and
+  `disableAutoUserStamp`.
+
+- Partial updates are supported. Only the columns present in the record
+  (besides the primary key) are modified. The read-back returns the complete
+  record.

package/docs/api/getRoleName.md

@@ -0,0 +1,84 @@
+# getRoleName
+
+Get the human-readable role name for a numeric role index.
+
+## Signature
+
+```javascript
+meadow.getRoleName(pRoleIndex)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pRoleIndex` | `number` | The zero-based index of the role |
+
+## Returns
+
+| Type | Description |
+|------|-------------|
+| `string` | The role name corresponding to the index |
+
+## Description
+
+`getRoleName` maps a numeric role index to a human-readable role name string.
+If the index is out of range (negative or beyond the array length), it returns
+`'Unauthenticated'`.
+
+## Default Role Names
+
+| Index | Role Name |
+|-------|-----------|
+| 0 | `'Unauthenticated'` |
+| 1 | `'User'` |
+| 2 | `'Manager'` |
+| 3 | `'Director'` |
+| 4 | `'Executive'` |
+| 5 | `'Administrator'` |
+
+## Examples
+
+### Get a role name
+
+```javascript
+console.log(meadow.getRoleName(0)); // 'Unauthenticated'
+console.log(meadow.getRoleName(1)); // 'User'
+console.log(meadow.getRoleName(5)); // 'Administrator'
+```
+
+### Out-of-range index
+
+```javascript
+console.log(meadow.getRoleName(-1));  // 'Unauthenticated'
+console.log(meadow.getRoleName(99));  // 'Unauthenticated'
+```
+
+### Custom role names via Fable settings
+
+```javascript
+var tmpFable = libFable.new({
+	MeadowRoleNames: [
+		'Anonymous',
+		'Reader',
+		'Editor',
+		'Admin',
+		'SuperAdmin'
+	]
+});
+
+var meadow = libMeadow.new(tmpFable, 'Book');
+console.log(meadow.getRoleName(0)); // 'Anonymous'
+console.log(meadow.getRoleName(3)); // 'Admin'
+```
+
+## Notes
+
+- The default role names can be overridden by providing an array as
+  `MeadowRoleNames` in the Fable settings. The array must be provided at
+  Meadow construction time.
+
+- The role names are used by the authorizer system (set via `setAuthorizer`)
+  to map numeric user roles to permission sets.
+
+- If `MeadowRoleNames` is not an array, the default six-role set is used.

package/docs/api/loadFromPackage.md

@@ -0,0 +1,153 @@
+# loadFromPackage / loadFromPackageObject
+
+Load a complete Meadow configuration from a JSON package file or a JavaScript
+object.
+
+## Signatures
+
+```javascript
+meadow.loadFromPackage(pPackage)
+meadow.loadFromPackageObject(pPackage)
+```
+
+## Parameters
+
+### loadFromPackage
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pPackage` | `string` | File path to a JSON package (resolved via `require()`) |
+
+### loadFromPackageObject
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pPackage` | `Object` | A JavaScript object containing the package definition |
+
+## Returns
+
+Returns a **new** Meadow instance configured from the package, or `false` on
+error. This does **not** modify the calling instance.
+
+## Description
+
+These methods create a brand-new Meadow instance and configure it from a
+package definition. The package can contain all of the following properties:
+
+| Property | Type | Method Called |
+|----------|------|--------------|
+| `Scope` | `string` | `setScope()` |
+| `Domain` | `string` | `setDomain()` |
+| `DefaultIdentifier` | `string` | `setDefaultIdentifier()` |
+| `Schema` | `Array` | `setSchema()` |
+| `JsonSchema` | `Object` | `setJsonSchema()` |
+| `DefaultObject` | `Object` | `setDefault()` |
+| `Authorization` | `Object` | `setAuthorizer()` |
+
+`loadFromPackage` uses `require()` to load the file, so relative paths are
+resolved relative to the module. `loadFromPackageObject` takes the object
+directly.
+
+The new Meadow instance inherits the Fable context from the calling instance.
+
+## Package File Format
+
+```json
+{
+	"Scope": "Book",
+	"Domain": "Library",
+	"DefaultIdentifier": "IDBook",
+	"Schema": [
+		{ "Column": "IDBook", "Type": "AutoIdentity" },
+		{ "Column": "GUIDBook", "Type": "AutoGUID" },
+		{ "Column": "Title", "Type": "String", "Size": "256" },
+		{ "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" }
+	],
+	"JsonSchema": {
+		"title": "Book",
+		"type": "object",
+		"properties": {
+			"Title": { "type": "string" }
+		},
+		"required": ["Title"]
+	},
+	"DefaultObject": {
+		"IDBook": 0,
+		"GUIDBook": "",
+		"Title": ""
+	},
+	"Authorization": {
+		"User": {
+			"Create": "Allow",
+			"Read": "Allow",
+			"Update": "Allow",
+			"Delete": "Allow"
+		}
+	}
+}
+```
+
+## Examples
+
+### Load from a file path
+
+```javascript
+var tmpBookMeadow = libMeadow.new(tmpFable)
+	.loadFromPackage(__dirname + '/schemas/Book.json');
+
+if (!tmpBookMeadow)
+{
+	console.error('Failed to load package');
+}
+else
+{
+	console.log(tmpBookMeadow.scope); // 'Book'
+}
+```
+
+### Load from a JavaScript object
+
+```javascript
+var tmpPackage = {
+	Scope: 'Author',
+	DefaultIdentifier: 'IDAuthor',
+	Schema: [
+		{ Column: 'IDAuthor', Type: 'AutoIdentity' },
+		{ Column: 'GUIDAuthor', Type: 'AutoGUID' },
+		{ Column: 'Name', Type: 'String', Size: '128' }
+	],
+	DefaultObject: {
+		IDAuthor: 0,
+		GUIDAuthor: '',
+		Name: ''
+	}
+};
+
+var tmpAuthorMeadow = libMeadow.new(tmpFable)
+	.loadFromPackageObject(tmpPackage);
+
+console.log(tmpAuthorMeadow.scope); // 'Author'
+```
+
+## Notes
+
+- Both methods return a **new** Meadow instance. They do not modify the
+  calling instance. Assign the return value to use the configured instance.
+
+- `loadFromPackage` returns `false` if the `require()` call fails (file not
+  found, JSON parse error, etc.). An error is logged via the Fable logger.
+
+- `loadFromPackageObject` logs a warning if the object does not have a `Scope`
+  property but still creates the new instance.
+
+- All package properties are optional. Only properties present in the package
+  are applied to the new instance.
+
+- The new instance inherits the Fable context (and therefore the provider
+  setting from `MeadowProvider` in Fable settings) from the calling instance.

package/docs/api/marshalRecordFromSourceToObject.md

@@ -0,0 +1,92 @@
+# marshalRecordFromSourceToObject
+
+Convert a raw database record into a plain JavaScript object using the schema
+and default object template.
+
+## Signature
+
+```javascript
+meadow.marshalRecordFromSourceToObject(pRecord)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pRecord` | `Object` | A raw database record as returned by the provider |
+
+## Returns
+
+| Type | Description |
+|------|-------------|
+| `Object` | A plain JavaScript object with all schema columns populated |
+
+## Description
+
+`marshalRecordFromSourceToObject` performs a two-step conversion:
+
+1. **Clone the default object** -- Creates a shallow copy of the default object
+   template (set via `setDefault`), ensuring all schema columns have initial
+   values.
+
+2. **Overlay provider values** -- Calls the active provider's
+   `marshalRecordFromSourceToObject` method to map raw database values onto
+   the cloned object according to the column schema.
+
+This guarantees a consistent object shape regardless of what the database
+returned. Missing or null columns fall back to the default values.
+
+## Examples
+
+### Basic usage
+
+```javascript
+// Assume a raw database row from the provider
+var tmpRawRow = {
+	IDBook: 42,
+	GUIDBook: '0xABCDE-12345',
+	Title: 'Dune',
+	Author: 'Herbert',
+	PageCount: 412,
+	Created: '2024-01-15T10:30:00Z',
+	CreatingIDUser: 1,
+	Modified: null,
+	ModifyingIDUser: null,
+	Deleted: 0,
+	DeletingIDUser: 0,
+	DeleteDate: null
+};
+
+var tmpRecord = meadow.marshalRecordFromSourceToObject(tmpRawRow);
+console.log(tmpRecord.Title);     // 'Dune'
+console.log(tmpRecord.Modified);  // '' (from default, since DB returned null)
+```
+
+### Used internally by CRUD methods
+
+```javascript
+// You typically do not call this directly.
+// It is called automatically by doCreate, doRead, doReads, and doUpdate
+// when marshalling results back to the caller.
+
+meadow.doRead(tmpQuery,
+	function (pError, pQuery, pRecord)
+	{
+		// pRecord has already been marshalled
+		console.log(pRecord);
+	});
+```
+
+## Notes
+
+- This method is called internally by `doCreate`, `doRead`, `doReads`, and
+  `doUpdate`. Direct use is uncommon but available for custom scenarios.
+
+- The returned object is a new plain object, not a reference to the default
+  object or the original database row.
+
+- The provider's marshalling logic handles type-specific conversions (e.g.,
+  date formatting, numeric parsing) depending on the database backend.
+
+- If `setDefault` has not been called, the base object is an empty `{}` and
+  only columns present in the database row will appear on the result.

package/docs/api/query.md

@@ -0,0 +1,133 @@
+# query (Property)
+
+Access a fresh, cloned FoxHound query object pre-configured with the current
+scope and schema.
+
+## Signature
+
+```javascript
+var tmpQuery = meadow.query;
+```
+
+## Returns
+
+| Type | Description |
+|------|-------------|
+| `Object` | A cloned FoxHound query with scope and schema pre-set |
+
+## Description
+
+The `query` property returns a **new clone** of the internal FoxHound query
+every time it is accessed. This ensures that each query operation gets an
+independent query object with no shared mutable state.
+
+The cloned query inherits:
+
+- The current **scope** (table name)
+- The current **schema** (column definitions)
+- Any **filters**, **cap**, **begin**, and **data elements** from the base
+  query (these are cloned values, not references)
+
+Because each access creates a fresh clone, it is safe to write:
+
+```javascript
+var tmpQuery = meadow.query;
+```
+
+without worrying about leakage between subsequent queries.
+
+## Key Methods on the Returned Query
+
+| Method | Description |
+|--------|-------------|
+| `addFilter(pColumn, pValue, pOperator, pConnector, pType)` | Add a WHERE filter |
+| `addRecord(pRecord)` | Add a record for Create/Update operations |
+| `setCap(pCap)` | Set the maximum number of records (LIMIT) |
+| `setBegin(pBegin)` | Set the starting offset (OFFSET) |
+| `addSort(pSort)` | Add a sort clause (e.g. `{ Column: 'Title', Direction: 'ASC' }`) |
+| `setDataElements(pDataElements)` | Set which columns to return (SELECT list) |
+| `setDistinct(pDistinct)` | Enable DISTINCT on the query |
+| `setDisableDeleteTracking(pDisable)` | Include soft-deleted records when `true` |
+| `setIDUser(pIDUser)` | Set the user ID on the query |
+| `clone()` | Create another independent clone of this query |
+
+## Examples
+
+### Basic query for a read
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('IDBook', 42);
+
+meadow.doRead(tmpQuery,
+	function (pError, pQuery, pRecord)
+	{
+		console.log(pRecord);
+	});
+```
+
+### Query with pagination and sorting
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('Author', 'Tolkien')
+	.setCap(25)
+	.setBegin(0)
+	.addSort({ Column: 'Title', Direction: 'ASC' });
+
+meadow.doReads(tmpQuery,
+	function (pError, pQuery, pRecords)
+	{
+		console.log(pRecords.length, 'results');
+	});
+```
+
+### Query with specific columns
+
+```javascript
+var tmpQuery = meadow.query
+	.setDataElements(['IDBook', 'Title', 'Author']);
+
+meadow.doReads(tmpQuery,
+	function (pError, pQuery, pRecords)
+	{
+		console.log(pRecords);
+	});
+```
+
+### Query for create with a record
+
+```javascript
+var tmpQuery = meadow.query
+	.addRecord({ Title: 'Dune', Author: 'Herbert' });
+
+meadow.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		console.log('New ID:', pRecord.IDBook);
+	});
+```
+
+### Independent queries from the same meadow
+
+```javascript
+var tmpQueryA = meadow.query.addFilter('IDBook', 1);
+var tmpQueryB = meadow.query.addFilter('IDBook', 2);
+
+// tmpQueryA and tmpQueryB are completely independent
+// Modifying one does not affect the other
+```
+
+## Notes
+
+- Every access to `meadow.query` creates a new clone. Do not access it in a
+  loop if you need the same query object -- assign it to a variable first.
+
+- The query object is a FoxHound instance. See the FoxHound documentation for
+  the full query API.
+
+- The schema is attached to the cloned query at `tmpQuery.query.schema`, which
+  providers use for query generation.
+
+- Filters, cap, begin, and data elements survive cloning. Records do not
+  survive cloning by default.