meadow 2.0.23 → 2.0.27

package/docs/_sidebar.md

@@ -1,22 +1,21 @@
 - Getting Started
 
   - [Introduction](/)
+  - [Quick Start](quick-start.md)
   - [Architecture](architecture.md)
+  - [Configuration](configuration.md)
 
 - Core Concepts
 
   - [Schema](schema/README.md)
-  - [CRUD Operations](crud-operations.md)
   - [Query DSL](query-dsl.md)
   - [Raw Queries](raw-queries.md)
+  - [Audit Tracking](audit-tracking.md)
+  - [Soft Deletes](soft-deletes.md)
 
-- Schema
-
-  - [Schema Overview](schema/README.md)
-
-- Query Operations
+- CRUD Operations
 
-  - [Query Overview](query/README.md)
+  - [Overview](query/README.md)
   - [Create](query/create.md)
   - [Read](query/read.md)
   - [Update](query/update.md)
@@ -25,14 +24,47 @@
 
 - Providers
 
-  - [Providers Overview](providers/README.md)
+  - [Overview](providers/README.md)
   - [MySQL](providers/mysql.md)
   - [MSSQL](providers/mssql.md)
+  - [PostgreSQL](providers/postgresql.md)
   - [SQLite](providers/sqlite.md)
+  - [MongoDB](providers/mongodb.md)
+  - [RocksDB](providers/rocksdb.md)
   - [ALASQL](providers/alasql.md)
+  - [MeadowEndpoints](providers/meadow-endpoints.md)
 
-- Advanced
+- API Reference
 
-  - [Audit Tracking](audit-tracking.md)
-  - [Soft Deletes](soft-deletes.md)
-  - [Configuration Reference](configuration.md)
+  - [Overview](api/reference.md)
+
+  - CRUD Methods
+
+    - [doCreate()](api/doCreate.md)
+    - [doRead()](api/doRead.md)
+    - [doReads()](api/doReads.md)
+    - [doUpdate()](api/doUpdate.md)
+    - [doDelete()](api/doDelete.md)
+    - [doUndelete()](api/doUndelete.md)
+    - [doCount()](api/doCount.md)
+
+  - Configuration
+
+    - [setProvider()](api/setProvider.md)
+    - [setScope()](api/setScope.md)
+    - [setSchema()](api/setSchema.md)
+    - [setDefaultIdentifier()](api/setDefaultIdentifier.md)
+    - [setIDUser()](api/setIDUser.md)
+    - [setJsonSchema()](api/setJsonSchema.md)
+    - [setDefault()](api/setDefault.md)
+    - [setAuthorizer()](api/setAuthorizer.md)
+    - [setDomain()](api/setDomain.md)
+    - [loadFromPackage()](api/loadFromPackage.md)
+
+  - Utility
+
+    - [query (property)](api/query.md)
+    - [rawQueries](api/rawQueries.md)
+    - [validateObject()](api/validateObject.md)
+    - [marshalRecordFromSourceToObject()](api/marshalRecordFromSourceToObject.md)
+    - [getRoleName()](api/getRoleName.md)

package/docs/_topbar.md

