meadow 2.0.23 → 2.0.27

package/docs/configuration.md

@@ -0,0 +1,317 @@
+# Configuration
+
+Meadow is configured through the Fable settings object. All settings are passed when constructing the Fable instance and are available to Meadow and its providers at runtime.
+
+## Core Meadow Settings
+
+### MeadowProvider
+
+The name of the database provider to use by default when creating new Meadow instances.
+
+- **Type:** `String`
+- **Default:** `'None'`
+- **Valid values:** `'MySQL'`, `'MSSQL'`, `'PostgreSQL'`, `'SQLite'`, `'MongoDB'`, `'RocksDB'`, `'ALASQL'`, `'MeadowEndpoints'`, `'None'`
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'MySQL'
+	});
+```
+
+When set, every `libMeadow.new(_Fable, 'SomeEntity')` call automatically uses this provider. You can override it per-DAL with `meadow.setProvider('OtherProvider')`.
+
+### MeadowRoleNames
+
+An ordered array of role names used by the authorization system. Role indices map to positions in this array.
+
+- **Type:** `Array<String>`
+- **Default:**
+  ```javascript
+  [
+  	'Unauthenticated',
+  	'User',
+  	'Manager',
+  	'Director',
+  	'Executive',
+  	'Administrator'
+  ]
+  ```
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowRoleNames:
+		[
+			'Anonymous',
+			'Viewer',
+			'Editor',
+			'Admin',
+			'SuperAdmin'
+		]
+	});
+```
+
+Role names are retrieved with `meadow.getRoleName(pRoleIndex)`. If the index is out of bounds, `'Unauthenticated'` (or your first role name) is returned.
+
+### QueryThresholdWarnTime
+
+The threshold in milliseconds for slow query warnings. When a `doReads` or `doCount` operation exceeds this time, Meadow logs a warning with the full query details.
+
+- **Type:** `Number`
+- **Default:** `200`
+- **Unit:** milliseconds
+
+```javascript
+var _Fable = new libFable(
+	{
+		QueryThresholdWarnTime: 500
+	});
+```
+
+## MySQL Connection Settings
+
+The `MySQL` settings object configures the MySQL provider and connection pool.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `Server` | `String` | `'localhost'` | Database server hostname |
+| `Port` | `Number` | `3306` | Database server port |
+| `User` | `String` | `'root'` | Database user |
+| `Password` | `String` | `''` | Database password |
+| `Database` | `String` | `''` | Database name |
+| `ConnectionPoolLimit` | `Number` | `20` | Maximum connections in the pool |
+| `GlobalLogLevel` | `Number` | `0` | Set to `> 0` to trace all query bodies |
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'MySQL',
+		MySQL:
+		{
+			Server: 'db.example.com',
+			Port: 3306,
+			User: 'app_user',
+			Password: 'secret',
+			Database: 'my_application',
+			ConnectionPoolLimit: 20,
+			GlobalLogLevel: 0
+		}
+	});
+```
+
+## MSSQL Connection Settings
+
+The `MSSQL` settings object configures the Microsoft SQL Server provider. The connection pool is managed by the `meadow-connection-mssql` module.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `Server` | `String` | `'localhost'` | Database server hostname |
+| `Port` | `Number` | `1433` | Database server port |
+| `User` | `String` | `'sa'` | Database user |
+| `Password` | `String` | `''` | Database password |
+| `Database` | `String` | `''` | Database name |
+| `ConnectionPoolLimit` | `Number` | `20` | Maximum connections in the pool |
+| `GlobalLogLevel` | `Number` | `0` | Set to `> 0` to trace all query bodies |
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'MSSQL',
+		MSSQL:
+		{
+			Server: 'sqlserver.example.com',
+			Port: 1433,
+			User: 'sa',
+			Password: 'secret',
+			Database: 'my_application',
+			ConnectionPoolLimit: 20,
+			GlobalLogLevel: 0
+		}
+	});
+```
+
+## PostgreSQL Connection Settings
+
+The `PostgreSQL` settings object configures the PostgreSQL provider.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `Server` | `String` | `'localhost'` | Database server hostname |
+| `Port` | `Number` | `5432` | Database server port |
+| `User` | `String` | `'postgres'` | Database user |
+| `Password` | `String` | `''` | Database password |
+| `Database` | `String` | `''` | Database name |
+| `GlobalLogLevel` | `Number` | `0` | Set to `> 0` to trace all query bodies |
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'PostgreSQL',
+		PostgreSQL:
+		{
+			Server: 'pg.example.com',
+			Port: 5432,
+			User: 'postgres',
+			Password: 'secret',
+			Database: 'my_application',
+			GlobalLogLevel: 0
+		}
+	});
+```
+
+## MeadowEndpoints Settings
+
+The `MeadowEndpoints` settings object configures the REST API proxy provider. This provider translates CRUD operations into HTTP requests against a remote Meadow-Endpoints server.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `ServerProtocol` | `String` | `'http'` | Protocol (`'http'` or `'https'`) |
+| `ServerAddress` | `String` | `'127.0.0.1'` | Remote server hostname |
+| `ServerPort` | `String` | `'8086'` | Remote server port |
+| `ServerEndpointPrefix` | `String` | `'1.0/'` | URL prefix for API endpoints |
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'MeadowEndpoints',
+		MeadowEndpoints:
+		{
+			ServerProtocol: 'https',
+			ServerAddress: 'api.example.com',
+			ServerPort: '443',
+			ServerEndpointPrefix: '1.0/'
+		}
+	});
+```
+
+## SQLite Settings
+
+SQLite is configured through the `meadow-connection-sqlite` connection module. The connection provider manages the `better-sqlite3` database instance.
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'SQLite'
+	});
+
+var libMeadowConnectionSQLite = require('meadow-connection-sqlite');
+var tmpConnection = libMeadowConnectionSQLite.new(_Fable);
+tmpConnection.connectAsync(':memory:');
+```
+
+SQLite supports both file-based databases (pass a file path) and in-memory databases (pass `':memory:'`).
+
+## MongoDB Settings
+
+The `MongoDB` settings object configures the MongoDB provider.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `URL` | `String` | `''` | MongoDB connection URL |
+| `Database` | `String` | `''` | Database name |
+| `GlobalLogLevel` | `Number` | `0` | Set to `> 0` to trace all query bodies |
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'MongoDB',
+		MongoDB:
+		{
+			URL: 'mongodb://localhost:27017',
+			Database: 'my_application',
+			GlobalLogLevel: 0
+		}
+	});
+```
+
+## RocksDB Settings
+
+The `RocksDB` settings object configures the RocksDB key-value provider.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `KeyMode` | `String` | `'GUID'` | Key strategy: `'GUID'` or `'ID'` |
+| `GlobalLogLevel` | `Number` | `0` | Set to `> 0` to trace all operations |
+
+```javascript
+var _Fable = new libFable(
+	{
+		MeadowProvider: 'RocksDB',
+		RocksDB:
+		{
+			KeyMode: 'GUID',
+			GlobalLogLevel: 0
+		}
+	});
+```
+
+## Full Example
+
+A complete Fable settings object showing all available Meadow options:
+
+```json
+{
+	"MeadowProvider": "MySQL",
+
+	"MeadowRoleNames": [
+		"Unauthenticated",
+		"User",
+		"Manager",
+		"Director",
+		"Executive",
+		"Administrator"
+	],
+
+	"QueryThresholdWarnTime": 200,
+
+	"MySQL": {
+		"Server": "localhost",
+		"Port": 3306,
+		"User": "app_user",
+		"Password": "secret",
+		"Database": "my_application",
+		"ConnectionPoolLimit": 20,
+		"GlobalLogLevel": 0
+	},
+
+	"MSSQL": {
+		"Server": "localhost",
+		"Port": 1433,
+		"User": "sa",
+		"Password": "secret",
+		"Database": "my_application",
+		"ConnectionPoolLimit": 20,
+		"GlobalLogLevel": 0
+	},
+
+	"PostgreSQL": {
+		"Server": "localhost",
+		"Port": 5432,
+		"User": "postgres",
+		"Password": "secret",
+		"Database": "my_application",
+		"GlobalLogLevel": 0
+	},
+
+	"MeadowEndpoints": {
+		"ServerProtocol": "https",
+		"ServerAddress": "api.example.com",
+		"ServerPort": "443",
+		"ServerEndpointPrefix": "1.0/"
+	},
+
+	"MongoDB": {
+		"URL": "mongodb://localhost:27017",
+		"Database": "my_application",
+		"GlobalLogLevel": 0
+	},
+
+	"RocksDB": {
+		"KeyMode": "GUID",
+		"GlobalLogLevel": 0
+	}
+}
+```
+
+Note that you only need to include configuration for the provider you are using. Including unused provider settings has no effect.

