retold-data-service 2.0.12 → 2.0.13

package/docs/api/onInitialize.md

@@ -0,0 +1,38 @@
+# onInitialize
+
+Lifecycle hook called after Orator starts and the persistence engine loads, but before data endpoints are created.
+
+## Signature
+
+`onInitialize(fCallback)`
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | Function | Callback `(pError)` to continue the initialization chain |
+
+## Default Behavior
+
+No-op -- calls `fCallback()` immediately.
+
+## Override
+
+```javascript
+class MyDataService extends require('retold-data-service')
+{
+	onInitialize(fCallback)
+	{
+		this.fable.log.info('Running database migrations...');
+		// The persistence engine is connected but endpoints don't exist yet
+		return fCallback();
+	}
+}
+```
+
+## Use Cases
+
+- Database migrations
+- Additional service registration
+- Custom route registration before entity routes
+- Schema transformations

package/docs/api/reference.md

@@ -0,0 +1,35 @@
+# API Reference
+
+Complete method reference for the `RetoldDataService` class.
+
+## Class: RetoldDataService
+
+Extends `fable-serviceproviderbase`. Registered as service type `'RetoldDataService'`.
+
+**Source:** `source/Retold-Data-Service.js`
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| [constructor](api/constructor.md) | Create a new RetoldDataService instance |
+| [initializeService](api/initializeService.md) | Initialize the full service stack |
+| [stopService](api/stopService.md) | Stop the Orator web server |
+| [initializePersistenceEngine](api/initializePersistenceEngine.md) | Load the storage provider module |
+| [initializeDataEndpoints](api/initializeDataEndpoints.md) | Load model and create DAL + endpoints |
+| [onBeforeInitialize](api/onBeforeInitialize.md) | Pre-initialization lifecycle hook |
+| [onInitialize](api/onInitialize.md) | Mid-initialization lifecycle hook |
+| [onAfterInitialize](api/onAfterInitialize.md) | Post-initialization lifecycle hook |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `serviceType` | String | Always `'RetoldDataService'` |
+| `serviceInitialized` | Boolean | Whether the service has been initialized |
+| `fullModel` | Object/Boolean | The loaded Stricture model, or `false` before init |
+| `entityList` | Array/Boolean | Array of entity names, or `false` before init |
+| `_DAL` | Object | Map of entity name to Meadow DAL instance |
+| `_MeadowEndpoints` | Object | Map of entity name to MeadowEndpoints controller |
+| `fable.DAL` | Object | Same as `_DAL` (decorated on Fable) |
+| `fable.MeadowEndpoints` | Object | Same as `_MeadowEndpoints` (decorated on Fable) |

package/docs/api/stopService.md

@@ -0,0 +1,34 @@
+# stopService
+
+Stop the Orator web server and reset the service state.
+
+## Signature
+
+`stopService(fCallback)`
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | Function | Callback `(pError)` when the service is stopped |
+
+## Behavior
+
+- Stops the Orator web server via `fable.Orator.stopWebServer()`
+- Sets `serviceInitialized = false`
+- Returns error if the service is not currently initialized
+
+## Example
+
+```javascript
+_Fable.RetoldDataService.stopService(
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('Stop failed:', pError);
+			return;
+		}
+		console.log('Service stopped');
+	});
+```

package/docs/architecture.md

@@ -8,7 +8,7 @@ Retold Data Service orchestrates several Retold modules into a unified service t
 ┌─────────────────────────────────────────────┐
 │            Your Application Code            │
 │   - Configure options                       │
-│   - Override lifecycle hooks                 │
+│   - Override lifecycle hooks                │
 │   - Inject behaviors                        │
 └──────────────────┬──────────────────────────┘
                    │
