meadow 2.0.23 → 2.0.27

package/docs/api/setIDUser.md

@@ -0,0 +1,91 @@
+# setIDUser
+
+Set the user ID used for create, update, and delete audit stamps.
+
+## Signature
+
+```javascript
+meadow.setIDUser(pIDUser)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pIDUser` | `number` | The user ID to stamp on records |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setIDUser` sets the fallback user ID that Meadow uses when stamping audit
+columns (`CreatingIDUser`, `ModifyingIDUser`, `DeletingIDUser`) during create,
+update, and delete operations.
+
+The user ID resolution order for CRUD operations is:
+
+1. `pQuery.query.IDUser` -- if already set directly on the query
+2. `pQuery.userID` -- if set on the query and is a non-negative integer
+3. `meadow.userIdentifier` -- the fallback value set by `setIDUser`
+
+The default value is `0`.
+
+## Examples
+
+### Set a global user ID
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book')
+	.setIDUser(42);
+
+console.log(meadow.userIdentifier); // 42
+```
+
+### Override per-query
+
+```javascript
+meadow.setIDUser(1); // Default user
+
+// This query uses user 99 instead
+var tmpQuery = meadow.query
+	.setIDUser(99)
+	.addRecord({ Title: 'Dune' });
+
+meadow.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		// CreatingIDUser will be 99, not 1
+		console.log(pRecord.CreatingIDUser);
+	});
+```
+
+### Typical use in a web server
+
+```javascript
+// In a request handler, set the user from the session
+app.get('/api/Books',
+	function (pRequest, pResponse)
+	{
+		var tmpMeadow = meadow.setIDUser(pRequest.session.UserID);
+		var tmpQuery = tmpMeadow.query;
+
+		tmpMeadow.doReads(tmpQuery,
+			function (pError, pQuery, pRecords)
+			{
+				pResponse.send(pRecords);
+			});
+	});
+```
+
+## Notes
+
+- The value set by `setIDUser` is accessible via the `userIdentifier`
+  read-only property.
+
+- `setIDUser` sets a fallback. If the query already has `IDUser` set, the
+  query-level value takes precedence.
+
+- The default value is `0`, which typically represents an unauthenticated or
+  system user.

package/docs/api/setJsonSchema.md

