meadow 2.0.16 → 2.0.18

package/docs/_sidebar.md

@@ -0,0 +1,38 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Architecture](architecture.md)
+
+- Core Concepts
+
+  - [Schema](schema/README.md)
+  - [CRUD Operations](crud-operations.md)
+  - [Query DSL](query-dsl.md)
+  - [Raw Queries](raw-queries.md)
+
+- Schema
+
+  - [Schema Overview](schema/README.md)
+
+- Query Operations
+
+  - [Query Overview](query/README.md)
+  - [Create](query/create.md)
+  - [Read](query/read.md)
+  - [Update](query/update.md)
+  - [Delete](query/delete.md)
+  - [Count](query/count.md)
+
+- Providers
+
+  - [Providers Overview](providers/README.md)
+  - [MySQL](providers/mysql.md)
+  - [MSSQL](providers/mssql.md)
+  - [SQLite](providers/sqlite.md)
+  - [ALASQL](providers/alasql.md)
+
+- Advanced
+
+  - [Audit Tracking](audit-tracking.md)
+  - [Soft Deletes](soft-deletes.md)
+  - [Configuration Reference](configuration.md)

package/docs/providers/README.md

@@ -0,0 +1,253 @@
+# Providers
+
+> Pluggable database backends through a consistent interface
+
+Meadow's provider system abstracts database communication behind a unified CRUD interface. You write your data access code once, then swap providers to target MySQL, MSSQL, SQLite, an in-browser IndexedDB store, or even a remote REST API — all without changing your application logic.
+
+## Overview
+
+```
+Meadow (Data Access Layer)
+  └── Provider Interface
+        ├── MySQL       → mysql2 connection pool, named placeholders
+        ├── MSSQL       → mssql prepared statements, SCOPE_IDENTITY()
+        ├── SQLite      → Lightweight embedded SQL
+        ├── ALASQL      → In-memory JavaScript SQL engine (browser/Node)
+        ├── MeadowEndpoints → HTTP proxy to remote Meadow REST API
+        └── None        → No-op stub for testing
+```
+
+Every provider implements the same operation set:
+
+| Operation | Description |
+|-----------|-------------|
+| `Create` | Insert a new record, return the identity value |
+| `Read` | Execute a SELECT query, return result rows |
+| `Update` | Execute an UPDATE query |
+| `Delete` | Execute a DELETE query (soft delete), return affected rows |
+| `Undelete` | Reverse a soft delete, return affected rows |
+| `Count` | Execute a COUNT query, return the row count |
+
+## Choosing a Provider
+
+| Provider | Best For | Connection Module |
+|----------|----------|-------------------|
+| [MySQL](providers/mysql.md) | Production web applications, MySQL/MariaDB | [meadow-connection-mysql](https://github.com/stevenvelozo/meadow-connection-mysql) |
+| [MSSQL](providers/mssql.md) | Enterprise environments, SQL Server | [meadow-connection-mssql](https://github.com/stevenvelozo/meadow-connection-mssql) |
+| [SQLite](providers/sqlite.md) | Embedded applications, local development | [meadow-connection-sqlite](https://github.com/stevenvelozo/meadow-connection-sqlite) |
+| [ALASQL](providers/alasql.md) | Browser applications, unit testing, prototyping | Built-in (no external connection) |
+| MeadowEndpoints | Client-side proxy to remote Meadow APIs | Built-in (HTTP via simple-get) |
+| None | Unit testing stubs, development scaffolding | None required |
+
+## Setting a Provider
+
+```javascript
+const libFable = require('fable').new();
+const libMeadow = require('meadow');
+
+const meadow = libMeadow.new(libFable, 'Book')
+	.setProvider('MySQL')
+	.setDefaultIdentifier('IDBook')
+	.setSchema([
+		{ Column: 'IDBook', Type: 'AutoIdentity' },
+		{ Column: 'Title', Type: 'String', Size: '255' }
+	]);
+```
+
+The provider name is a string matching one of: `'MySQL'`, `'MSSQL'`, `'SQLite'`, `'ALASQL'`, `'MeadowEndpoints'`, or `'None'`.
+
+## How Providers Work
+
+### Query Flow
+
+Every CRUD operation follows the same flow through the provider:
+
+```
+Application Code
+  │
+  ▼
+Meadow Behavior (e.g., doCreate)
+  │  1. Build query object via FoxHound
+  │  2. Apply auto-stamps and GUID generation
+  │  3. Merge default object with submitted record
+  │
+  ▼
+FoxHound Query DSL
+  │  4. Set dialect for target database
+  │  5. Generate dialect-specific SQL
+  │  6. Bind parameters
+  │
+  ▼
+Provider
+  │  7. Get database connection
+  │  8. Execute generated SQL
+  │  9. Marshal results into result object
+  │
+  ▼
+Callback
+  10. Return (pError, pQuery, pRecord/pRecords)
+```
+
+### FoxHound Dialect Integration
+
+Each provider sets the appropriate FoxHound dialect before building queries:
+
+```javascript
+// MySQL provider internally calls:
+pQuery.setDialect('MySQL').buildReadQuery();
+
+// MSSQL provider internally calls:
+pQuery.setDialect('MSSQL').buildReadQuery();
+
+// ALASQL provider internally calls:
+pQuery.setDialect('ALASQL').buildReadQuery();
+```
+
+This ensures the generated SQL matches the target database's syntax.
+
+### Result Object
+
+All providers store their results in a consistent structure on the query object:
+
+```javascript
+pQuery.parameters.result =
+{
+	error: null,        // Error object if operation failed, null on success
+	value: false,       // Result value (varies by operation — see below)
+	executed: true      // Whether the provider attempted execution
+};
+```
+
+| Operation | `result.value` |
+|-----------|----------------|
+| Create | Identity value of the new record (e.g., `42`) |
+| Read | Array of record objects |
+| Update | Query result object |
+| Delete | Number of affected rows |
+| Undelete | Number of affected rows |
+| Count | Integer count of matching records |
+
+### Record Marshalling
+
+All providers implement `marshalRecordFromSourceToObject(pObject, pRecord)` to copy database field values onto a result object:
+
+```javascript
+// Provider copies each column from the database result to the output object
+for (var tmpColumn in pRecord)
+{
+	pObject[tmpColumn] = pRecord[tmpColumn];
+}
+```
+
+Meadow's `marshalRecordFromSourceToObject` method combines this with default object merging:
+
+```javascript
+// Internally:
+// 1. Create object from default template
+// 2. Provider copies database values over defaults
+const tmpRecord = fable.Utility.extend({}, schema.defaultObject, pRecord);
+```
+
+### Schema Synchronization
+
+When you call `setSchema()` on Meadow, it automatically updates the provider:
+
+```javascript
+// Meadow internally calls:
+provider.setSchema(scope, schema, defaultIdentifier, defaultGUIdentifier);
+```
+
+This is critical for providers like ALASQL that dynamically create tables from schema definitions.
+
+## Connection Management
+
+Each SQL provider requires a connection module registered as a Fable service. The connection modules handle pooling, configuration, and lifecycle management.
+
+### MySQL Connection
+
+```javascript
+const libMeadowConnectionMySQL = require('meadow-connection-mysql');
+
+// Register the connection service
+libFable.serviceManager.addServiceType('MeadowMySQLProvider', libMeadowConnectionMySQL);
+libFable.serviceManager.instantiateServiceProvider('MeadowMySQLProvider');
+
+// Or auto-connect on init:
+libFable.serviceManager.instantiateServiceProvider('MeadowMySQLProvider',
+	{ MeadowConnectionMySQLAutoConnect: true });
+```
+
+### MSSQL Connection
+
+```javascript
+const libMeadowConnectionMSSQL = require('meadow-connection-mssql');
+
+// Register and connect asynchronously
+libFable.serviceManager.addServiceType('MeadowMSSQLProvider', libMeadowConnectionMSSQL);
+const tmpConnection = libFable.serviceManager.instantiateServiceProvider('MeadowMSSQLProvider');
+tmpConnection.connectAsync(
+	(pError) =>
+	{
+		if (pError)
+		{
+			return console.error('Connection failed:', pError);
+		}
+		// Ready for CRUD operations
+	});
+```
+
+## MeadowEndpoints Provider
+
+The MeadowEndpoints provider is unique — it doesn't connect to a database directly. Instead, it acts as an HTTP proxy to a remote Meadow REST API. This enables client-side code to use the same Meadow interface while the actual data operations happen on a server.
+
+```javascript
+meadow.setProvider('MeadowEndpoints');
+```
+
+Configuration is read from Fable settings:
+
+```json
+{
+	"MeadowEndpoints": {
+		"ServerProtocol": "http",
+		"ServerAddress": "127.0.0.1",
+		"ServerPort": 8086,
+		"ServerEndpointPrefix": "1.0/"
+	}
+}
+```
+
+| HTTP Method | CRUD Operation |
+|-------------|----------------|
+| `POST` | Create |
+| `GET` | Read / Reads / Count |
+| `PUT` | Update |
+| `DELETE` | Delete |
+
+## None Provider
+
+The None provider is a no-op stub that marks every operation as executed without doing anything. Useful for testing application logic without a database connection.
+
+```javascript
+meadow.setProvider('None');
+
+// All operations succeed immediately with empty results
+meadow.doRead(meadow.query.addFilter('IDBook', 1),
+	(pError, pQuery, pRecord) =>
+	{
+		// pRecord will be minimal/empty — no actual data
+	});
+```
+
+## Provider-Specific Documentation
+
+- [MySQL](providers/mysql.md) — Connection pooling, named placeholders, configuration
+- [MSSQL](providers/mssql.md) — Prepared statements, type mapping, identity handling
+- [SQLite](providers/sqlite.md) — Embedded database, lightweight deployment
+- [ALASQL](providers/alasql.md) — In-memory SQL, dynamic table creation, browser support
+
+## Related Documentation
+
+- [Schema](schema/README.md) — How schema definitions drive provider behavior
+- [Query Overview](query/README.md) — FoxHound query DSL and dialect generation
+- [Meadow-Endpoints](https://github.com/stevenvelozo/meadow-endpoints) — REST API generation on top of Meadow providers

package/docs/providers/alasql.md

@@ -0,0 +1,271 @@
+# ALASQL Provider
+
+> In-memory JavaScript SQL engine for browser applications, unit testing, and rapid prototyping
+
+The ALASQL provider connects Meadow to [AlaSQL](https://github.com/AlaSQL/alasql), a JavaScript SQL database that runs entirely in memory. It requires no external database server, supports dynamic table creation from Meadow schemas, and works in both Node.js and browser environments. This makes it ideal for unit tests, browser-based applications, and prototyping.
+
+## Setup
+
+### Install Dependencies
+
+```bash
+npm install meadow alasql
+```
+
+### Initialize ALASQL on Fable
+
+```javascript
+const libFable = require('fable').new();
+const libALASQL = require('alasql');
+
+// Attach ALASQL to the Fable instance
+libFable.ALASQL = libALASQL;
+```
+
+### Create a Meadow DAL
+
+```javascript
+const libMeadow = require('meadow');
+
+const meadow = libMeadow.new(libFable, 'Book')
+	.setProvider('ALASQL')
+	.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: 'InPrint', Type: 'Boolean' },
+		{ 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' }
+	]);
+```
+
+## Dynamic Table Creation
+
+Unlike SQL-server-based providers, ALASQL dynamically creates tables from your Meadow schema. When the first CRUD operation is executed, the provider checks whether the table exists and creates it if needed.
+
+### Schema-to-SQL Type Mapping
+
+| Meadow Type | ALASQL Column Definition |
+|-------------|--------------------------|
+| `AutoIdentity` | `INT AUTOINCREMENT` |
+| `AutoGUID` | `STRING` |
+| `Boolean` | `BOOLEAN` |
+| `Numeric` | `INT` |
+| `Integer` | `INT` |
+| `Decimal` | `DECIMAL` |
+| `String` | `STRING` |
+| `Text` | `STRING` |
+| `DateTime` | `STRING` |
+| `CreateDate` | `STRING` |
+| `CreateIDUser` | `INT` |
+| `UpdateDate` | `STRING` |
+| `UpdateIDUser` | `INT` |
+| `DeleteDate` | `STRING` |
+| `DeleteIDUser` | `INT` |
+| `Deleted` | `BOOLEAN` |
+
+### Automatic Table Check
+
+Before each CRUD operation, the provider calls `checkDataExists(pParameters)` to verify the table exists. If not, it generates and executes a `CREATE TABLE` statement based on the schema:
+
+```sql
+-- Generated automatically from schema:
+CREATE TABLE Book (
+	IDBook INT AUTOINCREMENT,
+	GUIDBook STRING,
+	Title STRING,
+	Author STRING,
+	PageCount INT,
+	InPrint BOOLEAN,
+	CreateDate STRING,
+	CreatingIDUser INT,
+	UpdateDate STRING,
+	UpdatingIDUser INT,
+	DeleteDate STRING,
+	DeletingIDUser INT,
+	Deleted BOOLEAN
+)
+```
+
+## CRUD Operations
+
+All ALASQL operations are **synchronous** internally (wrapped in callbacks for API consistency). Queries are compiled via `libALASQL.compile()` for efficient execution.
+
+### Create
+
+```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('ALASQL').buildCreateQuery()`
+- Compiles: `libALASQL.compile(queryBody)`
+- Extracts identity: `libALASQL.autoval(scope, defaultIdentifier)`
+
+### Read
+
+```javascript
+meadow.doRead(
+	meadow.query.addFilter('IDBook', 1),
+	(pError, pQuery, pRecord) =>
+	{
+		console.log('Title:', pRecord.Title);
+	});
+
+meadow.doReads(
+	meadow.query.setCap(10),
+	(pError, pQuery, pRecords) =>
+	{
+		pRecords.forEach((pBook) => console.log(pBook.Title));
+	});
+```
+
+### Update
+
+```javascript
+meadow.doUpdate(
+	meadow.query
+		.addFilter('IDBook', 1)
+		.addRecord({ Title: 'Updated Title' }),
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('Updated:', pRecord.Title);
+	});
+```
+
+### Delete
+
+```javascript
+meadow.doDelete(
+	meadow.query.addFilter('IDBook', 1),
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Deleted rows:', pResult);
+	});
+```
+
+### Count
+
+```javascript
+meadow.doCount(
+	meadow.query,
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Total books:', pCount);
+	});
+```
+
+## Data Binding
+
+The ALASQL provider offers special methods for directly binding JavaScript data to tables, which is useful for initializing state or importing datasets.
+
+### Bind an Array to a Table
+
+```javascript
+// Directly assign an array as the table's data
+meadow.provider.bindObject(
+[
+	{ IDBook: 1, Title: 'Dune', Author: 'Frank Herbert' },
+	{ IDBook: 2, Title: 'Foundation', Author: 'Isaac Asimov' },
+	{ IDBook: 3, Title: 'Neuromancer', Author: 'William Gibson' }
+]);
+// ALASQL.tables['Book'].data now contains these records
+```
+
+### Construct from Object
+
+The `constructFromObject` method builds a complete Meadow entity from a JavaScript object prototype, optionally including audit columns and importing data:
+
+```javascript
+meadow.provider.constructFromObject(
+{
+	Meadow: meadow,
+	Scope: 'Book',
+	ObjectPrototype:
+	{
+		Title: 'String',
+		Author: 'String',
+		PageCount: 'Numeric'
+	},
+	AuditData: true,       // Auto-generate audit columns
+	Import: true,          // Import the Data array via doCreate
+	Data:
+	[
+		{ Title: 'Dune', Author: 'Frank Herbert', PageCount: 412 },
+		{ Title: 'Foundation', Author: 'Isaac Asimov', PageCount: 244 }
+	]
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `Meadow` | object | The Meadow instance to configure |
+| `Scope` | string | Entity name for the table |
+| `ObjectPrototype` | object | Column name to type mapping |
+| `AuditData` | boolean | Add Create/Update/Delete audit columns |
+| `Import` | boolean | Import Data array via `doCreate` operations |
+| `Data` | array | Records to import (when `Import` is `true`) |
+
+## Browser Usage
+
+ALASQL is the recommended provider for browser-based Meadow applications. When bundled with Browserify or another bundler, Meadow with ALASQL provides a full SQL database in the browser.
+
+```javascript
+// In a browser bundle:
+const libFable = require('fable').new();
+const libALASQL = require('alasql');
+const libMeadow = require('meadow');
+
+libFable.ALASQL = libALASQL;
+
+const meadow = libMeadow.new(libFable, 'Task')
+	.setProvider('ALASQL')
+	.setDefaultIdentifier('IDTask')
+	.setSchema([
+		{ Column: 'IDTask', Type: 'AutoIdentity' },
+		{ Column: 'Description', Type: 'String', Size: '255' },
+		{ Column: 'Complete', Type: 'Boolean' }
+	]);
+
+// Full CRUD operations in the browser
+meadow.doCreate(
+	meadow.query.addRecord({ Description: 'Buy groceries', Complete: false }),
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		console.log('Created task:', pRecord.IDTask);
+	});
+```
+
+## When to Use ALASQL
+
+| Use Case | Recommendation |
+|----------|---------------|
+| Unit testing | Excellent — no database setup, fast, deterministic |
+| Browser applications | Excellent — full SQL in the browser |
+| Rapid prototyping | Excellent — start coding immediately |
+| Production server | Consider MySQL or MSSQL instead |
+| Data persistence | Data is in-memory only (lost on refresh/restart) |
+
+## Error Handling
+
+All operations are wrapped in try-catch blocks. Errors are stored in `pQuery.parameters.result.error` and the `executed` flag is always set to `true`.
+
+## Related Documentation
+
+- [Providers Overview](providers/README.md) — Comparison of all providers
+- [MySQL Provider](providers/mysql.md) — Production MySQL alternative
+- [SQLite Provider](providers/sqlite.md) — Lightweight embedded alternative
+- [Schema](schema/README.md) — Schema definitions that drive table creation