@@ -49,18 +49,66 @@ Retold Data Service orchestrates several Retold modules into a unified service t
 └─────────────────────────────────────────────┘
 ```
 
+## Initialization Flow
+
+The `initializeService()` method runs an ordered sequence of asynchronous steps using Fable's Anticipate pattern:
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant RDS as RetoldDataService
+    participant O as Orator
+    participant PE as PersistenceEngine
+    participant M as Meadow
+    participant ME as MeadowEndpoints
+
+    App->>RDS: initializeService()
+    RDS->>RDS: onBeforeInitialize()
+    RDS->>O: startWebServer()
+    RDS->>PE: initializePersistenceEngine()
+    RDS->>RDS: onInitialize()
+    RDS->>M: Load Stricture model
+    loop Each Entity
+        RDS->>M: loadFromPackageObject(schema)
+        M-->>RDS: DAL instance
+        RDS->>ME: new MeadowEndpoints(DAL)
+        ME->>O: connectRoutes()
+    end
+    RDS->>RDS: onAfterInitialize()
+    RDS-->>App: callback()
+```
+
+## Component Diagram
+
+```mermaid
+graph TD
+    A[Application Code] --> B[RetoldDataService]
+    B --> C[Orator + Restify]
+    B --> D[Meadow DAL]
+    B --> E[MeadowEndpoints]
+    D --> F[FoxHound Query DSL]
+    D --> G[Storage Provider]
+    G --> H[MySQL]
+    G --> I[SQLite]
+    G --> J[MSSQL]
+    G --> K[PostgreSQL]
+    G --> L[MongoDB]
+    E --> M[REST Routes]
+    E --> N[Behavior Injection]
+```
+
 ## How It Works
 
-1. **Registration** — `RetoldDataService` is registered with Fable's service manager and instantiated with options
-2. **Server Setup** — Orator and its Restify service server are registered and configured
-3. **Initialization** — calling `initializeService()` triggers an ordered sequence:
-   - `onBeforeInitialize()` — your custom pre-initialization logic
+1. **Registration** -- `RetoldDataService` is registered with Fable's service manager and instantiated with options
+2. **Server Setup** -- Orator and its Restify service server are registered and configured
+3. **Initialization** -- calling `initializeService()` triggers an ordered sequence:
+   - `onBeforeInitialize()` -- your custom pre-initialization logic
    - Orator web server start (if `AutoStartOrator` is true)
    - Persistence engine initialization (loads the storage provider module)
-   - `onInitialize()` — your custom initialization logic
+   - `onInitialize()` -- your custom initialization logic
    - Data endpoint initialization (loads model, creates DALs and endpoints)
-   - `onAfterInitialize()` — your custom post-initialization logic
-4. **Serving** — the Restify server listens for HTTP requests and routes them through Meadow Endpoints to the DAL
+   - `onAfterInitialize()` -- your custom post-initialization logic
+4. **Serving** -- the Restify server listens for HTTP requests and routes them through Meadow Endpoints to the DAL
 
 ## Key Objects
 
