meadow-endpoints 4.0.7 → 4.0.10

package/docs/crud/read.md

@@ -0,0 +1,324 @@
+# Read Endpoints
+
+> Retrieve records with pagination, filtering, and projections
+
+The Read endpoint group is the largest in Meadow Endpoints, covering single-record reads, paginated lists, filtered queries, select lists for dropdowns, lite projections, and distinct value queries. All list-based endpoints share the `Reads-QueryConfiguration` behavior injection point.
+
+## Routes
+
+### Single Record
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/{v}/{entity}/:IDRecord` | Read a record by its integer ID |
+| GET | `/{v}/{entity}/By/:GUIDRecord` | Read a record by its GUID |
+
+### Record Lists
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/{v}/{entity}/s` | Read records (default cap: 250) |
+| GET | `/{v}/{entity}/s/:Begin/:Cap` | Read with pagination |
+| GET | `/{v}/{entity}/s/FilteredTo/:Filter` | Read with filter expression |
+| GET | `/{v}/{entity}/s/FilteredTo/:Filter/:Begin/:Cap` | Filtered read with pagination |
+| GET | `/{v}/{entity}/s/By/:ByField/:ByValue` | Read by exact field match |
+| GET | `/{v}/{entity}/s/By/:ByField/:ByValue/:Begin/:Cap` | Field match with pagination |
+
+### Aggregation
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/{v}/{entity}/Max/:ColumnName` | Maximum value for a column |
+
+### Specialized Projections
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/{v}/{entity}/Select` | Select list ({Hash, Value} pairs) |
+| GET | `/{v}/{entity}/Select/:Begin/:Cap` | Paginated select list |
+| GET | `/{v}/{entity}/Select/FilteredTo/:Filter` | Filtered select list |
+| GET | `/{v}/{entity}/Select/FilteredTo/:Filter/:Begin/:Cap` | Filtered paginated select list |
+| GET | `/{v}/{entity}/s/Lite` | Lite list (ID + GUID + name only) |
+| GET | `/{v}/{entity}/s/Lite/:Begin/:Cap` | Paginated lite list |
+| GET | `/{v}/{entity}/s/LiteExtended/:ExtraColumns` | Lite list with extra columns |
+| GET | `/{v}/{entity}/s/Distinct/:Columns` | Distinct values for columns |
+| GET | `/{v}/{entity}/s/Distinct/:Columns/:Begin/:Cap` | Paginated distinct list |
+| GET | `/{v}/{entity}/s/Distinct/:Columns/FilteredTo/:Filter` | Filtered distinct list |
+
+## Single Read
+
+**Request:** `GET /1.0/Book/42`
+
+**Response:** A single record object:
+
+```json
+{
+	"IDBook": 42,
+	"GUIDBook": "0x12ab34cd...",
+	"Title": "Dune",
+	"Author": "Frank Herbert",
+	"CreateDate": "2024-01-15T10:30:00.000Z",
+	"CreatingIDUser": 1,
+	"UpdateDate": "2024-01-15T10:30:00.000Z",
+	"UpdatingIDUser": 1,
+	"Deleted": 0
+}
+```
+
+### Single Read Lifecycle
+
+```
+GET /{v}/{entity}/:IDRecord
+  |
+  v
+Initialize Query
+  |
+  v
+[Read-PreOperation]                <-- authorize, modify criteria
+  |
+  v
+Apply filter: IDRecord or GUIDRecord
+  |
+  v
+[Read-QueryConfiguration]          <-- add extra filters, joins
+  |
+  v
+DAL.doRead(query)
+  |
+  v
+[Read-PostOperation]               <-- transform, redact fields
+  |
+  v
+Send response (single record)
+```
+
+## Record List (Reads)
+
+**Request:** `GET /1.0/Book/s/0/25`
+
+**Response:** A newline-delimited JSON stream of records. Each record is a complete JSON object separated by newlines. This streaming approach efficiently handles large recordsets.
+
+### Reads Lifecycle
+
+```
+GET /{v}/{entity}/s/:Begin/:Cap
+  |
+  v
+Build query with pagination (Begin, Cap)
+Parse filter expression (if FilteredTo)
+  |
+  v
+[Reads-QueryConfiguration]         <-- add security filters, modify query
+  |
+  v
+DAL.doReads(query)
+  |
+  v
+[Reads-PostOperation]              <-- transform recordset, aggregate
+  |
+  v
+Stream response (newline-delimited JSON)
+```
+
+## Pagination
+
+All list endpoints support pagination via `Begin` and `Cap` URL parameters:
+
+- **Begin** - Zero-based starting index (skip this many records)
+- **Cap** - Maximum number of records to return
+
+If no `Cap` is provided, the default is `250` (configurable via `MeadowDefaultMaxCap` in Fable settings).
+
+```
+GET /1.0/Book/s           -> records 0-249 (default)
+GET /1.0/Book/s/0/10      -> first 10 records
+GET /1.0/Book/s/10/10     -> records 10-19
+GET /1.0/Book/s/100/50    -> records 100-149
+```
+
+## Filter Expressions
+
+The `FilteredTo` parameter accepts filter expressions parsed by meadow-filter:
+
+```
+GET /1.0/Book/s/FilteredTo/Author~Herbert
+GET /1.0/Book/s/FilteredTo/Title=Dune
+GET /1.0/Book/s/FilteredTo/IDBook>10
+```
+
+| Operator | Meaning |
+|----------|---------|
+| `=` | Equals |
+| `!=` | Not equals |
+| `>` | Greater than |
+| `<` | Less than |
+| `>=` | Greater than or equal |
+| `<=` | Less than or equal |
+| `~` | Contains (LIKE) |
+
+Multiple filters can be combined with semicolons:
+
+```
+GET /1.0/Book/s/FilteredTo/Author~Herbert;Title~Dune
+```
+
+## ReadsBy
+
+The `ReadsBy` endpoint filters by an exact field match:
+
+```
+GET /1.0/Book/s/By/Author/Frank Herbert
+GET /1.0/Book/s/By/Author/Frank Herbert/0/10
+```
+
+When the `ByValue` parameter is an array (passed via query string), it generates an `IN` filter:
+
+```
+GET /1.0/Book/s/By/IDBook/[1,2,3]
+```
+
+## ReadMax
+
+Returns the maximum value for a given column:
+
+```
+GET /1.0/Book/Max/IDBook
+```
+
+## Select List
+
+Returns `{Hash, Value}` pairs suitable for populating dropdowns. The `Hash` is the record's default identifier, and the `Value` is generated from a template:
+
+```
+GET /1.0/Book/Select
+```
+
+**Response:**
+
+```json
+[
+	{ "Hash": 1, "Value": "Book #1" },
+	{ "Hash": 2, "Value": "Book #2" }
+]
+```
+
+The `Value` template defaults to `{Entity} #{ID}` but can be customized via `BehaviorInjection.processTemplate('SelectList', ...)`.
+
+## Lite List
+
+Returns only the identity columns (ID, GUID, and name/label columns) for a compact response:
+
+```
+GET /1.0/Book/s/Lite
+GET /1.0/Book/s/Lite/0/50
+```
+
+### Extended Lite List
+
+Include additional columns by name:
+
+```
+GET /1.0/Book/s/LiteExtended/Author,PublishYear
+```
+
+## Distinct List
+
+Returns distinct values for the specified columns:
+
+```
+GET /1.0/Book/s/Distinct/Author
+GET /1.0/Book/s/Distinct/Author,Publisher/0/100
+GET /1.0/Book/s/Distinct/Author/FilteredTo/PublishYear>2000
+```
+
+## Behavior Injection Points
+
+### Read-PreOperation
+
+Runs before filter criteria are applied on single-record reads. The query object is initialized but no filters are set yet.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Read-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Check if user is authenticated
+		if (!pRequestState.SessionData.LoggedIn)
+		{
+			return fCallback({ Code: 401, Message: 'Authentication required' });
+		}
+		return fCallback();
+	});
+```
+
+### Read-QueryConfiguration
+
+Runs after the ID/GUID filter is applied on single-record reads. Use this to add security filters or additional query constraints.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Read-QueryConfiguration',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Restrict reads to user's own customer
+		pRequestState.Query.addFilter('IDCustomer',
+			pRequestState.SessionData.CustomerID);
+		return fCallback();
+	});
+```
+
+### Read-PostOperation
+
+Runs after the record is retrieved from the database. Use this to transform the result, redact sensitive fields, or load related data.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Read-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Redact sensitive information
+		delete pRequestState.Record.InternalNotes;
+
+		// Add computed fields
+		pRequestState.Record.DisplayName =
+			`${pRequestState.Record.Title} by ${pRequestState.Record.Author}`;
+
+		return fCallback();
+	});
+```
+
+### Reads-QueryConfiguration
+
+Shared across all list-based read endpoints: Reads, ReadsBy, ReadSelectList, ReadLiteList, ReadDistinctList, and ReadMax. Runs after pagination and filter expressions are applied, before the DAL call.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Reads-QueryConfiguration',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Multi-tenant security: always filter by customer
+		if (pRequestState.SessionData.UserRoleIndex < 5)
+		{
+			pRequestState.Query.addFilter('IDCustomer',
+				pRequestState.SessionData.CustomerID);
+		}
+		return fCallback();
+	});
+```
+
+### Reads-PostOperation
+
+Runs after the recordset is retrieved on Reads and ReadsBy endpoints. Use this to transform the array of records before they are streamed to the client.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Reads-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Strip internal fields from all records
+		for (let i = 0; i < pRequestState.Records.length; i++)
+		{
+			delete pRequestState.Records[i].InternalNotes;
+		}
+		return fCallback();
+	});
+```
+
+## Streaming Responses
+
+All list endpoints use `doStreamRecordArray()` to send records as newline-delimited JSON. This approach avoids buffering large result sets in memory and allows the client to begin processing records before the full response is complete.

package/docs/crud/schema.md

@@ -0,0 +1,349 @@
+# Schema Endpoints
+
+> Serve metadata, default records, and validation with customization hooks
+
+The Schema endpoints expose entity metadata over REST: the JSON Schema definition, an empty default record for new-record forms, and record validation. Each endpoint has both pre-operation and post-operation hooks, making them fully customizable.
+
+## Routes
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/{v}/{entity}/Schema` | Return the JSON Schema for the entity |
+| GET | `/{v}/{entity}/Schema/New` | Return an empty default record |
+| POST | `/{v}/{entity}/Schema/Validate` | Validate a record against the schema |
+
+## Schema
+
+**Request:** `GET /1.0/Book/Schema`
+
+**Response:** The entity's JSON Schema definition:
+
+```json
+{
+	"title": "Book",
+	"type": "object",
+	"properties": {
+		"IDBook": { "type": "integer" },
+		"GUIDBook": { "type": "string" },
+		"Title": { "type": "string", "maxLength": 255 },
+		"Author": { "type": "string", "maxLength": 128 },
+		"CreateDate": { "type": "string", "format": "date-time" },
+		"CreatingIDUser": { "type": "integer" },
+		"UpdateDate": { "type": "string", "format": "date-time" },
+		"UpdatingIDUser": { "type": "integer" },
+		"Deleted": { "type": "integer" }
+	}
+}
+```
+
+## New (Default Record)
+
+**Request:** `GET /1.0/Book/Schema/New`
+
+**Response:** An empty record with default values populated from the schema:
+
+```json
+{
+	"IDBook": 0,
+	"GUIDBook": "",
+	"Title": "",
+	"Author": "",
+	"CreateDate": "",
+	"CreatingIDUser": 0,
+	"UpdateDate": "",
+	"UpdatingIDUser": 0,
+	"Deleted": 0
+}
+```
+
+## Validate
+
+**Request:** `POST /1.0/Book/Schema/Validate`
+
+```json
+{
+	"IDBook": 0,
+	"Title": "Dune",
+	"Author": "Frank Herbert"
+}
+```
+
+**Response:** The validation result from the Meadow schema's `validateObject()` method. Returns the validation outcome indicating whether the record conforms to the schema constraints.
+
+## Schema Request Lifecycle
+
+```
+GET /{v}/{entity}/Schema
+  |
+  v
+[Schema-PreOperation]              <-- authorize, customize
+  |
+  v
+Load JSON Schema from DAL (if not set during PreOperation)
+  |
+  v
+[Schema-PostOperation]             <-- filter properties, add metadata
+  |
+  v
+Send response (JSON Schema)
+```
+
+## New Request Lifecycle
+
+```
+GET /{v}/{entity}/Schema/New
+  |
+  v
+[New-PreOperation]                  <-- set custom default record
+  |
+  v
+Build default record from schema (if not set during PreOperation)
+  |
+  v
+[New-PostOperation]                 <-- populate computed defaults
+  |
+  v
+Send response (default record)
+```
+
+## Validate Request Lifecycle
+
+```
+POST /{v}/{entity}/Schema/Validate
+  |
+  v
+[Validate-PreOperation]            <-- add custom validation rules
+  |
+  v
+Validate request body is an object
+  |
+  v
+Run schema validation: DAL.schemaFull.validateObject(record)
+  |
+  v
+[Validate-PostOperation]           <-- augment validation result
+  |
+  v
+Send response (validation result)
+```
+
+## Behavior Injection Points
+
+### Schema-PreOperation
+
+Runs before the JSON Schema is loaded. You can set `pRequest.JSONSchema` during this hook to provide a custom schema instead of the default.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Schema-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Require authentication to view schema
+		if (!pRequestState.SessionData.LoggedIn)
+		{
+			return fCallback({ Code: 401, Message: 'Authentication required' });
+		}
+		return fCallback();
+	});
+```
+
+### Schema-PostOperation
+
+Runs after the JSON Schema is loaded onto `pRequestState.JSONSchema`. Use this to modify the schema before it is sent -- for example, to remove internal columns or add UI hints.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Schema-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Remove internal fields from the public schema
+		if (pRequestState.JSONSchema && pRequestState.JSONSchema.properties)
+		{
+			delete pRequestState.JSONSchema.properties.InternalNotes;
+			delete pRequestState.JSONSchema.properties.InternalStatus;
+		}
+
+		// Add UI metadata
+		if (pRequestState.JSONSchema)
+		{
+			pRequestState.JSONSchema.uiHints = {
+				primaryField: 'Title',
+				searchableFields: ['Title', 'Author']
+			};
+		}
+
+		return fCallback();
+	});
+```
+
+### New-PreOperation
+
+Runs before the default record is generated. You can set `pRequestState.EmptyEntityRecord` during this hook to provide a custom default object instead of the schema-generated one.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('New-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Provide a custom default record with pre-populated values
+		pRequestState.EmptyEntityRecord = {
+			IDBook: 0,
+			GUIDBook: '',
+			Title: '',
+			Author: '',
+			Status: 'Draft',
+			IDCustomer: pRequestState.SessionData.CustomerID,
+			CreatingIDUser: pRequestState.SessionData.UserID
+		};
+		return fCallback();
+	});
+```
+
+### New-PostOperation
+
+Runs after the default record is generated (or custom default is set). Use this to add computed defaults or session-specific values.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('New-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Set session-specific defaults
+		pRequestState.EmptyEntityRecord.IDCustomer =
+			pRequestState.SessionData.CustomerID;
+		pRequestState.EmptyEntityRecord.CreatingIDUser =
+			pRequestState.SessionData.UserID;
+
+		// Add a generated reference number
+		pRequestState.EmptyEntityRecord.ReferenceNumber =
+			`BK-${Date.now()}`;
+
+		return fCallback();
+	});
+```
+
+### Validate-PreOperation
+
+Runs before validation is performed. Use this to add custom validation logic or modify the record before schema validation.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Validate-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Normalize data before validation
+		if (pRequest.body && pRequest.body.Title)
+		{
+			pRequest.body.Title = pRequest.body.Title.trim();
+		}
+		return fCallback();
+	});
+```
+
+### Validate-PostOperation
+
+Runs after schema validation completes. The validation result is on `pRequestState.RecordValidation`. Use this to add custom validation rules beyond what the JSON Schema checks.
+
+```javascript
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Validate-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Add custom business rule validation
+		if (pRequestState.Record && !pRequestState.Record.Author)
+		{
+			// Augment validation result with custom error
+			if (!pRequestState.RecordValidation.errors)
+			{
+				pRequestState.RecordValidation.errors = [];
+			}
+			pRequestState.RecordValidation.errors.push({
+				field: 'Author',
+				message: 'Author is required for all books'
+			});
+		}
+
+		return fCallback();
+	});
+```
+
+## Complete Hook Example: Protected Schema with Custom Defaults
+
+This example shows all six schema hooks working together to provide a customized, secure schema experience:
+
+```javascript
+const tmpEndpoints = new libMeadowEndpoints(tmpBookMeadow);
+
+// Protect schema access
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Schema-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		if (!pRequestState.SessionData.LoggedIn)
+		{
+			return fCallback({ Code: 401, Message: 'Login required' });
+		}
+		return fCallback();
+	});
+
+// Clean up schema for API consumers
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Schema-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		// Hide internal tracking fields
+		let tmpHiddenFields = ['CreatingIDUser', 'UpdatingIDUser', 'Deleted'];
+		tmpHiddenFields.forEach((pField) =>
+		{
+			if (pRequestState.JSONSchema.properties)
+			{
+				delete pRequestState.JSONSchema.properties[pField];
+			}
+		});
+		return fCallback();
+	});
+
+// Provide smart defaults for new records
+tmpEndpoints.controller.BehaviorInjection.setBehavior('New-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		pRequestState.EmptyEntityRecord.IDCustomer =
+			pRequestState.SessionData.CustomerID;
+		pRequestState.EmptyEntityRecord.Status = 'Draft';
+		return fCallback();
+	});
+
+// Normalize before validation
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Validate-PreOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		if (pRequest.body && typeof(pRequest.body.Title) === 'string')
+		{
+			pRequest.body.Title = pRequest.body.Title.trim();
+		}
+		return fCallback();
+	});
+
+// Add business rules after schema validation
+tmpEndpoints.controller.BehaviorInjection.setBehavior('Validate-PostOperation',
+	(pRequest, pRequestState, fCallback) =>
+	{
+		if (pRequestState.Record)
+		{
+			if (!pRequestState.Record.Title || pRequestState.Record.Title.length < 1)
+			{
+				if (!pRequestState.RecordValidation.errors)
+				{
+					pRequestState.RecordValidation.errors = [];
+				}
+				pRequestState.RecordValidation.errors.push({
+					field: 'Title',
+					message: 'Title cannot be empty'
+				});
+			}
+		}
+		return fCallback();
+	});
+
+tmpEndpoints.connectRoutes(_Fable.Orator.serviceServer);
+```
+
+## Use Cases
+
+| Endpoint | Common Use Cases |
+|----------|-----------------|
+| **Schema** | Form generation, API documentation, client-side validation setup |
+| **New** | Pre-populating create forms with defaults, setting tenant-specific values |
+| **Validate** | Pre-submit validation, import data verification, API input checking |