@@ -0,0 +1,5 @@
+[Home](/)
+[Quick Start](quick-start.md)
+[Schema](schema/README.md)
+[API Reference](api/reference.md)
+[GitHub](https://github.com/stevenvelozo/meadow)

package/docs/api/doCount.md

@@ -0,0 +1,109 @@
+# doCount
+
+Count records matching the query filters.
+
+## Signature
+
+```javascript
+meadow.doCount(pQuery, fCallBack)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQuery` | `Object` | A FoxHound query object with optional filters |
+| `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 count operation |
+| `pCount` | `number\|false` | The integer count of matching records, or `false` on failure |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`doCount` executes a two-step asynchronous waterfall:
+
+1. **Count** -- If a `Count` raw query override is set via
+   `rawQueries.setQuery('Count', ...)`, it is used. Otherwise, the provider's
+   `Count` method executes the query.
+
+2. **Validate and profile** -- The result is verified to be a number. If the
+   provider returned a non-numeric value, the callback receives
+   `'Count did not return valid results.'`. The elapsed time is checked against
+   the `QueryThresholdWarnTime` setting (default 200ms). If the query exceeded
+   the threshold, `logSlowQuery` emits a warning.
+
+Soft-deleted records are excluded by default unless delete tracking is disabled
+on the query.
+
+## Examples
+
+### Count all records
+
+```javascript
+var tmpQuery = meadow.query;
+
+meadow.doCount(tmpQuery,
+	function (pError, pQuery, pCount)
+	{
+		if (pError)
+		{
+			console.error('Count error:', pError);
+			return;
+		}
+		console.log('Total books:', pCount);
+	});
+```
+
+### Count with filters
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('Author', 'Tolkien');
+
+meadow.doCount(tmpQuery,
+	function (pError, pQuery, pCount)
+	{
+		console.log('Books by Tolkien:', pCount);
+	});
+```
+
+### Count including soft-deleted records
+
+```javascript
+var tmpQuery = meadow.query
+	.setDisableDeleteTracking(true);
+
+meadow.doCount(tmpQuery,
+	function (pError, pQuery, pCount)
+	{
+		console.log('Total including deleted:', pCount);
+	});
+```
+
+## Notes
+
+- The `Count` raw query override applies to this method. Set it via
+  `meadow.rawQueries.setQuery('Count', pQueryString)`.
+
+- Slow query profiling measures elapsed wall time from the start of `doCount`
+  through provider completion. The threshold defaults to 200ms and can be
+  configured via the `QueryThresholdWarnTime` Fable setting.
+
+- The result is always an integer. If the provider returns a non-number, the
+  callback receives an error and `pCount` is `false`.
+
+- Soft-deleted records are excluded by default. Use
+  `setDisableDeleteTracking(true)` on the query to include them in the count.

package/docs/api/doCreate.md

@@ -0,0 +1,132 @@
+# doCreate
+
+Insert a new record into the data source, read it back, and return the
+marshalled result.
+
+## Signature
+
+```javascript
+meadow.doCreate(pQuery, fCallBack)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQuery` | `Object` | A FoxHound query object with at least one record added via `addRecord()` |
+| `fCallBack` | `Function` | Callback invoked when the operation completes |
+
+## Callback
+
+```javascript
+function (pError, pCreateQuery, pReadQuery, pRecord)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pError` | `string\|null` | Error message, or falsy on success |
+| `pCreateQuery` | `Object` | The FoxHound query used for the INSERT operation |
+| `pReadQuery` | `Object` | The FoxHound query used for the read-back operation |
+| `pRecord` | `Object\|false` | The marshalled record, or `false` on failure |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`doCreate` executes a four-step asynchronous waterfall:
+
+1. **GUID uniqueness check** -- If the record contains a GUID column value
+   (the `defaultGUIdentifier`, e.g. `GUIDBook`) that is at least 5 characters
+   long, Meadow reads the data source to confirm no existing record has that
+   GUID. If a duplicate is found, the callback receives an error.
+
+2. **Insert** -- The record is merged with the default object template so that
+   all schema columns have values. The `IDUser` is set automatically from
+   either `pQuery.userID` or `meadow.userIdentifier` when not already present
+   on the query. The provider's `Create` method executes the insert.
+
+3. **Read back** -- After a successful insert, the newly created record is read
+   from the data source using the returned primary key value. If a `Read` raw
+   query override is set, it is used for this step.
+
+4. **Marshal** -- The raw database row is converted to a plain JavaScript
+   object via `marshalRecordFromSourceToObject`.
+
+## Examples
+
+### Basic create
+
+```javascript
+var tmpQuery = meadow.query
+	.addRecord({ Title: 'The Hobbit', Author: 'Tolkien' });
+
+meadow.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		if (pError)
+		{
+			console.error('Create failed:', pError);
+			return;
+		}
+		console.log('New record ID:', pRecord.IDBook);
+	});
+```
+
+### Create with a specific GUID
+
+```javascript
+var tmpQuery = meadow.query
+	.addRecord({
+		GUIDBook: '0x12345-abcde-67890',
+		Title: 'Dune'
+	});
+
+meadow.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		if (pError)
+		{
+			// Error if GUID already exists
+			console.error(pError);
+			return;
+		}
+		console.log('Created with GUID:', pRecord.GUIDBook);
+	});
+```
+
+### Create with explicit user ID on the query
+
+```javascript
+var tmpQuery = meadow.query
+	.setIDUser(42)
+	.addRecord({ Title: 'Neuromancer' });
+
+meadow.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		// CreatingIDUser will be 42
+		console.log(pRecord);
+	});
+```
+
+## Notes
+
+- The query **must** have a record added via `addRecord()` before calling
+  `doCreate`. If `pQuery.query.records` is falsy, the callback receives
+  `'No record submitted'`.
+
+- GUID uniqueness is only checked when the GUID value is at least 5 characters
+  long. Shorter values or empty strings skip the check.
+
+- The default object template (set via `setDefault`) is merged into the record
+  before insert, ensuring all schema columns have initial values.
+
+- `Create` raw query overrides are **not** supported. The comment in the source
+  notes that create overrides are too complex. However, `Read` raw query
+  overrides **are** used during the read-back step.
+
+- The `IDUser` resolution order is: `pQuery.query.IDUser` (if already set) >
+  `pQuery.userID` (if a non-negative integer) > `meadow.userIdentifier`
+  (fallback).

package/docs/api/doDelete.md

@@ -0,0 +1,101 @@
+# doDelete
+
+Delete a record from the data source. Uses soft delete when the schema includes
+a `Deleted` column, otherwise performs a hard delete.
+
+## Signature
+
+```javascript
+meadow.doDelete(pQuery, fCallBack)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQuery` | `Object` | A FoxHound query object with filters identifying the record(s) to delete |
+| `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 delete operation |
+| `pCount` | `number` | The number of affected records |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`doDelete` executes a single-step asynchronous waterfall:
+
+1. **Delete** -- If a `Delete` raw query override is set via
+   `rawQueries.setQuery('Delete', ...)`, it is used. Otherwise, the provider's
+   `Delete` method executes the query. The provider determines the actual SQL
+   based on the schema:
+
+   - **Soft delete**: If the schema contains a column with type `Deleted`, the
+     provider issues `UPDATE {Scope} SET Deleted=1, DeleteDate=NOW(),
+     DeletingIDUser={IDUser} WHERE ...`.
+   - **Hard delete**: If no `Deleted` column exists, the provider issues
+     `DELETE FROM {Scope} WHERE ...`.
+
+## Examples
+
+### Delete by primary key
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('IDBook', 42);
+
+meadow.doDelete(tmpQuery,
+	function (pError, pQuery, pCount)
+	{
+		if (pError)
+		{
+			console.error('Delete failed:', pError);
+			return;
+		}
+		console.log('Deleted', pCount, 'record(s)');
+	});
+```
+
+### Delete with a custom raw query
+
+```javascript
+meadow.rawQueries.setQuery('Delete',
+	'UPDATE Book SET Deleted=1, DeleteDate=NOW() WHERE IDBook = :IDBook AND OwnerIDUser = :IDUser');
+
+var tmpQuery = meadow.query
+	.addFilter('IDBook', 42);
+
+meadow.doDelete(tmpQuery,
+	function (pError, pQuery, pCount)
+	{
+		console.log('Custom delete affected', pCount, 'record(s)');
+	});
+```
+
+## Notes
+
+- Soft delete is automatic when the schema includes `{ Column: 'Deleted',
+  Type: 'Deleted' }`. No configuration is needed beyond the schema definition.
+
+- After a soft delete, the record still exists in the database with
+  `Deleted = 1`. Subsequent `doRead` and `doReads` calls will exclude it by
+  default (unless `setDisableDeleteTracking(true)` is set on the query).
+
+- Use [doUndelete](doUndelete.md) to restore a soft-deleted record.
+
+- The `Delete` raw query override applies to this method. Set it via
+  `meadow.rawQueries.setQuery('Delete', pQueryString)`.
+
+- Hard deletes are irreversible. Only schemas without a `Deleted` column
+  trigger hard deletes.

package/docs/api/doRead.md

@@ -0,0 +1,122 @@
+# doRead
+
+Read a single record from the data source and return it as a marshalled plain
+object.
+
+## Signature
+
+```javascript
+meadow.doRead(pQuery, fCallBack)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQuery` | `Object` | A FoxHound query object with filters set to identify the target record |
+| `fCallBack` | `Function` | Callback invoked when the operation completes |
+
+## Callback
+
+```javascript
+function (pError, pQuery, pRecord)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pError` | `string\|null` | Error message, or falsy on success |
+| `pQuery` | `Object` | The FoxHound query used for the read operation |
+| `pRecord` | `Object\|false` | The marshalled record, or `false` if no record was found |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`doRead` executes a two-step asynchronous waterfall:
+
+1. **Read** -- The provider's `Read` method executes the query. If a `Read`
+   raw query override is set via `rawQueries.setQuery('Read', ...)`, it is
+   used instead of the auto-generated query.
+
+2. **Marshal** -- If at least one record is returned, the first row is
+   converted to a plain JavaScript object via `marshalRecordFromSourceToObject`.
+   If no rows match, `pRecord` is `false` (not an error).
+
+Soft-deleted records (those with `Deleted = 1`) are excluded by default unless
+delete tracking has been explicitly disabled on the query via
+`setDisableDeleteTracking(true)`.
+
+## Examples
+
+### Read by primary key
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('IDBook', 42);
+
+meadow.doRead(tmpQuery,
+	function (pError, pQuery, pRecord)
+	{
+		if (pError)
+		{
+			console.error('Read error:', pError);
+			return;
+		}
+		if (!pRecord)
+		{
+			console.log('No record found');
+			return;
+		}
+		console.log('Title:', pRecord.Title);
+	});
+```
+
+### Read by GUID
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('GUIDBook', '0x12345-abcde-67890');
+
+meadow.doRead(tmpQuery,
+	function (pError, pQuery, pRecord)
+	{
+		if (pRecord)
+		{
+			console.log('Found:', pRecord.Title);
+		}
+	});
+```
+
+### Read including soft-deleted records
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('IDBook', 99)
+	.setDisableDeleteTracking(true);
+
+meadow.doRead(tmpQuery,
+	function (pError, pQuery, pRecord)
+	{
+		if (pRecord)
+		{
+			console.log('Deleted?', pRecord.Deleted);
+		}
+	});
+```
+
+## Notes
+
+- When no record is found, `pRecord` is `false` and `pError` is `undefined`
+  (not an error condition). Always check for a falsy record.
+
+- `doRead` returns only the **first** matching record. To read multiple records,
+  use [doReads](doReads.md).
+
+- The `Read` raw query override applies to this method. Set it via
+  `meadow.rawQueries.setQuery('Read', pQueryString)`.
+
+- The returned object is built from the default object template overlaid with
+  provider-marshalled values, so all schema columns are present even if the
+  database row has nulls.

package/docs/api/doReads.md

@@ -0,0 +1,136 @@
+# doReads
+
+Read multiple records from the data source and return them as an array of
+marshalled plain objects.
+
+## Signature
+
+```javascript
+meadow.doReads(pQuery, fCallBack)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pQuery` | `Object` | A FoxHound query object with filters, pagination, and sort options |
+| `fCallBack` | `Function` | Callback invoked when the operation completes |
+
+## Callback
+
+```javascript
+function (pError, pQuery, pRecords)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pError` | `string\|null` | Error message, or falsy on success |
+| `pQuery` | `Object` | The FoxHound query used for the read operation |
+| `pRecords` | `Array` | Array of marshalled record objects (empty array if none found) |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`doReads` executes a two-step asynchronous waterfall:
+
+1. **Read** -- The provider's `Read` method executes the query. If a `Reads`
+   raw query override is set via `rawQueries.setQuery('Reads', ...)`, it is
+   used instead of the auto-generated query.
+
+2. **Marshal and profile** -- Each returned row is converted to a plain
+   JavaScript object via `marshalRecordFromSourceToObject` and pushed into an
+   array. After the provider returns, the elapsed time is checked against the
+   `QueryThresholdWarnTime` setting (default 200ms). If the query exceeded the
+   threshold, `logSlowQuery` emits a warning.
+
+Soft-deleted records are excluded by default unless delete tracking is disabled
+on the query.
+
+## Examples
+
+### Read all records (with default cap)
+
+```javascript
+var tmpQuery = meadow.query;
+
+meadow.doReads(tmpQuery,
+	function (pError, pQuery, pRecords)
+	{
+		if (pError)
+		{
+			console.error('Reads error:', pError);
+			return;
+		}
+		console.log('Found', pRecords.length, 'records');
+		pRecords.forEach(function (pRecord)
+		{
+			console.log('-', pRecord.Title);
+		});
+	});
+```
+
+### Read with filters and pagination
+
+```javascript
+var tmpQuery = meadow.query
+	.addFilter('Author', 'Tolkien')
+	.setCap(10)
+	.setBegin(0)
+	.addSort({ Column: 'Title', Direction: 'ASC' });
+
+meadow.doReads(tmpQuery,
+	function (pError, pQuery, pRecords)
+	{
+		console.log('Page 1:', pRecords.length, 'results');
+	});
+```
+
+### Read with specific data elements
+
+```javascript
+var tmpQuery = meadow.query
+	.setDataElements(['IDBook', 'Title', 'Author']);
+
+meadow.doReads(tmpQuery,
+	function (pError, pQuery, pRecords)
+	{
+		// Each record will have only the requested columns
+		// (plus any columns derived from the default object)
+		console.log(pRecords);
+	});
+```
+
+### Read with custom slow query threshold
+
+```javascript
+// In Fable settings:
+// { QueryThresholdWarnTime: 500 }
+
+var tmpQuery = meadow.query
+	.addFilter('Genre', 'Fantasy');
+
+meadow.doReads(tmpQuery,
+	function (pError, pQuery, pRecords)
+	{
+		// Queries taking longer than 500ms will trigger a warning log
+		console.log(pRecords.length, 'records');
+	});
+```
+
+## Notes
+
+- The `Reads` raw query override is **separate** from the `Read` override. Set
+  it via `meadow.rawQueries.setQuery('Reads', pQueryString)`.
+
+- Slow query profiling measures elapsed wall time from the start of `doReads`
+  through provider completion. The threshold defaults to 200ms and can be
+  configured via the `QueryThresholdWarnTime` Fable setting.
+
+- Each record in the result array is independently marshalled through the
+  default object template, so all schema columns are present on every record.
+
+- An empty result set returns an empty array `[]`, not `false`. This differs
+  from `doRead` which returns `false` for no results.