package/docs/providers/meadow-endpoints.md

@@ -0,0 +1,306 @@
+# MeadowEndpoints Provider
+
+> HTTP proxy to remote Meadow REST APIs using the same Meadow interface
+
+The MeadowEndpoints provider enables client-side JavaScript to use the same Meadow CRUD interface while delegating actual data operations to a remote Meadow REST API server. Instead of connecting to a database directly, it translates Meadow operations into HTTP requests using [simple-get](https://github.com/feross/simple-get). No external connection module is required -- the HTTP transport is built in.
+
+## Setup
+
+### Install Dependencies
+
+```bash
+npm install meadow
+```
+
+No external connection module is needed. The MeadowEndpoints provider uses `simple-get` (bundled with Meadow) for HTTP communication.
+
+### Configure the Remote Server
+
+```javascript
+const libFable = require('fable').new(
+	{
+		MeadowEndpoints:
+		{
+			ServerProtocol: 'http',
+			ServerAddress: '127.0.0.1',
+			ServerPort: 8086,
+			ServerEndpointPrefix: '1.0/'
+		}
+	});
+```
+
+### Create a Meadow DAL
+
+```javascript
+const libMeadow = require('meadow');
+
+const meadow = libMeadow.new(libFable, 'Book')
+	.setProvider('MeadowEndpoints')
+	.setDefaultIdentifier('IDBook')
+	.setSchema([
+		{ 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: 'DeleteDate', Type: 'DeleteDate' },
+		{ Column: 'DeletingIDUser', Type: 'DeleteIDUser' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+```
+
+## Connection Configuration
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `MeadowEndpoints.ServerProtocol` | string | -- | HTTP protocol (`'http'` or `'https'`) |
+| `MeadowEndpoints.ServerAddress` | string | -- | Remote server hostname or IP address |
+| `MeadowEndpoints.ServerPort` | number | -- | Remote server port |
+| `MeadowEndpoints.ServerEndpointPrefix` | string | -- | URL path prefix for API endpoints (e.g., `'1.0/'`) |
+
+### URL Construction
+
+The provider constructs endpoint URLs from the configuration settings:
+
+```
+{ServerProtocol}://{ServerAddress}:{ServerPort}/{ServerEndpointPrefix}{Scope}/{Operation}
+```
+
+For example, with the default configuration and a `Book` scope:
+
+```
+http://127.0.0.1:8086/1.0/Book
+http://127.0.0.1:8086/1.0/Books
+http://127.0.0.1:8086/1.0/Book/42
+http://127.0.0.1:8086/1.0/Books/Count
+```
+
+## HTTP Method Mapping
+
+Each Meadow CRUD operation maps to a standard HTTP method:
+
+| HTTP Method | Meadow Operation | Endpoint Pattern |
+|-------------|------------------|------------------|
+| `POST` | Create | `/{prefix}{Scope}` |
+| `GET` | Read | `/{prefix}{Scope}/{ID}` |
+| `GET` | Reads | `/{prefix}{Scope}s` |
+| `GET` | Count | `/{prefix}{Scope}s/Count` |
+| `PUT` | Update | `/{prefix}{Scope}` |
+| `DELETE` | Delete | `/{prefix}{Scope}/{ID}` |
+
+This mapping follows the standard Meadow REST conventions generated by [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) on the server side.
+
+## Cookie and Header Forwarding
+
+The MeadowEndpoints provider forwards cookies and headers from the client to the remote server. This enables transparent authentication and session management -- if the client has an authenticated session with the server, the provider carries those credentials through on every request.
+
+## CRUD Operations
+
+### Create
+
+Sends a POST request with the record data as the JSON body.
+
+```javascript
+meadow.doCreate(
+	meadow.query.addRecord({ Title: 'Dune', Author: 'Frank Herbert' }),
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('New ID:', pRecord.IDBook);
+	});
+```
+
+**HTTP request:**
+```
+POST http://127.0.0.1:8086/1.0/Book
+Content-Type: application/json
+
+{ "Title": "Dune", "Author": "Frank Herbert" }
+```
+
+### Read
+
+Sends a GET request to retrieve a single record by identifier.
+
+```javascript
+meadow.doRead(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pRecord) =>
+	{
+		console.log('Title:', pRecord.Title);
+	});
+```
+
+**HTTP request:**
+```
+GET http://127.0.0.1:8086/1.0/Book/42
+```
+
+### Reads
+
+Sends a GET request to retrieve multiple records with optional filtering and pagination.
+
+```javascript
+meadow.doReads(
+	meadow.query.setCap(25).setBegin(0),
+	(pError, pQuery, pRecords) =>
+	{
+		pRecords.forEach((pBook) => console.log(pBook.Title));
+	});
+```
+
+**HTTP request:**
+```
+GET http://127.0.0.1:8086/1.0/Books
+```
+
+### Update
+
+Sends a PUT request with the updated record data as the JSON body.
+
+```javascript
+meadow.doUpdate(
+	meadow.query
+		.addFilter('IDBook', 42)
+		.addRecord({ Title: 'Updated Title' }),
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('Updated:', pRecord.Title);
+	});
+```
+
+**HTTP request:**
+```
+PUT http://127.0.0.1:8086/1.0/Book
+Content-Type: application/json
+
+{ "IDBook": 42, "Title": "Updated Title" }
+```
+
+### Delete
+
+Sends a DELETE request to soft-delete a record by identifier.
+
+```javascript
+meadow.doDelete(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Deleted:', pResult);
+	});
+```
+
+**HTTP request:**
+```
+DELETE http://127.0.0.1:8086/1.0/Book/42
+```
+
+### Count
+
+Sends a GET request to the count endpoint.
+
+```javascript
+meadow.doCount(
+	meadow.query,
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Total books:', pCount);
+	});
+```
+
+**HTTP request:**
+```
+GET http://127.0.0.1:8086/1.0/Books/Count
+```
+
+## Use Case: Unified Client-Server Interface
+
+The primary use case for MeadowEndpoints is enabling client-side JavaScript to use the same Meadow data access interface that the server uses. This means your application logic can be written once and run in either context:
+
+```
+Browser / Client                        Server
+┌──────────────────┐                   ┌──────────────────┐
+│  Application Code │                   │  Application Code │
+│                   │                   │                   │
+│  Meadow DAL       │                   │  Meadow DAL       │
+│  Provider:        │    HTTP/REST      │  Provider:        │
+│  MeadowEndpoints ─┼──────────────────>│  MySQL            │
+│                   │                   │                   │
+└──────────────────┘                   └──────────────────┘
+```
+
+- **Server side:** Meadow uses a database provider (MySQL, MSSQL, PostgreSQL, etc.) to interact with the database directly
+- **Client side:** Meadow uses MeadowEndpoints to proxy the same operations over HTTP to the server's REST API
+- **Application code:** Identical CRUD calls in both environments
+
+This pattern is especially powerful when combined with [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) on the server, which auto-generates REST routes from Meadow entity definitions.
+
+## Full Setup Example
+
+A complete working example showing client-side Meadow proxying to a remote server:
+
+```javascript
+const libFable = require('fable').new(
+	{
+		MeadowEndpoints:
+		{
+			ServerProtocol: 'https',
+			ServerAddress: 'api.example.com',
+			ServerPort: 443,
+			ServerEndpointPrefix: '1.0/'
+		}
+	});
+
+const libMeadow = require('meadow');
+
+// Create the DAL with MeadowEndpoints provider
+const meadow = libMeadow.new(libFable, 'Book')
+	.setProvider('MeadowEndpoints')
+	.setDefaultIdentifier('IDBook')
+	.setSchema([
+		{ 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: 'DeleteDate', Type: 'DeleteDate' },
+		{ Column: 'DeletingIDUser', Type: 'DeleteIDUser' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+
+// These calls transparently proxy to the remote server
+meadow.doCreate(
+	meadow.query.addRecord({ Title: 'Dune', Author: 'Frank Herbert' }),
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('Created book with ID:', pRecord.IDBook);
+
+		// Read it back from the server
+		meadow.doRead(
+			meadow.query.addFilter('IDBook', pRecord.IDBook),
+			(pError, pQuery, pRecord) =>
+			{
+				console.log('Read back:', pRecord.Title, 'by', pRecord.Author);
+			});
+	});
+```
+
+## Error Handling
+
+HTTP-related errors follow the standard pattern:
+
+- Network errors (connection refused, timeouts) are returned as `pError` in the callback
+- HTTP error status codes (4xx, 5xx) are stored in `pQuery.parameters.result.error`
+- Response parsing failures are logged and reported through the error callback
+
+## Related Documentation
+
+- [Providers Overview](providers/README.md) -- Comparison of all providers
+- [MySQL Provider](providers/mysql.md) -- Server-side database provider
+- [ALASQL Provider](providers/alasql.md) -- Client-side in-memory alternative
+- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) -- Server-side REST API generation