meadow 2.0.17 → 2.0.18

package/docs/query/read.md

@@ -0,0 +1,350 @@
+# Read
+
+> Retrieve single or multiple records from the database
+
+Meadow provides two read methods: `doRead` for fetching a single record and `doReads` for fetching multiple records with pagination, filtering, and performance profiling.
+
+## doRead - Single Record
+
+### Method Signature
+
+```javascript
+meadow.doRead(pQuery, fCallBack)
+```
+
+### Callback
+
+```javascript
+fCallBack(pError, pQuery, pRecord)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pError` | object/null | Error object if the operation failed, null on success |
+| `pQuery` | object | The query that was executed |
+| `pRecord` | object/undefined | The marshaled record, or `undefined` if not found |
+
+### Basic Usage
+
+```javascript
+// Read a single book by ID
+meadow.doRead(meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pRecord) =>
+	{
+		if (pError)
+		{
+			return console.log('Read error:', pError);
+		}
+		if (!pRecord)
+		{
+			return console.log('Book not found');
+		}
+		console.log('Found:', pRecord.Title, 'by', pRecord.Author);
+	});
+```
+
+### Reading by GUID
+
+```javascript
+meadow.doRead(meadow.query.addFilter('GUIDBook', 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'),
+	(pError, pQuery, pRecord) =>
+	{
+		if (pRecord)
+		{
+			console.log('Found book:', pRecord.Title);
+		}
+	});
+```
+
+### Reading with Multiple Filters
+
+```javascript
+const tmpQuery = meadow.query
+	.addFilter('Author', 'Asimov')
+	.addFilter('InPrint', 1);
+
+meadow.doRead(tmpQuery,
+	(pError, pQuery, pRecord) =>
+	{
+		// Returns the first matching record
+		if (pRecord)
+		{
+			console.log('Found:', pRecord.Title);
+		}
+	});
+```
+
+### How It Works
+
+```
+1. Build Read Query
+   └── Apply filters, set dialect, generate SELECT SQL
+2. Execute via Provider
+   └── Run query against database
+3. Marshal Record
+   └── Convert DB row to plain JavaScript object using schema defaults
+```
+
+The read operation returns only the first matching record. If no record matches, the callback receives `undefined` as the record parameter (not an error).
+
+---
+
+## doReads - Multiple Records
+
+### Method Signature
+
+```javascript
+meadow.doReads(pQuery, fCallBack)
+```
+
+### Callback
+
+```javascript
+fCallBack(pError, pQuery, pRecords)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pError` | object/null | Error object if the operation failed, null on success |
+| `pQuery` | object | The query that was executed |
+| `pRecords` | array | Array of marshaled records (empty array if none found) |
+
+### Basic Usage
+
+```javascript
+// Read all books (up to default cap)
+meadow.doReads(meadow.query,
+	(pError, pQuery, pRecords) =>
+	{
+		if (pError)
+		{
+			return console.log('Read error:', pError);
+		}
+		console.log('Found', pRecords.length, 'books');
+		pRecords.forEach((pBook) =>
+		{
+			console.log('-', pBook.Title);
+		});
+	});
+```
+
+### Pagination
+
+```javascript
+// Page 1: first 25 records
+meadow.doReads(meadow.query.setCap(25).setBegin(0),
+	(pError, pQuery, pRecords) =>
+	{
+		console.log('Page 1:', pRecords.length, 'records');
+	});
+
+// Page 2: next 25 records
+meadow.doReads(meadow.query.setCap(25).setBegin(25),
+	(pError, pQuery, pRecords) =>
+	{
+		console.log('Page 2:', pRecords.length, 'records');
+	});
+```
+
+### Filtering
+
+```javascript
+// Read books by a specific author
+meadow.doReads(meadow.query.addFilter('Author', 'Philip K. Dick'),
+	(pError, pQuery, pRecords) =>
+	{
+		console.log('Found', pRecords.length, 'books by PKD');
+	});
+
+// Read with multiple filters
+const tmpQuery = meadow.query
+	.addFilter('Author', 'Asimov')
+	.addFilter('PublishYear', 1950, '>')
+	.setCap(10);
+
+meadow.doReads(tmpQuery,
+	(pError, pQuery, pRecords) =>
+	{
+		console.log('Found', pRecords.length, 'post-1950 Asimov books');
+	});
+```
+
+### Sorting
+
+```javascript
+// Read books sorted by title
+const tmpQuery = meadow.query
+	.addSort({ Column: 'Title', Direction: 'ASC' })
+	.setCap(50);
+
+meadow.doReads(tmpQuery,
+	(pError, pQuery, pRecords) =>
+	{
+		pRecords.forEach((pBook) =>
+		{
+			console.log(pBook.Title);
+		});
+	});
+```
+
+### Column Selection
+
+```javascript
+// Only retrieve specific columns for efficiency
+const tmpQuery = meadow.query
+	.setDataElements(['IDBook', 'Title', 'Author'])
+	.setCap(100);
+
+meadow.doReads(tmpQuery,
+	(pError, pQuery, pRecords) =>
+	{
+		// pRecords still contain all schema default fields,
+		// but only the selected columns will have DB values
+	});
+```
+
+### Distinct Queries
+
+```javascript
+// Get unique author/publisher combinations
+const tmpQuery = meadow.query
+	.setDistinct(true)
+	.setDataElements(['Author', 'Publisher']);
+
+meadow.doReads(tmpQuery,
+	(pError, pQuery, pRecords) =>
+	{
+		pRecords.forEach((pRow) =>
+		{
+			console.log(pRow.Author, '-', pRow.Publisher);
+		});
+	});
+```
+
+### How It Works
+
+```
+1. Build Read Query
+   └── Apply filters, pagination, sorting, set dialect, generate SELECT SQL
+2. Execute via Provider
+   └── Run query against database, start performance timer
+3. Marshal Each Record
+   └── Convert each DB row to plain JavaScript object
+4. Performance Check
+   └── Log warning if query exceeded threshold (default 200ms)
+```
+
+---
+
+## Soft Delete Filtering
+
+By default, both `doRead` and `doReads` automatically exclude soft-deleted records (where `Deleted = 1`). This filter is applied at the SQL dialect level.
+
+```javascript
+// Default: only active records
+meadow.doReads(meadow.query,
+	(pError, pQuery, pRecords) =>
+	{
+		// Soft-deleted records are excluded
+	});
+
+// Include soft-deleted records
+meadow.doReads(meadow.query.setDisableDeleteTracking(true),
+	(pError, pQuery, pRecords) =>
+	{
+		// ALL records returned, including soft-deleted ones
+	});
+```
+
+## Slow Query Profiling
+
+The `doReads` method (and `doCount`) automatically profiles query execution time. If a query exceeds the configured threshold, a warning is logged:
+
+```javascript
+// Configure the threshold (default: 200ms)
+const _Fable = require('fable').new(
+	{
+		QueryThresholdWarnTime: 500  // Warn for queries over 500ms
+	});
+```
+
+The slow query log includes the provider name, SQL body, parameters, and the fully interpolated query string for easy debugging.
+
+## Raw Query Override
+
+Both read operations respect the `Read` raw query override:
+
+```javascript
+// Override the generated SELECT with custom SQL
+meadow.rawQueries.setQuery('Read',
+	'SELECT b.*, a.Name AS AuthorName FROM Book b LEFT JOIN Author a ON b.IDAuthor = a.IDAuthor WHERE b.IDBook = :IDBook');
+
+// This custom query is used for doRead
+meadow.doRead(meadow.query.addFilter('IDBook', 1),
+	(pError, pQuery, pRecord) =>
+	{
+		// pRecord will include the AuthorName from the JOIN
+	});
+```
+
+For `doReads`, use the `Reads` override key:
+
+```javascript
+meadow.rawQueries.setQuery('Reads',
+	'SELECT b.*, COUNT(r.IDReview) AS ReviewCount FROM Book b LEFT JOIN Review r ON b.IDBook = r.IDBook GROUP BY b.IDBook');
+```
+
+## 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: 'GUIDBook', Type: 'AutoGUID' },
+		{ Column: 'Title', Type: 'String', Size: '255' },
+		{ Column: 'Author', Type: 'String', Size: '128' },
+		{ Column: 'PublishYear', Type: 'Numeric' },
+		{ Column: 'Price', Type: 'Decimal', Size: '18,2' },
+		{ Column: 'CreateDate', Type: 'CreateDate' },
+		{ Column: 'CreatingIDUser', Type: 'CreateIDUser' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+
+// Read a single book
+meadow.doRead(meadow.query.addFilter('IDBook', 1),
+	(pError, pQuery, pBook) =>
+	{
+		if (!pError && pBook)
+		{
+			console.log('Book:', pBook.Title);
+		}
+	});
+
+// Read a filtered, sorted, paginated list
+const tmpQuery = meadow.query
+	.addFilter('PublishYear', 1980, '>=')
+	.addSort({ Column: 'Title', Direction: 'ASC' })
+	.setCap(10)
+	.setBegin(0);
+
+meadow.doReads(tmpQuery,
+	(pError, pQuery, pBooks) =>
+	{
+		if (!pError)
+		{
+			console.log('Post-1980 books (page 1):');
+			pBooks.forEach((pBook) =>
+			{
+				console.log(`  ${pBook.Title} (${pBook.PublishYear}) - $${pBook.Price}`);
+			});
+		}
+	});
+```

package/docs/query/update.md

@@ -0,0 +1,250 @@
+# Update
+
+> Modify existing records in the database
+
+The `doUpdate` method modifies an existing record and returns the fully hydrated updated object. Meadow automatically handles audit stamping, safely ignores identity and create-only fields, and reads back the record after updating to ensure you receive the current state.
+
+## Method Signature
+
+```javascript
+meadow.doUpdate(pQuery, fCallBack)
+```
+
+### Callback
+
+```javascript
+fCallBack(pError, pUpdateQuery, pReadQuery, pRecord)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pError` | object/null | Error object if the operation failed, null on success |
+| `pUpdateQuery` | object | The query used for the UPDATE operation |
+| `pReadQuery` | object | The query used to read back the updated record |
+| `pRecord` | object | The fully hydrated record after update |
+
+## Basic Usage
+
+```javascript
+const tmpQuery = meadow.query
+	.addRecord(
+		{
+			IDBook: 42,
+			Title: 'Updated Title',
+			Price: 19.99
+		});
+
+meadow.doUpdate(tmpQuery,
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		if (pError)
+		{
+			return console.log('Update failed:', pError);
+		}
+		console.log('Updated:', pRecord.Title, '- New price:', pRecord.Price);
+		console.log('Last modified:', pRecord.UpdateDate);
+	});
+```
+
+## How It Works
+
+The update operation follows a multi-step waterfall:
+
+```
+1. Validate and Prepare
+   └── Verify record has default identifier, set user ID, add filters
+2. Execute UPDATE
+   └── Run the UPDATE query via provider
+3. Read Back Record
+   └── Fetch the updated record using the same filter
+4. Marshal to Object
+   └── Convert DB result to a plain JavaScript object
+```
+
+## Record Identification
+
+The record you pass to `addRecord()` **must** include the default identifier (e.g., `IDBook`). Meadow uses this to build the WHERE clause:
+
+```javascript
+// The default identifier must be present
+const tmpQuery = meadow.query
+	.addRecord(
+		{
+			IDBook: 42,      // Required: identifies which record to update
+			Title: 'New Title'
+		});
+
+meadow.doUpdate(tmpQuery,
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		// Meadow automatically added: WHERE IDBook = 42
+	});
+```
+
+If the default identifier is missing, the operation fails with an error to prevent accidental mass updates.
+
+## Auto-Populated Fields
+
+When your schema includes these column types, Meadow handles them automatically during updates:
+
+| Schema Type | Behavior on Update |
+|-------------|-------------------|
+| `AutoIdentity` | **Ignored** - cannot modify the primary key |
+| `AutoGUID` | **Ignored** - not modified on update |
+| `CreateDate` | **Ignored** - creation timestamp is immutable |
+| `CreateIDUser` | **Ignored** - creating user is immutable |
+| `UpdateDate` | Set to `NOW()` automatically |
+| `UpdateIDUser` | Set to the current user ID |
+| `DeleteDate` | **Ignored** on standard update |
+| `DeleteIDUser` | **Ignored** on standard update |
+| `Deleted` | Included if present in the record |
+
+## Partial Updates
+
+Only fields present in the record are modified. Other columns remain unchanged:
+
+```javascript
+// Only update the Title -- Author, Price, etc. stay the same
+const tmpQuery = meadow.query
+	.addRecord(
+		{
+			IDBook: 42,
+			Title: 'Just the Title Changes'
+		});
+
+meadow.doUpdate(tmpQuery,
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		// pRecord.Author is unchanged
+		// pRecord.Price is unchanged
+		// pRecord.Title is 'Just the Title Changes'
+		// pRecord.UpdateDate is NOW()
+	});
+```
+
+## Disabling Auto-Stamps
+
+For data migration or special operations, you can disable automatic timestamp and user stamping:
+
+```javascript
+const tmpQuery = meadow.query
+	.addRecord(
+		{
+			IDBook: 42,
+			Title: 'Migrated Data'
+		});
+
+// Disable auto-date stamp (UpdateDate will not be set to NOW())
+tmpQuery.query.disableAutoDateStamp = true;
+
+// Disable auto-user stamp (UpdateIDUser will not be set)
+tmpQuery.query.disableAutoUserStamp = true;
+
+meadow.doUpdate(tmpQuery,
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		// UpdateDate and UpdatingIDUser were not modified
+	});
+```
+
+## Safety: Filter Requirement
+
+Meadow requires at least one filter on the query before executing an update. The default identifier filter is added automatically from the record, but if somehow no filters are present, the operation aborts:
+
+```javascript
+// This will fail safely:
+// "Automated update missing filters... aborting!"
+```
+
+This prevents accidental `UPDATE ... SET ...` without a WHERE clause.
+
+## Error Handling
+
+Common error conditions:
+
+```javascript
+meadow.doUpdate(tmpQuery,
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		if (pError)
+		{
+			// Possible errors:
+			// - "No record submitted" (missing addRecord)
+			// - "Automated update missing default identifier"
+			//     (record doesn't have IDBook or equivalent)
+			// - "Automated update missing filters... aborting!"
+			//     (safety check failed)
+			// - "No record updated." (database returned no affected rows)
+			// - "No record found to update!" (read-back found nothing)
+			// - Provider-specific database errors
+			console.log('Error:', pError);
+		}
+	});
+```
+
+## Raw Query Override
+
+The Update operation does not support raw query overrides for the UPDATE step itself. However, the read-back step respects the `Read` override, so custom JOINs and computed columns appear in the returned record.
+
+## Full Example
+
+```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: 'GUIDBook', Type: 'AutoGUID' },
+		{ Column: 'Title', Type: 'String', Size: '255' },
+		{ Column: 'Author', Type: 'String', Size: '128' },
+		{ Column: 'Price', Type: 'Decimal', Size: '18,2' },
+		{ Column: 'InPrint', Type: 'Boolean' },
+		{ Column: 'CreateDate', Type: 'CreateDate' },
+		{ Column: 'CreatingIDUser', Type: 'CreateIDUser' },
+		{ Column: 'UpdateDate', Type: 'UpdateDate' },
+		{ Column: 'UpdatingIDUser', Type: 'UpdateIDUser' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+
+// Set the user performing the update
+meadow.setIDUser(5);
+
+// Update the price and print status of book 42
+const tmpQuery = meadow.query
+	.addRecord(
+		{
+			IDBook: 42,
+			Price: 24.99,
+			InPrint: true
+		});
+
+meadow.doUpdate(tmpQuery,
+	(pError, pUpdateQuery, pReadQuery, pRecord) =>
+	{
+		if (pError)
+		{
+			return console.log('Update failed:', pError);
+		}
+
+		// pRecord now contains the full updated record:
+		// {
+		//   IDBook: 42,                      (unchanged)
+		//   GUIDBook: '0x...',               (unchanged)
+		//   Title: 'Original Title',         (unchanged)
+		//   Author: 'Original Author',       (unchanged)
+		//   Price: 24.99,                    (updated)
+		//   InPrint: true,                   (updated)
+		//   CreateDate: '2024-01-15...',     (unchanged)
+		//   CreatingIDUser: 1,               (unchanged)
+		//   UpdateDate: '2024-06-20...',     (auto: NOW())
+		//   UpdatingIDUser: 5,               (auto: from setIDUser)
+		//   Deleted: 0                       (unchanged)
+		// }
+		console.log('Updated book', pRecord.IDBook);
+		console.log('New price:', pRecord.Price);
+		console.log('Modified at:', pRecord.UpdateDate, 'by user', pRecord.UpdatingIDUser);
+	});
+```