meadow 2.0.22 → 2.0.26

package/docs/providers/mongodb.md

@@ -0,0 +1,319 @@
+# MongoDB Provider
+
+> Document-based storage with automatic counter management and sentinel value support
+
+The MongoDB provider connects Meadow to MongoDB databases via the [meadow-connection-mongodb](https://github.com/stevenvelozo/meadow-connection-mongodb) module. It uses the FoxHound MongoDB dialect for query generation, providing document-based storage without schema migration. Auto-increment counters, GUID generation, and timestamp sentinels are handled automatically.
+
+## Setup
+
+### Install Dependencies
+
+```bash
+npm install meadow meadow-connection-mongodb
+```
+
+### Register the Connection
+
+```javascript
+const libFable = require('fable').new(
+	{
+		MongoDB:
+		{
+			URL: 'mongodb://localhost:27017',
+			Database: 'myapp'
+		}
+	});
+
+const libMeadowConnectionMongoDB = require('meadow-connection-mongodb');
+
+// Register the connection service
+libFable.serviceManager.addServiceType('MeadowMongoDBProvider', libMeadowConnectionMongoDB);
+libFable.serviceManager.instantiateServiceProvider('MeadowMongoDBProvider');
+```
+
+### Create a Meadow DAL
+
+```javascript
+const libMeadow = require('meadow');
+
+const meadow = libMeadow.new(libFable, 'Book')
+	.setProvider('MongoDB')
+	.setDefaultIdentifier('IDBook')
+	.setSchema([
+		{ Column: 'IDBook', Type: 'AutoIdentity' },
+		{ Column: 'GUIDBook', Type: 'AutoGUID' },
+		{ Column: 'Title', Type: 'String', Size: '255' },
+		{ Column: 'Author', Type: 'String', Size: '128' },
+		{ Column: 'PageCount', Type: 'Numeric' },
+		{ 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 Management
+
+### Connection Configuration
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `MongoDB.URL` | string | -- | MongoDB connection URL |
+| `MongoDB.Database` | string | -- | Database name |
+
+### No Schema Migration
+
+Unlike SQL-based providers, MongoDB does not require table creation or schema migration. Collections are created automatically when the first document is inserted. This makes MongoDB well-suited for rapid development and evolving data models.
+
+## Document Storage
+
+### The `_id` Field
+
+MongoDB automatically assigns an `_id` field to every document. The Meadow MongoDB provider works alongside this native identifier while maintaining Meadow's own identity system (`IDBook`, `GUIDBook`, etc.). Your application code interacts with Meadow's identity columns as usual; the underlying `_id` is managed transparently.
+
+### Auto-Increment Counters
+
+MongoDB does not natively support auto-increment integer identifiers. The Meadow MongoDB provider implements auto-increment behavior using a dedicated `_meadow_counters` collection. When a record is created with an `AutoIdentity` column:
+
+1. The provider queries the `_meadow_counters` collection for the current counter value
+2. The counter is atomically incremented
+3. The new value is assigned to the identity column on the inserted document
+
+This ensures unique, sequential integer IDs across concurrent inserts.
+
+### Sentinel Values
+
+The MongoDB provider supports sentinel values that are resolved at write time:
+
+| Sentinel | Resolved To | Description |
+|----------|-------------|-------------|
+| `$$NOW` | Current timestamp | Sets the field to the current date and time |
+| `$$AUTOINCREMENT` | Next counter value | Assigns the next auto-increment integer from `_meadow_counters` |
+| `$$AUTOGUID` | New GUID | Generates a new globally unique identifier |
+
+Sentinels are placed in record fields and expanded by the provider before the document is written to MongoDB:
+
+```javascript
+meadow.doCreate(
+	meadow.query.addRecord(
+		{
+			Title: 'Dune',
+			Author: 'Frank Herbert',
+			CreateDate: '$$NOW',
+			GUIDBook: '$$AUTOGUID'
+		}),
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('Created at:', pRecord.CreateDate);
+		console.log('GUID:', pRecord.GUIDBook);
+	});
+```
+
+## CRUD Operations
+
+### Create
+
+Inserts a new document into the collection and returns the auto-generated identity value.
+
+```javascript
+meadow.doCreate(
+	meadow.query.addRecord({ Title: 'Dune', Author: 'Frank Herbert' }),
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('New ID:', pRecord.IDBook);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('MongoDB').buildCreateQuery()`
+- Resolves sentinel values ($$NOW, $$AUTOINCREMENT, $$AUTOGUID)
+- Increments the counter in `_meadow_counters`
+- Inserts the document into the collection
+
+### Read
+
+Queries the collection and returns matching documents.
+
+```javascript
+// Single record
+meadow.doRead(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pRecord) =>
+	{
+		console.log('Title:', pRecord.Title);
+	});
+
+// Multiple records
+meadow.doReads(
+	meadow.query.setCap(25).setBegin(0).addSort({ Column: 'Title', Direction: 'ASC' }),
+	(pError, pQuery, pRecords) =>
+	{
+		pRecords.forEach((pBook) => console.log(pBook.Title));
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('MongoDB').buildReadQuery()`
+- Translates filters to MongoDB query objects
+- Applies sort, skip, and limit from the query parameters
+
+### Update
+
+Updates matching documents in the collection.
+
+```javascript
+meadow.doUpdate(
+	meadow.query
+		.addFilter('IDBook', 42)
+		.addRecord({ Title: 'Updated Title' }),
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('Updated:', pRecord.Title);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('MongoDB').buildUpdateQuery()`
+- Resolves sentinel values before applying the update
+
+### Delete
+
+Executes a soft delete (sets the Deleted flag) and returns the affected document count.
+
+```javascript
+meadow.doDelete(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Deleted documents:', pResult);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('MongoDB').buildDeleteQuery()`
+- Updates the Deleted field rather than removing the document
+
+### Undelete
+
+Reverses a soft delete.
+
+```javascript
+meadow.doUndelete(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Restored documents:', pResult);
+	});
+```
+
+### Count
+
+Returns the count of matching documents.
+
+```javascript
+meadow.doCount(
+	meadow.query.addFilter('Author', 'Frank Herbert', '='),
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Books by Herbert:', pCount);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('MongoDB').buildCountQuery()`
+- Returns the integer count of matching documents
+
+## Full Setup Example
+
+A complete working example connecting to MongoDB and performing CRUD operations:
+
+```javascript
+const libFable = require('fable').new(
+	{
+		MongoDB:
+		{
+			URL: 'mongodb://localhost:27017',
+			Database: 'bookstore'
+		}
+	});
+
+const libMeadow = require('meadow');
+const libMeadowConnectionMongoDB = require('meadow-connection-mongodb');
+
+// Register the connection service
+libFable.serviceManager.addServiceType('MeadowMongoDBProvider', libMeadowConnectionMongoDB);
+libFable.serviceManager.instantiateServiceProvider('MeadowMongoDBProvider');
+
+// Create the DAL
+const meadow = libMeadow.new(libFable, 'Book')
+	.setProvider('MongoDB')
+	.setDefaultIdentifier('IDBook')
+	.setSchema([
+		{ Column: 'IDBook', Type: 'AutoIdentity' },
+		{ Column: 'GUIDBook', Type: 'AutoGUID' },
+		{ Column: 'Title', Type: 'String', Size: '255' },
+		{ Column: 'Author', Type: 'String', Size: '128' },
+		{ Column: 'PageCount', Type: 'Numeric' },
+		{ 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' }
+	]);
+
+// Insert a record
+meadow.doCreate(
+	meadow.query.addRecord({ Title: 'Dune', Author: 'Frank Herbert', PageCount: 412 }),
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('Created book with ID:', pRecord.IDBook);
+		console.log('GUID:', pRecord.GUIDBook);
+
+		// Read it back
+		meadow.doRead(
+			meadow.query.addFilter('IDBook', pRecord.IDBook),
+			(pError, pQuery, pRecord) =>
+			{
+				console.log('Read back:', pRecord.Title, 'by', pRecord.Author);
+
+				// Count all books
+				meadow.doCount(
+					meadow.query,
+					(pError, pQuery, pCount) =>
+					{
+						console.log('Total books in collection:', pCount);
+					});
+			});
+	});
+```
+
+## Error Handling
+
+All operations follow the same error handling pattern:
+
+- Database errors are stored in `pQuery.parameters.result.error`
+- Connection errors bubble up through the callback as `pError`
+- Counter increment failures are logged and reported through the error callback
+
+## Docker Development
+
+For local MongoDB development:
+
+```bash
+docker run -d \
+	--name meadow-mongodb \
+	-p 27017:27017 \
+	mongo:7
+```
+
+## Related Documentation
+
+- [Providers Overview](providers/README.md) -- Comparison of all providers
+- [MySQL Provider](providers/mysql.md) -- Relational database alternative
+- [ALASQL Provider](providers/alasql.md) -- In-memory alternative
+- [meadow-connection-mongodb](https://github.com/stevenvelozo/meadow-connection-mongodb) -- Connection module source

package/docs/providers/postgresql.md

@@ -0,0 +1,312 @@
+# PostgreSQL Provider
+
+> Production-ready PostgreSQL integration with connection pooling and named parameter binding
+
+The PostgreSQL provider connects Meadow to PostgreSQL databases via the [meadow-connection-postgresql](https://github.com/stevenvelozo/meadow-connection-postgresql) module. It uses the FoxHound PostgreSQL dialect for query generation and supports named parameter binding with positional placeholders ($1, $2, etc.).
+
+## Setup
+
+### Install Dependencies
+
+```bash
+npm install meadow meadow-connection-postgresql
+```
+
+### Register the Connection
+
+```javascript
+const libFable = require('fable').new(
+	{
+		PostgreSQL:
+		{
+			Host: 'localhost',
+			Port: 5432,
+			User: 'postgres',
+			Password: '',
+			Database: 'myapp',
+			ConnectionPoolLimit: 20
+		}
+	});
+
+const libMeadowConnectionPostgreSQL = require('meadow-connection-postgresql');
+
+// Register the connection service
+libFable.serviceManager.addServiceType('MeadowPostgreSQLProvider', libMeadowConnectionPostgreSQL);
+const tmpConnection = libFable.serviceManager.instantiateServiceProvider('MeadowPostgreSQLProvider');
+
+// Connect asynchronously
+tmpConnection.connectAsync(
+	(pError) =>
+	{
+		if (pError)
+		{
+			return console.error('PostgreSQL connection failed:', pError);
+		}
+		console.log('Connected to PostgreSQL');
+	});
+```
+
+### Create a Meadow DAL
+
+```javascript
+const libMeadow = require('meadow');
+
+const meadow = libMeadow.new(libFable, 'Book')
+	.setProvider('PostgreSQL')
+	.setDefaultIdentifier('IDBook')
+	.setSchema([
+		{ Column: 'IDBook', Type: 'AutoIdentity' },
+		{ Column: 'GUIDBook', Type: 'AutoGUID' },
+		{ Column: 'Title', Type: 'String', Size: '255' },
+		{ Column: 'Author', Type: 'String', Size: '128' },
+		{ Column: 'Price', Type: 'Decimal', Size: '12,2' },
+		{ 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 Management
+
+### Async Connection Model
+
+The PostgreSQL provider uses an asynchronous connection model. The connection module provides:
+
+| Method | Description |
+|--------|-------------|
+| `connectAsync(fCallback)` | Async connection with callback on completion |
+
+### Connection Pool Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `PostgreSQL.Host` | string | -- | Database server hostname |
+| `PostgreSQL.Port` | number | `5432` | Database server port |
+| `PostgreSQL.User` | string | -- | Database user |
+| `PostgreSQL.Password` | string | -- | Database password |
+| `PostgreSQL.Database` | string | -- | Database name |
+| `PostgreSQL.ConnectionPoolLimit` | number | `20` | Maximum pool connections |
+
+### Named Parameter Binding
+
+The PostgreSQL provider uses positional parameter placeholders ($1, $2, etc.) as required by the PostgreSQL wire protocol. FoxHound's PostgreSQL dialect generates queries with these positional bindings:
+
+```sql
+-- Generated by FoxHound with positional placeholders:
+SELECT "IDBook", "Title", "Author" FROM "Book" WHERE "IDBook" = $1 AND "Deleted" = 0
+```
+
+## CRUD Operations
+
+### Create
+
+Executes an INSERT statement with a RETURNING clause to capture the generated identity.
+
+```javascript
+meadow.doCreate(
+	meadow.query.addRecord({ Title: 'Dune', Author: 'Frank Herbert' }),
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('New ID:', pRecord.IDBook);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('PostgreSQL').buildCreateQuery()`
+- Extracts identity from the RETURNING clause result
+
+### Read
+
+Executes a SELECT statement and returns result rows.
+
+```javascript
+// Single record
+meadow.doRead(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pRecord) =>
+	{
+		console.log('Title:', pRecord.Title);
+	});
+
+// Multiple records
+meadow.doReads(
+	meadow.query.setCap(25).setBegin(0).addSort({ Column: 'Title', Direction: 'ASC' }),
+	(pError, pQuery, pRecords) =>
+	{
+		pRecords.forEach((pBook) => console.log(pBook.Title));
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('PostgreSQL').buildReadQuery()`
+- Returns full result rows array
+
+### Update
+
+Executes an UPDATE statement.
+
+```javascript
+meadow.doUpdate(
+	meadow.query
+		.addFilter('IDBook', 42)
+		.addRecord({ Title: 'Updated Title' }),
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('Updated:', pRecord.Title);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('PostgreSQL').buildUpdateQuery()`
+
+### Delete
+
+Executes a soft delete (UPDATE setting Deleted flag) and returns the affected row count.
+
+```javascript
+meadow.doDelete(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Deleted rows:', pResult);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('PostgreSQL').buildDeleteQuery()`
+- Extracts affected rows from the result
+
+### Undelete
+
+Reverses a soft delete and returns the affected row count.
+
+```javascript
+meadow.doUndelete(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Restored rows:', pResult);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('PostgreSQL').buildUndeleteQuery()`
+- Extracts affected rows from the result
+
+### Count
+
+Executes a COUNT query and returns the integer count.
+
+```javascript
+meadow.doCount(
+	meadow.query.addFilter('Author', 'Frank Herbert', '='),
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Books by Herbert:', pCount);
+	});
+```
+
+**Internally:**
+- Builds query: `pQuery.setDialect('PostgreSQL').buildCountQuery()`
+- Extracts count from the result
+
+## Full Setup Example
+
+A complete working example connecting to PostgreSQL and performing CRUD operations:
+
+```javascript
+const libFable = require('fable').new(
+	{
+		PostgreSQL:
+		{
+			Host: 'localhost',
+			Port: 5432,
+			User: 'postgres',
+			Password: 'secret',
+			Database: 'bookstore',
+			ConnectionPoolLimit: 10
+		}
+	});
+
+const libMeadow = require('meadow');
+const libMeadowConnectionPostgreSQL = require('meadow-connection-postgresql');
+
+// Register and connect
+libFable.serviceManager.addServiceType('MeadowPostgreSQLProvider', libMeadowConnectionPostgreSQL);
+const tmpConnection = libFable.serviceManager.instantiateServiceProvider('MeadowPostgreSQLProvider');
+
+tmpConnection.connectAsync(
+	(pError) =>
+	{
+		if (pError)
+		{
+			return console.error('Connection failed:', pError);
+		}
+
+		// Create the DAL
+		const meadow = libMeadow.new(libFable, 'Book')
+			.setProvider('PostgreSQL')
+			.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' }
+			]);
+
+		// Insert a record
+		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
+				meadow.doRead(
+					meadow.query.addFilter('IDBook', pRecord.IDBook),
+					(pError, pQuery, pRecord) =>
+					{
+						console.log('Read back:', pRecord.Title, 'by', pRecord.Author);
+					});
+			});
+	});
+```
+
+## Error Handling
+
+All operations follow the same error handling pattern:
+
+- Database errors are stored in `pQuery.parameters.result.error`
+- Identity/rowcount extraction failures are logged as warnings
+- Connection errors bubble up through the callback as `pError`
+
+## Docker Development
+
+For local PostgreSQL development:
+
+```bash
+docker run -d \
+	--name meadow-postgresql \
+	-e POSTGRES_PASSWORD=secret \
+	-e POSTGRES_DB=myapp \
+	-p 5432:5432 \
+	postgres:16
+```
+
+## Related Documentation
+
+- [Providers Overview](providers/README.md) -- Comparison of all providers
+- [MySQL Provider](providers/mysql.md) -- MySQL/MariaDB alternative
+- [MSSQL Provider](providers/mssql.md) -- Microsoft SQL Server alternative
+- [meadow-connection-postgresql](https://github.com/stevenvelozo/meadow-connection-postgresql) -- Connection module source