@@ -0,0 +1,92 @@
+# setJsonSchema
+
+Set the JSON Schema used for object validation.
+
+## Signature
+
+```javascript
+meadow.setJsonSchema(pJsonSchema)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pJsonSchema` | `Object` | A JSON Schema (draft-04) object |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setJsonSchema` replaces the current JSON Schema and creates a new validator
+using the `is-my-json-valid` library with `greedy` and `verbose` modes enabled.
+
+- **greedy**: The validator checks all properties rather than stopping at the
+  first error.
+- **verbose**: Error objects include the full path and value of the failing
+  property.
+
+Once set, use `validateObject(pObject)` to validate records against the schema.
+
+## Examples
+
+### Set a JSON Schema
+
+```javascript
+meadow.setJsonSchema({
+	"$schema": "http://json-schema.org/draft-04/schema#",
+	"title": "Book",
+	"type": "object",
+	"properties": {
+		"Title": {
+			"type": "string",
+			"minLength": 1
+		},
+		"Author": {
+			"type": "string"
+		},
+		"PageCount": {
+			"type": "integer",
+			"minimum": 1
+		}
+	},
+	"required": ["Title"]
+});
+```
+
+### Validate after setting
+
+```javascript
+var tmpResult = meadow.validateObject({ Title: 'Dune', PageCount: 412 });
+console.log(tmpResult.Valid); // true
+
+var tmpBad = meadow.validateObject({ PageCount: -5 });
+console.log(tmpBad.Valid);  // false
+console.log(tmpBad.Errors); // Array of error details
+```
+
+### Chain with other configuration
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book')
+	.setSchema(bookSchema)
+	.setJsonSchema(bookJsonSchema)
+	.setDefault(bookDefaultObject);
+```
+
+## Notes
+
+- If `pJsonSchema` is not an object, a minimal fallback schema is used:
+  `{ title: 'Unknown', type: 'object', required: [] }`.
+
+- The JSON Schema is separate from the column schema (set via `setSchema`).
+  The column schema drives query generation and marshalling. The JSON Schema
+  drives object validation.
+
+- The JSON Schema is accessible via the `jsonSchema` read-only property.
+
+- Validation uses JSON Schema draft-04. See
+  [json-schema.org](http://json-schema.org/draft-04/schema#) for the
+  specification.

package/docs/api/setProvider.md

@@ -0,0 +1,87 @@
+# setProvider
+
+Set the database provider used for query execution.
+
+## Signature
+
+```javascript
+meadow.setProvider(pProviderName)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pProviderName` | `string` | The name of the database provider |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setProvider` loads a database provider module by name and binds it to the
+Meadow instance. After loading, it calls `updateProviderState()` to synchronize
+the current scope, schema, and identifier settings with the new provider.
+
+If `pProviderName` is not a string, or if the provider module fails to load,
+Meadow falls back to the `'None'` provider and logs an error.
+
+The provider is also initialized during Meadow construction from the
+`MeadowProvider` Fable setting (default `'None'`).
+
+## Valid Provider Names
+
+| Provider | Description |
+|----------|-------------|
+| `'MySQL'` | MySQL / MariaDB |
+| `'MSSQL'` | Microsoft SQL Server |
+| `'PostgreSQL'` | PostgreSQL |
+| `'SQLite'` | SQLite |
+| `'MongoDB'` | MongoDB |
+| `'RocksDB'` | RocksDB |
+| `'DGraph'` | Dgraph |
+| `'Solr'` | Apache Solr |
+| `'ALASQL'` | AlaSQL (in-memory / browser) |
+| `'MeadowEndpoints'` | Remote Meadow REST endpoints |
+| `'None'` | No-op provider (default) |
+
+## Examples
+
+### Set provider explicitly
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book')
+	.setProvider('MySQL');
+```
+
+### Set provider via Fable settings
+
+```javascript
+var tmpFable = libFable.new({ MeadowProvider: 'PostgreSQL' });
+var meadow = libMeadow.new(tmpFable, 'Book');
+// Provider is already PostgreSQL from settings
+```
+
+### Chain with other configuration
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book')
+	.setProvider('MySQL')
+	.setSchema(bookSchema)
+	.setDefaultIdentifier('IDBook');
+```
+
+## Notes
+
+- Provider names are **case sensitive**. `'MySQL'` is valid; `'mysql'` is not.
+
+- When a provider fails to load, Meadow logs the error and silently falls back
+  to `'None'`. The `'None'` provider is a no-op that does not execute any
+  database operations.
+
+- Changing the provider calls `updateProviderState()`, which passes the current
+  scope, schema, default identifier, and GUID identifier to the new provider.
+
+- The provider can be changed at any time, but in practice it is typically set
+  once during initialization.

package/docs/api/setSchema.md

@@ -0,0 +1,107 @@
+# setSchema
+
+Set the column schema array for this Meadow instance.
+
+## Signature
+
+```javascript
+meadow.setSchema(pSchema)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pSchema` | `Array` | An array of schema column definition objects |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setSchema` replaces the current column schema with a new array of column
+definitions. Each element describes a column and its behavior during CRUD
+operations. After setting the schema, `updateProviderState()` is called to
+synchronize the schema with the active provider.
+
+## Schema Column Object
+
+Each element in the schema array is an object with the following properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `Column` | `string` | Yes | The column name |
+| `Type` | `string` | Yes | The column type (see below) |
+| `Size` | `string` | No | Size constraint (e.g. `'128'` for VARCHAR(128)) |
+
+## Column Types
+
+| Type | Description |
+|------|-------------|
+| `AutoIdentity` | Auto-incrementing primary key |
+| `AutoGUID` | Automatically generated GUID |
+| `CreateDate` | Timestamp set on record creation |
+| `CreateIDUser` | User ID stamped on record creation |
+| `UpdateDate` | Timestamp set on record update |
+| `UpdateIDUser` | User ID stamped on record update |
+| `Deleted` | Soft-delete flag (0 or 1) |
+| `DeleteIDUser` | User ID stamped on soft delete |
+| `DeleteDate` | Timestamp set on soft delete |
+| `String` | String/VARCHAR column |
+| `Number` | Numeric column |
+| `DateTime` | Date/time column |
+
+## Examples
+
+### Full schema definition
+
+```javascript
+meadow.setSchema([
+	{ Column: 'IDBook', Type: 'AutoIdentity' },
+	{ Column: 'GUIDBook', Type: 'AutoGUID' },
+	{ Column: 'Title', Type: 'String', Size: '256' },
+	{ Column: 'Author', Type: 'String', Size: '128' },
+	{ Column: 'PageCount', Type: 'Number' },
+	{ 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' }
+]);
+```
+
+### Minimal schema without soft delete
+
+```javascript
+meadow.setSchema([
+	{ Column: 'IDWidget', Type: 'AutoIdentity' },
+	{ Column: 'GUIDWidget', Type: 'AutoGUID' },
+	{ Column: 'Name', Type: 'String', Size: '64' }
+]);
+```
+
+### Access the schema after setting it
+
+```javascript
+console.log(meadow.schema);
+// [{ Column: 'IDBook', Type: 'AutoIdentity' }, ...]
+```
+
+## Notes
+
+- If `pSchema` is not an object, the schema falls back to a minimal default:
+  `{ title: 'Unknown', type: 'object', required: [] }`.
+
+- The schema determines whether soft delete or hard delete is used. If the
+  schema contains a column with `Type: 'Deleted'`, all `doDelete` calls perform
+  soft deletes.
+
+- The schema is passed to the provider via `updateProviderState()` so the
+  provider can use it for query generation and marshalling.
+
+- The `schema` property returns the raw schema array. The `schemaFull` property
+  returns the full Meadow-Schema object which includes `validateObject`,
+  `defaultObject`, and `authorizer`.

package/docs/api/setScope.md

@@ -0,0 +1,68 @@
+# setScope
+
+Set the entity scope (table name) for this Meadow instance.
+
+## Signature
+
+```javascript
+meadow.setScope(pScope)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pScope` | `string` | The entity scope, typically a database table name (e.g. `'Book'`) |
+
+## Returns
+
+Returns the Meadow instance for chaining.
+
+## Description
+
+`setScope` updates the internal scope and synchronizes it with the FoxHound
+query object and the active provider. The scope is used as the table name (or
+collection name) in generated queries.
+
+The scope is also set during construction via the second argument to
+`libMeadow.new(pFable, pScope)`. If no scope is provided at construction time,
+it defaults to `'Unknown'`.
+
+## Examples
+
+### Set scope at construction
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book');
+console.log(meadow.scope); // 'Book'
+```
+
+### Change scope after construction
+
+```javascript
+var meadow = libMeadow.new(tmpFable, 'Book');
+meadow.setScope('Author');
+console.log(meadow.scope); // 'Author'
+```
+
+### Chain with other configuration
+
+```javascript
+var meadow = libMeadow.new(tmpFable)
+	.setScope('Book')
+	.setSchema(bookSchema)
+	.setProvider('MySQL');
+```
+
+## Notes
+
+- Changing the scope calls `updateProviderState()` to synchronize the new scope
+  with the active provider.
+
+- The scope also updates the internal FoxHound query object via
+  `_Query.setScope(pScope)`, so that all subsequent cloned queries inherit the
+  new scope.
+
+- The `defaultIdentifier` is **not** automatically updated when the scope
+  changes. If you change the scope, you may also need to call
+  `setDefaultIdentifier` to match the new table's primary key column.

package/docs/api/validateObject.md

@@ -0,0 +1,119 @@
+# validateObject
+
+Validate a JavaScript object against the JSON Schema.
+
+## Signature
+
+```javascript
+meadow.validateObject(pObject)
+```
+
+Also accessible via the full schema object:
+
+```javascript
+meadow.schemaFull.validateObject(pObject)
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pObject` | `Object` | The plain JavaScript object to validate |
+
+## Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Valid` | `boolean` | `true` if the object passes validation, `false` otherwise |
+| `Errors` | `Array` | Present only when `Valid` is `false`. Array of error detail objects |
+
+## Description
+
+`validateObject` checks the given object against the JSON Schema that was
+previously set via `setJsonSchema()`. The underlying validator is
+`is-my-json-valid` with `greedy` and `verbose` modes, meaning:
+
+- All properties are checked (not just until the first failure).
+- Each error includes the full property path and the actual value.
+
+## Error Object Format
+
+Each entry in the `Errors` array is an object with properties including:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `field` | `string` | Dot-path to the failing property (e.g. `'data.Title'`) |
+| `message` | `string` | Description of the validation failure |
+| `value` | `*` | The actual value that failed validation |
+
+## Examples
+
+### Successful validation
+
+```javascript
+meadow.setJsonSchema({
+	"title": "Book",
+	"type": "object",
+	"properties": {
+		"Title": { "type": "string", "minLength": 1 },
+		"PageCount": { "type": "integer", "minimum": 1 }
+	},
+	"required": ["Title"]
+});
+
+var tmpResult = meadow.validateObject({
+	Title: 'Dune',
+	PageCount: 412
+});
+
+console.log(tmpResult.Valid); // true
+```
+
+### Failed validation
+
+```javascript
+var tmpResult = meadow.validateObject({
+	PageCount: -5
+});
+
+console.log(tmpResult.Valid);  // false
+console.log(tmpResult.Errors);
+// [
+//   { field: 'data.Title', message: 'is required', ... },
+//   { field: 'data.PageCount', message: 'is less than minimum', value: -5, ... }
+// ]
+```
+
+### Validate before create
+
+```javascript
+var tmpRecord = { Title: 'Neuromancer', Author: 'Gibson' };
+var tmpValidation = meadow.validateObject(tmpRecord);
+
+if (!tmpValidation.Valid)
+{
+	console.error('Validation errors:', tmpValidation.Errors);
+	return;
+}
+
+var tmpQuery = meadow.query.addRecord(tmpRecord);
+meadow.doCreate(tmpQuery,
+	function (pError, pCreateQuery, pReadQuery, pRecord)
+	{
+		console.log('Created:', pRecord);
+	});
+```
+
+## Notes
+
+- `setJsonSchema()` must be called before `validateObject()` for meaningful
+  validation. If no JSON Schema has been set, the validator may produce
+  unexpected results.
+
+- `validateObject` is the same function reference on both `meadow` and
+  `meadow.schemaFull`. Both point to the same underlying validator.
+
+- Meadow does **not** automatically validate records during `doCreate` or
+  `doUpdate`. Validation must be called explicitly by application code.
+
+- The validator uses JSON Schema draft-04 semantics.