@@ -83,12 +131,28 @@ const libFableServiceProviderBase = require('fable-serviceproviderbase');
 
 class RetoldDataService extends libFableServiceProviderBase
 {
-    constructor(pFable, pOptions, pServiceHash)
-    {
-        super(pFable, pOptions, pServiceHash);
-        this.serviceType = 'RetoldDataService';
-    }
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'RetoldDataService';
+	}
 }
 ```
 
-This means it inherits logging, configuration access, and service lifecycle management from the base class.
+This means it inherits logging, configuration access, and service lifecycle management from the base class.  You register it with Fable's service manager like any other service:
+
+```javascript
+const libRetoldDataService = require('retold-data-service');
+
+_Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
+let _DataService = _Fable.serviceManager.instantiateServiceProvider('RetoldDataService',
+	{
+		FullMeadowSchemaPath: `${__dirname}/model/`,
+		FullMeadowSchemaFilename: 'MeadowModel-Extended.json',
+		StorageProvider: 'MySQL',
+		StorageProviderModule: 'meadow-connection-mysql',
+		AutoStartOrator: true
+	});
+```
+
+Once instantiated, the service is available at `_Fable.RetoldDataService` and can be initialized with `initializeService()`.

package/docs/behavior-injection.md

@@ -1,111 +1,154 @@
 # Behavior Injection
 
-Behavior injection lets you add custom logic before and after any CRUD operation on your endpoints.
+Behavior injection lets you add custom logic before or after any CRUD operation on any entity. This is the primary extension mechanism for adding business rules, validation, enrichment, and side effects.
 
 ## How It Works
 
-Each entity's Meadow Endpoints controller has a `BehaviorInjection` object that accepts pre- and post-operation hooks.  These hooks run inline with the request handling pipeline.
+Each MeadowEndpoints controller has a `BehaviorInjection` object that manages hooks for every CRUD operation. You set behaviors by specifying the operation and timing (pre or post).
+
+## Available Hooks
+
+| Hook | Fires |
+|------|-------|
+| `Create-PreOperation` | Before a record is created |
+| `Create-PostOperation` | After a record is created |
+| `Read-PreOperation` | Before a single record is read |
+| `Read-PostOperation` | After a single record is read |
+| `Reads-PreOperation` | Before multiple records are read |
+| `Reads-PostOperation` | After multiple records are read |
+| `Update-PreOperation` | Before a record is updated |
+| `Update-PostOperation` | After a record is updated |
+| `Delete-PreOperation` | Before a record is deleted |
+| `Delete-PostOperation` | After a record is deleted |
+| `Count-PreOperation` | Before a count query |
+| `Count-PostOperation` | After a count query |
 
 ## Setting a Behavior
 
 ```javascript
 _Fable.MeadowEndpoints.Book.controller.BehaviorInjection.setBehavior(
-    'Read-PreOperation',
-    (pRequest, pRequestState, fRequestComplete) =>
-    {
-        // Custom logic before the Read operation
-        console.log('About to read Book ID:', pRequest.params.IDRecord);
-        return fRequestComplete(false);
-    });
+	'Create-PreOperation',
+	(pRequest, pRequestState, fRequestComplete) =>
+	{
+		// Your custom logic here
+		return fRequestComplete(false);
+	});
 ```
 
-## Available Hook Points
-
-Each CRUD operation supports `PreOperation` and `PostOperation` hooks:
-
-| Hook Name | Fires |
-|-----------|-------|
-| `Create-PreOperation` | Before a CREATE |
-| `Create-PostOperation` | After a CREATE |
-| `Read-PreOperation` | Before a single READ |
-| `Read-PostOperation` | After a single READ |
-| `Reads-PreOperation` | Before a READ-many |
-| `Reads-PostOperation` | After a READ-many |
-| `Update-PreOperation` | Before an UPDATE |
-| `Update-PostOperation` | After an UPDATE |
-| `Delete-PreOperation` | Before a DELETE |
-| `Delete-PostOperation` | After a DELETE |
-| `Count-PreOperation` | Before a COUNT |
-| `Count-PostOperation` | After a COUNT |
-| `Schema-PreOperation` | Before a SCHEMA read |
-| `Schema-PostOperation` | After a SCHEMA read |
-
-## Request State
-
-The `pRequestState` object contains:
-
-| Property | Description |
-|----------|-------------|
-| `Record` | The current record being operated on |
-| `RecordToCreate` | The record being created (Create operations) |
-| `Query` | The FoxHound query object |
-| `SessionData` | Session data for the current request |
+## Callback Convention
+
+The `fRequestComplete` callback accepts a single boolean argument:
+- `false` -- Continue normal processing
+- `true` -- Halt processing (request is already handled)
 
 ## Examples
 
-### Enriching Read Results
+### Validation
 
 ```javascript
 _Fable.MeadowEndpoints.Book.controller.BehaviorInjection.setBehavior(
-    'Read-PostOperation',
-    (pRequest, pRequestState, fRequestComplete) =>
-    {
-        // Load related author data
-        let tmpQuery = _Fable.DAL.BookAuthorJoin.query
-            .addFilter('IDBook', pRequestState.Record.IDBook);
-
-        _Fable.DAL.BookAuthorJoin.doReads(tmpQuery,
-            (pError, pQuery, pJoinRecords) =>
-            {
-                pRequestState.Record.AuthorJoins = pJoinRecords;
-                return fRequestComplete(false);
-            });
-    });
+	'Create-PreOperation',
+	(pRequest, pRequestState, fRequestComplete) =>
+	{
+		if (!pRequestState.RecordToCreate.Title)
+		{
+			pRequest.CommonServices.sendCodedResponse(
+				pRequestState.response, 400, 'Title is required');
+			return fRequestComplete(true);
+		}
+		return fRequestComplete(false);
+	});
 ```
 
-### Validating Before Create
+### Record Enrichment
 
 ```javascript
 _Fable.MeadowEndpoints.Book.controller.BehaviorInjection.setBehavior(
-    'Create-PreOperation',
-    (pRequest, pRequestState, fRequestComplete) =>
-    {
-        if (!pRequestState.RecordToCreate.Title)
-        {
-            pRequest.CommonServices.sendCodedResponse(
-                pRequestState.response, 400, 'Title is required');
-            return fRequestComplete(true); // true signals an error
-        }
-        return fRequestComplete(false);
-    });
+	'Read-PostOperation',
+	(pRequest, pRequestState, fRequestComplete) =>
+	{
+		// Add computed fields to the response
+		pRequestState.Record.DisplayTitle =
+			`${pRequestState.Record.Title} (${pRequestState.Record.PublicationYear})`;
+		return fRequestComplete(false);
+	});
 ```
 
-### Adding Query Filters
+### Cross-Entity Enrichment
 
 ```javascript
 _Fable.MeadowEndpoints.Book.controller.BehaviorInjection.setBehavior(
-    'Reads-PreOperation',
-    (pRequest, pRequestState, fRequestComplete) =>
-    {
-        // Only return English-language books
-        pRequestState.Query.addFilter('Language', 'English');
-        return fRequestComplete(false);
-    });
+	'Read-PostOperation',
+	(pRequest, pRequestState, fRequestComplete) =>
+	{
+		_Fable.DAL.BookAuthorJoin.doReads(
+			_Fable.DAL.BookAuthorJoin.query.addFilter('IDBook', pRequestState.Record.IDBook),
+			(pJoinError, pJoinQuery, pJoinRecords) =>
+			{
+				let tmpAuthors = [];
+				let tmpRemaining = pJoinRecords.length;
+
+				if (tmpRemaining < 1)
+				{
+					pRequestState.Record.Authors = [];
+					return fRequestComplete(false);
+				}
+
+				for (let j = 0; j < pJoinRecords.length; j++)
+				{
+					_Fable.DAL.Author.doRead(
+						_Fable.DAL.Author.query.addFilter('IDAuthor', pJoinRecords[j].IDAuthor),
+						(pReadError, pReadQuery, pAuthor) =>
+						{
+							if (pAuthor && pAuthor.IDAuthor)
+							{
+								tmpAuthors.push(pAuthor);
+							}
+							tmpRemaining--;
+							if (tmpRemaining <= 0)
+							{
+								pRequestState.Record.Authors = tmpAuthors;
+								return fRequestComplete(false);
+							}
+						});
+				}
+			});
+	});
 ```
 
-## Removing a Behavior
+### Audit Logging
+
+```javascript
+_Fable.MeadowEndpoints.Book.controller.BehaviorInjection.setBehavior(
+	'Delete-PreOperation',
+	(pRequest, pRequestState, fRequestComplete) =>
+	{
+		_Fable.log.warn(`Book ${pRequestState.RecordToDelete.IDBook} is being deleted`);
+		return fRequestComplete(false);
+	});
+```
+
+## Timing
+
+- **PreOperation** hooks run before the database operation. Use them for validation, transformation, or authorization.
+- **PostOperation** hooks run after the database operation. Use them for enrichment, logging, or triggering side effects.
+
+## Using with Lifecycle Hooks
+
+The best place to inject behaviors is in the `onAfterInitialize` lifecycle hook:
 
 ```javascript
