meadow 2.0.17 → 2.0.18

package/docs/query/create.md

@@ -0,0 +1,226 @@
+# Create
+
+> Insert new records into the database
+
+The `doCreate` method inserts a new record and returns the fully hydrated object, including any auto-generated fields like the primary key, GUID, and creation timestamps.
+
+## Method Signature
+
+```javascript
+meadow.doCreate(pQuery, fCallBack)
+```
+
+### Callback
+
+```javascript
+fCallBack(pError, pCreateQuery, pReadQuery, pRecord)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pError` | object/null | Error object if the operation failed, null on success |
+| `pCreateQuery` | object | The query used for the INSERT operation |
+| `pReadQuery` | object | The query used to read back the created record |
+| `pRecord` | object | The fully hydrated record with all auto-generated fields |
+
+## Basic Usage
+
+```javascript
+const tmpQuery = meadow.query.addRecord(
+	{
+		Title: 'Neuromancer',
+		Author: 'William Gibson',
+		PublishYear: 1984
+	});
+
+meadow.doCreate(tmpQuery,
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		if (pError)
+		{
+			return console.log('Create failed:', pError);
+		}
+		console.log('Created book:', pRecord.IDBook);
+		console.log('GUID:', pRecord.GUIDBook);
+		console.log('Created at:', pRecord.CreateDate);
+	});
+```
+
+## How It Works
+
+The create operation follows a multi-step waterfall:
+
+```
+1. GUID Uniqueness Check (if GUID provided)
+   └── Queries DB to verify no existing record has this GUID
+2. Insert Record
+   └── Merges record with schema defaults, executes INSERT
+3. Validate Creation
+   └── Confirms the insert succeeded, extracts new ID
+4. Read Back Record
+   └── Fetches the complete record using the new ID
+5. Marshal to Object
+   └── Converts DB result to a plain JavaScript object
+```
+
+## GUID Uniqueness
+
+If your record includes a GUID value (and the value is at least 5 characters), Meadow automatically checks for uniqueness before inserting:
+
+```javascript
+const tmpQuery = meadow.query.addRecord(
+	{
+		GUIDBook: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+		Title: 'Dune'
+	});
+
+meadow.doCreate(tmpQuery,
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		// If the GUID already exists, pError will contain:
+		// "Record with GUID a1b2c3d4-e5f6-7890-abcd-ef1234567890 already exists!"
+	});
+```
+
+The GUID check searches across all records, including soft-deleted ones (it sets `disableDeleteTracking` to `true` for the uniqueness query). If you do not provide a GUID, the `AutoGUID` schema type generates one automatically.
+
+## Auto-Populated Fields
+
+When your schema includes these column types, Meadow populates them automatically during creation:
+
+| Schema Type | Behavior on Create |
+|-------------|-------------------|
+| `AutoIdentity` | Generated by the database (auto-increment) |
+| `AutoGUID` | Generated if not provided in the record |
+| `CreateDate` | Set to `NOW()` by the database |
+| `CreateIDUser` | Set to the current user ID |
+| `UpdateDate` | Not set on create |
+| `UpdateIDUser` | Not set on create |
+| `Deleted` | Set to `0` (from schema defaults) |
+
+## Setting User Identity
+
+The creating user ID is determined in this order of precedence:
+
+```javascript
+// 1. Set on the query object directly
+const tmpQuery = meadow.query.addRecord({ Title: 'Dune' });
+tmpQuery.query.IDUser = 42;
+
+// 2. Set on the Meadow instance
+meadow.setIDUser(42);
+// This applies to all subsequent operations
+
+// 3. Set via the userID property on the query parameters
+const tmpQuery = meadow.query.addRecord({ Title: 'Dune' });
+tmpQuery.parameters.userID = 42;
+```
+
+## Creating with Specific Fields
+
+Only fields present in your schema are included in the INSERT statement. Extra fields are ignored:
+
+```javascript
+const tmpQuery = meadow.query.addRecord(
+	{
+		Title: 'Foundation',
+		Author: 'Isaac Asimov',
+		NotASchemaField: 'this will be ignored'
+	});
+
+meadow.doCreate(tmpQuery,
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		// pRecord will not contain NotASchemaField
+		// It WILL contain all schema defaults plus auto-generated fields
+	});
+```
+
+## Error Handling
+
+Common error conditions:
+
+```javascript
+meadow.doCreate(tmpQuery,
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		if (pError)
+		{
+			// Possible errors:
+			// - "No record submitted" (empty or missing addRecord)
+			// - "Creation failed" (database insert error)
+			// - "Record with GUID ... already exists!" (duplicate GUID)
+			// - Provider-specific database errors
+			console.log('Error:', pError);
+		}
+	});
+```
+
+## Raw Query Override
+
+The Create operation does not support raw query overrides for the INSERT step. However, the read-back step (which fetches the newly created record) does respect the `Read` query override:
+
+```javascript
+// This will be used when reading back the created record
+meadow.rawQueries.setQuery('Read',
+	'SELECT b.*, a.Name AS AuthorName FROM Book b JOIN Author a ON b.IDAuthor = a.IDAuthor WHERE b.IDBook = :IDBook');
+```
+
+## 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: 'CreateDate', Type: 'CreateDate' },
+		{ Column: 'CreatingIDUser', Type: 'CreateIDUser' },
+		{ Column: 'UpdateDate', Type: 'UpdateDate' },
+		{ Column: 'UpdatingIDUser', Type: 'UpdateIDUser' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+
+// Set the user performing the operation
+meadow.setIDUser(1);
+
+// Build the create query
+const tmpQuery = meadow.query.addRecord(
+	{
+		Title: 'Snow Crash',
+		Author: 'Neal Stephenson',
+		Price: 14.99
+	});
+
+// Execute the create
+meadow.doCreate(tmpQuery,
+	(pError, pCreateQuery, pReadQuery, pRecord) =>
+	{
+		if (pError)
+		{
+			return console.log('Failed to create book:', pError);
+		}
+
+		// pRecord now contains the full record:
+		// {
+		//   IDBook: 1,                    (auto-generated)
+		//   GUIDBook: '0x...',            (auto-generated)
+		//   Title: 'Snow Crash',
+		//   Author: 'Neal Stephenson',
+		//   Price: 14.99,
+		//   CreateDate: '2024-01-15...',  (auto-generated)
+		//   CreatingIDUser: 1,            (from setIDUser)
+		//   UpdateDate: null,
+		//   UpdatingIDUser: 0,
+		//   Deleted: 0
+		// }
+		console.log('Book created:', pRecord.IDBook, '-', pRecord.Title);
+	});
+```

package/docs/query/delete.md

@@ -0,0 +1,264 @@
+# Delete
+
+> Soft delete, hard delete, and undelete records
+
+Meadow supports both soft deletes (logical deletion) and hard deletes (physical removal), depending on your schema. When your schema includes a `Deleted` column, delete operations set a flag rather than removing the record. Meadow also provides an undelete operation to restore soft-deleted records.
+
+## doDelete
+
+### Method Signature
+
+```javascript
+meadow.doDelete(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 | Number of affected records |
+
+### Basic Usage
+
+```javascript
+meadow.doDelete(meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pCount) =>
+	{
+		if (pError)
+		{
+			return console.log('Delete failed:', pError);
+		}
+		console.log('Deleted', pCount, 'record(s)');
+	});
+```
+
+## Soft Delete vs Hard Delete
+
+The behavior depends on whether your schema includes a `Deleted` column:
+
+### Soft Delete (Schema has `Deleted` field)
+
+When the schema includes `{ Column: 'Deleted', Type: 'Deleted' }`, the delete operation generates an UPDATE statement instead of a DELETE:
+
+```sql
+-- What Meadow generates for soft delete:
+UPDATE Book SET Deleted = 1, DeleteDate = NOW(), DeletingIDUser = :IDUser,
+  UpdateDate = NOW() WHERE IDBook = :IDBook
+```
+
+The record remains in the database but is excluded from normal queries.
+
+```javascript
+// Schema includes Deleted column
+const meadow = libMeadow.new(libFable, 'Book')
+	.setDefaultIdentifier('IDBook')
+	.setSchema([
+		{ Column: 'IDBook', Type: 'AutoIdentity' },
+		{ Column: 'Title', Type: 'String', Size: '255' },
+		{ Column: 'DeleteDate', Type: 'DeleteDate' },
+		{ Column: 'DeletingIDUser', Type: 'DeleteIDUser' },
+		{ Column: 'UpdateDate', Type: 'UpdateDate' },
+		{ Column: 'UpdatingIDUser', Type: 'UpdateIDUser' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+
+meadow.setIDUser(5);
+
+meadow.doDelete(meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pCount) =>
+	{
+		// Record 42 now has:
+		//   Deleted = 1
+		//   DeleteDate = NOW()
+		//   DeletingIDUser = 5
+		//   UpdateDate = NOW()
+		// The record is still in the database
+	});
+```
+
+### Hard Delete (Schema without `Deleted` field)
+
+When there is no `Deleted` column in the schema, the delete operation generates an actual DELETE statement:
+
+```sql
+-- What Meadow generates for hard delete:
+DELETE FROM Book WHERE IDBook = :IDBook
+```
+
+The record is physically removed from the database.
+
+### Auto-Populated Fields on Soft Delete
+
+| Schema Type | Behavior on Delete |
+|-------------|-------------------|
+| `Deleted` | Set to `1` |
+| `DeleteDate` | Set to `NOW()` |
+| `DeleteIDUser` | Set to the current user ID |
+| `UpdateDate` | Set to `NOW()` (a delete is an update) |
+| `UpdateIDUser` | Set to the current user ID |
+| All others | **Not modified** |
+
+## Soft Delete and Read Queries
+
+After soft deletion, the record is automatically excluded from normal reads:
+
+```javascript
+// This will NOT find the soft-deleted book
+meadow.doRead(meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pRecord) =>
+	{
+		// pRecord is undefined -- the book appears "deleted"
+	});
+
+// To find soft-deleted records, disable delete tracking
+meadow.doRead(meadow.query.addFilter('IDBook', 42).setDisableDeleteTracking(true),
+	(pError, pQuery, pRecord) =>
+	{
+		// pRecord is the soft-deleted book with Deleted = 1
+	});
+```
+
+---
+
+## doUndelete
+
+### Method Signature
+
+```javascript
+meadow.doUndelete(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 | Number of affected records |
+
+### Basic Usage
+
+```javascript
+meadow.doUndelete(meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pCount) =>
+	{
+		if (pError)
+		{
+			return console.log('Undelete failed:', pError);
+		}
+		console.log('Restored', pCount, 'record(s)');
+	});
+```
+
+### How Undelete Works
+
+The undelete operation generates an UPDATE statement that reverses the soft delete:
+
+```sql
+UPDATE Book SET Deleted = 0, UpdateDate = NOW(), UpdatingIDUser = :IDUser
+  WHERE IDBook = :IDBook
+```
+
+Note that `DeleteDate` and `DeletingIDUser` are **not cleared** -- they remain as a historical record of when the record was deleted.
+
+### Auto-Populated Fields on Undelete
+
+| Schema Type | Behavior on Undelete |
+|-------------|---------------------|
+| `Deleted` | Set to `0` |
+| `UpdateDate` | Set to `NOW()` |
+| `UpdateIDUser` | Set to the current user ID |
+| `DeleteDate` | **Not modified** (preserved as history) |
+| `DeleteIDUser` | **Not modified** (preserved as history) |
+
+---
+
+## Raw Query Override
+
+Both delete and undelete operations respect their respective raw query overrides:
+
+```javascript
+// Override the delete query
+meadow.rawQueries.setQuery('Delete',
+	'UPDATE Book SET Deleted = 1, DeleteDate = NOW() WHERE IDBook = :IDBook AND IDCustomer = :IDCustomer');
+
+// Override the undelete query
+meadow.rawQueries.setQuery('Undelete',
+	'UPDATE Book SET Deleted = 0, UpdateDate = NOW() WHERE IDBook = :IDBook AND IDCustomer = :IDCustomer');
+```
+
+## Full Example: Delete and Restore Workflow
+
+```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: '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' }
+	]);
+
+meadow.setIDUser(5);
+
+// Step 1: Soft delete book 42
+meadow.doDelete(meadow.query.addFilter('IDBook', 42),
+	(pError, pQuery, pCount) =>
+	{
+		console.log('Soft deleted', pCount, 'record(s)');
+
+		// Step 2: Verify it's gone from normal queries
+		meadow.doRead(meadow.query.addFilter('IDBook', 42),
+			(pError, pQuery, pRecord) =>
+			{
+				console.log('Normal read found record:', !!pRecord);
+				// false -- record appears deleted
+
+				// Step 3: It's still there if we look for it
+				meadow.doRead(
+					meadow.query.addFilter('IDBook', 42).setDisableDeleteTracking(true),
+					(pError, pQuery, pRecord) =>
+					{
+						console.log('With delete tracking disabled:', pRecord.Title);
+						console.log('Deleted flag:', pRecord.Deleted);
+						// Deleted = 1, record is still in DB
+
+						// Step 4: Restore it
+						meadow.doUndelete(meadow.query.addFilter('IDBook', 42),
+							(pError, pQuery, pCount) =>
+							{
+								console.log('Restored', pCount, 'record(s)');
+
+								// Step 5: Now it shows up in normal queries again
+								meadow.doRead(meadow.query.addFilter('IDBook', 42),
+									(pError, pQuery, pRecord) =>
+									{
+										console.log('Restored:', pRecord.Title);
+										console.log('Deleted flag:', pRecord.Deleted);
+										// Deleted = 0, record is visible again
+									});
+							});
+					});
+			});
+	});
+```