meadow 2.0.17 → 2.0.18

package/docs/providers/sqlite.md

@@ -0,0 +1,173 @@
+# SQLite Provider
+
+> Lightweight embedded SQL for local development and compact deployments
+
+The SQLite provider connects Meadow to SQLite databases, offering a zero-configuration embedded database option. It's ideal for local development, testing, and applications that need a lightweight persistent store without a separate database server.
+
+## Setup
+
+### Install Dependencies
+
+```bash
+npm install meadow meadow-connection-sqlite
+```
+
+### Register the Connection
+
+```javascript
+const libFable = require('fable').new();
+const libMeadowConnectionSQLite = require('meadow-connection-sqlite');
+
+// Register the connection service
+libFable.serviceManager.addServiceType('MeadowMySQLProvider', libMeadowConnectionSQLite);
+libFable.serviceManager.instantiateServiceProvider('MeadowMySQLProvider');
+```
+
+### Create a Meadow DAL
+
+```javascript
+const libMeadow = require('meadow');
+
+const meadow = libMeadow.new(libFable, 'Book')
+	.setProvider('SQLite')
+	.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 Management
+
+The SQLite provider uses the same connection pool interface as the MySQL provider. Each operation:
+
+1. Acquires a connection via `pool.getConnection()`
+2. Executes the generated SQL query
+3. Releases the connection back to the pool
+
+## CRUD Operations
+
+### Create
+
+Executes an INSERT 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 with SQLite dialect: `pQuery.setDialect('SQLite').buildCreateQuery()`
+- Extracts identity: `result.insertId`
+
+### Read
+
+Executes a SELECT and returns result rows.
+
+```javascript
+meadow.doRead(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pRecord) =>
+	{
+		console.log('Title:', pRecord.Title);
+	});
+
+meadow.doReads(
+	meadow.query.setCap(25).setBegin(0),
+	(pError, pQuery, pRecords) =>
+	{
+		console.log('Found', pRecords.length, 'books');
+	});
+```
+
+### 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);
+	});
+```
+
+### Delete
+
+Executes a soft delete and returns the affected row count.
+
+```javascript
+meadow.doDelete(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Deleted rows:', pResult);
+	});
+```
+
+### Undelete
+
+Reverses a soft delete.
+
+```javascript
+meadow.doUndelete(
+	meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pResult) =>
+	{
+		console.log('Restored rows:', pResult);
+	});
+```
+
+### Count
+
+Returns the matching record count.
+
+```javascript
+meadow.doCount(
+	meadow.query,
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Total books:', pCount);
+	});
+```
+
+## When to Use SQLite
+
+| Use Case | Recommendation |
+|----------|---------------|
+| Local development | Great — no server setup required |
+| Unit testing | Good — fast, in-process database |
+| Small production apps | Good — for low-concurrency workloads |
+| High-concurrency production | Consider MySQL or MSSQL instead |
+| Browser applications | Use ALASQL provider instead |
+
+## Error Handling
+
+The SQLite provider follows the same error handling pattern as MySQL:
+
+- Database errors are stored in `pQuery.parameters.result.error`
+- Identity/rowcount extraction failures are logged as warnings
+- Connection errors bubble through the callback
+
+## Related Documentation
+
+- [Providers Overview](providers/README.md) — Comparison of all providers
+- [MySQL Provider](providers/mysql.md) — MySQL/MariaDB for production
+- [ALASQL Provider](providers/alasql.md) — In-memory alternative
+- [meadow-connection-sqlite](https://github.com/stevenvelozo/meadow-connection-sqlite) — Connection module source

package/docs/query/README.md

@@ -0,0 +1,175 @@
+# Query Objects
+
+> Building and configuring queries with the FoxHound DSL
+
+Every data operation in Meadow begins with a query object. Meadow uses [FoxHound](https://github.com/stevenvelozo/foxhound) as its query DSL, generating dialect-specific SQL from a fluent, chainable API. You never need to construct FoxHound directly -- Meadow gives you a fresh, pre-configured query every time you access the `.query` property.
+
+## Getting a Query Object
+
+```javascript
+const tmpQuery = meadow.query;
+```
+
+This returns a **cloned** FoxHound instance with the entity scope and schema already set. Each call to `.query` returns a new independent clone, so queries never leak state between operations.
+
+```javascript
+// These are two completely separate queries
+const tmpQueryA = meadow.query.addFilter('IDBook', 1);
+const tmpQueryB = meadow.query.addFilter('Author', 'Asimov');
+
+// tmpQueryA and tmpQueryB do not affect each other
+```
+
+## Chainable Methods
+
+Query methods return the query object itself, so you can chain them together fluently.
+
+### Filtering
+
+```javascript
+// Simple equality filter
+meadow.query.addFilter('IDBook', 42)
+
+// Multiple filters (AND)
+meadow.query
+	.addFilter('Author', 'Herbert')
+	.addFilter('InPrint', 1)
+
+// Filter with operator
+meadow.query.addFilter('Price', 20, '>')
+
+// Filter with IN clause (array value)
+meadow.query.addFilter('IDCategory', [1, 3, 5])
+```
+
+Supported filter operators: `=`, `!=`, `>`, `<`, `>=`, `<=`, `LIKE`, `IN`
+
+### Pagination
+
+```javascript
+// Limit to 25 records starting from record 50
+meadow.query
+	.setCap(25)
+	.setBegin(50)
+```
+
+| Method | Description |
+|--------|-------------|
+| `setCap(pNumber)` | Maximum records to return (SQL `LIMIT`) |
+| `setBegin(pNumber)` | Starting offset (SQL `OFFSET`) |
+
+### Sorting
+
+```javascript
+// Sort by Title ascending
+meadow.query.addSort({ Column: 'Title', Direction: 'ASC' })
+
+// Multiple sort columns
+meadow.query
+	.addSort({ Column: 'Author', Direction: 'ASC' })
+	.addSort({ Column: 'PublishDate', Direction: 'DESC' })
+```
+
+### Column Selection
+
+```javascript
+// Only retrieve specific columns
+meadow.query.setDataElements(['IDBook', 'Title', 'Author'])
+```
+
+### Distinct Queries
+
+```javascript
+// Return only unique combinations
+meadow.query
+	.setDistinct(true)
+	.setDataElements(['Author', 'Publisher'])
+```
+
+### Records for Create and Update
+
+```javascript
+// Add a record for insert or update
+meadow.query.addRecord({ Title: 'Neuromancer', Author: 'William Gibson' })
+```
+
+The `addRecord()` method attaches data that will be used by create and update operations. For updates, only the fields present in the record will be modified.
+
+### Delete Tracking
+
+```javascript
+// Include soft-deleted records in results
+meadow.query.setDisableDeleteTracking(true)
+```
+
+By default, queries automatically exclude records where the `Deleted` column is `1`. Use `setDisableDeleteTracking(true)` to include them.
+
+## Query Lifecycle
+
+When you pass a query to a CRUD method, Meadow handles the rest:
+
+```
+1. meadow.query          → Clone a fresh FoxHound query with scope and schema
+2. .addFilter(...)       → Configure the query parameters
+3. .addRecord(...)       → Attach data (for create/update)
+4. meadow.doRead(query)  → Meadow sets the dialect, builds SQL, executes via provider
+5. callback(error, ...)  → Results returned through callback
+```
+
+You never need to call `setDialect()` or `buildReadQuery()` yourself -- Meadow's behavior modules handle dialect selection and SQL generation based on the configured provider.
+
+## User Identity
+
+Meadow stamps user identity into create, update, and delete operations automatically. Set the user ID before operations:
+
+```javascript
+// Set user ID for audit stamping
+meadow.setIDUser(currentUserID);
+
+// Or set it per-query
+const tmpQuery = meadow.query;
+tmpQuery.query.IDUser = currentUserID;
+```
+
+This user ID is written to `CreateIDUser`, `UpdateIDUser`, and `DeleteIDUser` columns when those schema types are present.
+
+### Disabling Auto-Stamps
+
+For special cases like data migration, you can disable automatic stamping:
+
+```javascript
+const tmpQuery = meadow.query.addRecord(migrationRecord);
+tmpQuery.query.disableAutoDateStamp = true;  // Skip UpdateDate = NOW()
+tmpQuery.query.disableAutoUserStamp = true;  // Skip UpdateIDUser = :IDUser
+```
+
+## Query State
+
+Under the hood, the query object carries state that Meadow and the provider use:
+
+| Property | Description |
+|----------|-------------|
+| `query.scope` | Entity/table name |
+| `query.cap` | Record limit |
+| `query.begin` | Record offset |
+| `query.dataElements` | Selected columns |
+| `query.sort` | Sort configuration |
+| `query.filter` | Filter conditions |
+| `query.records` | Records for create/update |
+| `query.schema` | Column schema definitions |
+| `query.IDUser` | User ID for audit stamps |
+| `query.disableDeleteTracking` | Include soft-deleted records |
+| `query.disableAutoDateStamp` | Skip auto date stamps |
+| `query.disableAutoUserStamp` | Skip auto user stamps |
+| `result.executed` | Whether the query has been run |
+| `result.value` | Result data (ID, rows, count) |
+
+## CRUD Operations
+
+Each CRUD operation uses the query object differently. See the detailed documentation for each:
+
+- [Create](create.md) - Insert new records
+- [Read](read.md) - Retrieve single and multiple records
+- [Update](update.md) - Modify existing records
+- [Delete](delete.md) - Soft delete and undelete records
+- [Count](count.md) - Count records matching criteria

package/docs/query/count.md

@@ -0,0 +1,228 @@
+# Count
+
+> Count records matching query criteria
+
+The `doCount` method returns the number of records matching your query filters. It automatically excludes soft-deleted records (unless disabled) and includes slow query profiling for performance monitoring.
+
+## Method Signature
+
+```javascript
+meadow.doCount(pQuery, fCallBack)
+```
+
+### Callback
+
+```javascript
+fCallBack(pError, pQuery, pCount)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pError` | object/null | Error object if the operation failed, null on success |
+| `pQuery` | object | The query that was executed |
+| `pCount` | number | The record count |
+
+## Basic Usage
+
+```javascript
+// Count all records
+meadow.doCount(meadow.query,
+	(pError, pQuery, pCount) =>
+	{
+		if (pError)
+		{
+			return console.log('Count failed:', pError);
+		}
+		console.log('Total books:', pCount);
+	});
+```
+
+## Filtered Counts
+
+```javascript
+// Count books by a specific author
+meadow.doCount(meadow.query.addFilter('Author', 'Asimov'),
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Asimov books:', pCount);
+	});
+
+// Count books published after 2000
+meadow.doCount(meadow.query.addFilter('PublishYear', 2000, '>'),
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Post-2000 books:', pCount);
+	});
+
+// Count with multiple filters
+const tmpQuery = meadow.query
+	.addFilter('Author', 'Herbert')
+	.addFilter('InPrint', 1);
+
+meadow.doCount(tmpQuery,
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Herbert books in print:', pCount);
+	});
+```
+
+## How It Works
+
+```
+1. Build Count Query
+   └── Apply filters, set dialect, generate SELECT COUNT(*) SQL
+2. Execute via Provider
+   └── Run query against database, start performance timer
+3. Validate and Profile
+   └── Verify result is a number, log warning if query exceeded threshold
+```
+
+## Soft Delete Filtering
+
+By default, the count excludes soft-deleted records:
+
+```javascript
+// Count only active records (default)
+meadow.doCount(meadow.query,
+	(pError, pQuery, pActiveCount) =>
+	{
+		console.log('Active books:', pActiveCount);
+	});
+
+// Count ALL records including soft-deleted
+meadow.doCount(meadow.query.setDisableDeleteTracking(true),
+	(pError, pQuery, pTotalCount) =>
+	{
+		console.log('Total books (including deleted):', pTotalCount);
+	});
+```
+
+## Slow Query Profiling
+
+Like `doReads`, the count operation profiles execution time and logs a warning for slow queries:
+
+```javascript
+// Configure the threshold (default: 200ms)
+const _Fable = require('fable').new(
+	{
+		QueryThresholdWarnTime: 500
+	});
+```
+
+When a count query exceeds the threshold, Meadow logs a warning with the provider name, SQL body, parameters, and full interpolated query.
+
+## Pagination Pattern
+
+Count is commonly used together with `doReads` to implement pagination:
+
+```javascript
+const PAGE_SIZE = 25;
+let currentPage = 0;
+
+// First, get the total count
+meadow.doCount(meadow.query.addFilter('Author', 'Asimov'),
+	(pError, pQuery, pTotalCount) =>
+	{
+		const totalPages = Math.ceil(pTotalCount / PAGE_SIZE);
+		console.log('Total records:', pTotalCount, 'Pages:', totalPages);
+
+		// Then fetch the current page
+		const tmpQuery = meadow.query
+			.addFilter('Author', 'Asimov')
+			.setCap(PAGE_SIZE)
+			.setBegin(currentPage * PAGE_SIZE)
+			.addSort({ Column: 'Title', Direction: 'ASC' });
+
+		meadow.doReads(tmpQuery,
+			(pError, pQuery, pRecords) =>
+			{
+				console.log(`Page ${currentPage + 1} of ${totalPages}:`);
+				pRecords.forEach((pBook) =>
+				{
+					console.log('  -', pBook.Title);
+				});
+			});
+	});
+```
+
+## Error Handling
+
+```javascript
+meadow.doCount(meadow.query,
+	(pError, pQuery, pCount) =>
+	{
+		if (pError)
+		{
+			// Possible errors:
+			// - "Count did not return valid results."
+			//     (provider returned non-numeric value)
+			// - Provider-specific database errors
+			console.log('Error:', pError);
+		}
+	});
+```
+
+## Raw Query Override
+
+The count operation respects the `Count` raw query override:
+
+```javascript
+// Override with a custom count query
+meadow.rawQueries.setQuery('Count',
+	'SELECT COUNT(DISTINCT Author) AS RowCount FROM Book WHERE Deleted = 0');
+
+meadow.doCount(meadow.query,
+	(pError, pQuery, pCount) =>
+	{
+		// pCount is the number of unique authors
+	});
+```
+
+## Full Example
+
+```javascript
+const libFable = require('fable').new(
+	{
+		QueryThresholdWarnTime: 300
+	});
+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' },
+		{ Column: 'Author', Type: 'String', Size: '128' },
+		{ Column: 'PublishYear', Type: 'Numeric' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+
+// Count all active books
+meadow.doCount(meadow.query,
+	(pError, pQuery, pTotal) =>
+	{
+		console.log('Total active books:', pTotal);
+	});
+
+// Count by author
+meadow.doCount(meadow.query.addFilter('Author', 'Bradbury'),
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Bradbury books:', pCount);
+	});
+
+// Count including soft-deleted for an audit report
+meadow.doCount(meadow.query.setDisableDeleteTracking(true),
+	(pError, pQuery, pAllCount) =>
+	{
+		meadow.doCount(meadow.query,
+			(pError, pQuery, pActiveCount) =>
+			{
+				const deletedCount = pAllCount - pActiveCount;
+				console.log('Active:', pActiveCount);
+				console.log('Deleted:', deletedCount);
+				console.log('Total:', pAllCount);
+			});
+	});
+```