-delete _Fable.MeadowEndpoints.Book.controller
-    .BehaviorInjection._BehaviorFunctions['Read-PreOperation'];
+class MyDataService extends require('retold-data-service')
+{
+	onAfterInitialize(fCallback)
+	{
+		this.fable.MeadowEndpoints.Book.controller.BehaviorInjection.setBehavior(
+			'Read-PostOperation', myBookEnrichmentHook);
+
+		this.fable.MeadowEndpoints.Review.controller.BehaviorInjection.setBehavior(
+			'Create-PreOperation', myReviewValidationHook);
+
+		return fCallback();
+	}
+}
 ```

package/docs/css/docuserve.css

@@ -0,0 +1,73 @@
+/* ============================================================================
+   Pict Docuserve - Base Styles
+   ============================================================================ */
+
+/* Reset and base */
+*, *::before, *::after {
+	box-sizing: border-box;
+}
+
+html, body {
+	margin: 0;
+	padding: 0;
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+	font-size: 16px;
+	line-height: 1.5;
+	color: #423D37;
+	background-color: #fff;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+/* Typography */
+h1, h2, h3, h4, h5, h6 {
+	margin-top: 0;
+	line-height: 1.3;
+}
+
+a {
+	color: #2E7D74;
+	text-decoration: none;
+}
+
+a:hover {
+	color: #256861;
+}
+
+/* Application container */
+#Docuserve-Application-Container {
+	min-height: 100vh;
+}
+
+/* Utility: scrollbar styling */
+::-webkit-scrollbar {
+	width: 8px;
+}
+
+::-webkit-scrollbar-track {
+	background: #F5F0E8;
+}
+
+::-webkit-scrollbar-thumb {
+	background: #D4CCBE;
+	border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: #B5AA9A;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+	html {
+		font-size: 14px;
+	}
+
+	#Docuserve-Sidebar-Container {
+		display: none;
+	}
+
+	.docuserve-body {
+		flex-direction: column;
+	}
+}