retold-data-service 2.0.12 → 2.0.13

package/README.md

@@ -1,19 +1,28 @@
 # Retold Data Service
 
-> An all-in-one Fable service that turns a Stricture schema into a complete REST API
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> An all-in-one Fable service that turns a compiled Stricture schema into a complete REST API
 
 Retold Data Service combines Meadow (data access), Orator (API server), and Meadow Endpoints (REST routes) into a single service provider. Point it at a compiled Stricture model and it auto-generates typed CRUD endpoints for every entity -- complete with filtering, pagination, soft deletes, and behavior injection hooks.
 
 ## Features
 
-- **Zero-Boilerplate REST** - Define your schema once, get full CRUD endpoints for every entity automatically
-- **Provider-Agnostic** - Swap between MySQL, MSSQL, SQLite, or ALASQL without changing application code
-- **Schema-Driven** - Stricture DDL compiles into a model that drives endpoint generation, validation, and defaults
-- **Lifecycle Hooks** - `onBeforeInitialize`, `onInitialize`, and `onAfterInitialize` for custom startup logic
-- **Behavior Injection** - Pre- and post-operation hooks on every CRUD operation for custom business logic
-- **DAL Access** - Direct programmatic data access alongside the REST endpoints for server-side logic
-- **Fable Service Provider** - First-class service in the Fable ecosystem with logging, configuration, and DI
-- **Double-Init Protection** - Guards against accidental re-initialization
+- **Zero-Boilerplate REST** -- define your schema once, get full CRUD endpoints for every entity automatically
+- **Provider-Agnostic** -- swap between MySQL, MSSQL, PostgreSQL, SQLite, MongoDB, DGraph, Solr, or ALASQL without changing application code
+- **Schema-Driven** -- Stricture DDL compiles into a model that drives endpoint generation, validation, and defaults
+- **Lifecycle Hooks** -- `onBeforeInitialize`, `onInitialize`, and `onAfterInitialize` for custom startup logic
+- **Behavior Injection** -- pre- and post-operation hooks on every CRUD operation for custom business logic
+- **DAL Access** -- direct programmatic data access alongside the REST endpoints for server-side logic
+- **Backplane Endpoints** -- dynamic model loading, provider switching, and settings management at runtime
+- **Fable Service Provider** -- first-class service in the Fable ecosystem with logging, configuration, and DI
+- **Double-Init Protection** -- guards against accidental re-initialization
+
+## Installation
+
+```bash
+npm install retold-data-service
+```
 
 ## Quick Start
 
@@ -21,27 +30,30 @@ Retold Data Service combines Meadow (data access), Orator (API server), and Mead
 const libFable = require('fable');
 const libRetoldDataService = require('retold-data-service');
 
-const _Fable = new libFable({
-	APIServerPort: 8086,
-	MySQL: {
-		Server: '127.0.0.1',
-		Port: 3306,
-		User: 'root',
-		Password: 'secret',
-		Database: 'bookstore',
-		ConnectionPoolLimit: 20
-	},
-	MeadowConnectionMySQLAutoConnect: true
-});
+const _Fable = new libFable(
+	{
+		APIServerPort: 8086,
+		MySQL:
+		{
+			Server: '127.0.0.1',
+			Port: 3306,
+			User: 'root',
+			Password: 'secret',
+			Database: 'bookstore',
+			ConnectionPoolLimit: 20
+		},
+		MeadowConnectionMySQLAutoConnect: true
+	});
 
 _Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
 
-_Fable.serviceManager.instantiateServiceProvider('RetoldDataService', {
-	StorageProvider: 'MySQL',
-	StorageProviderModule: 'meadow-connection-mysql',
-	FullMeadowSchemaPath: `${__dirname}/model/`,
-	FullMeadowSchemaFilename: 'MeadowModel-Extended.json'
-});
+_Fable.serviceManager.instantiateServiceProvider('RetoldDataService',
+	{
+		StorageProvider: 'MySQL',
+		StorageProviderModule: 'meadow-connection-mysql',
+		FullMeadowSchemaPath: `${__dirname}/model/`,
+		FullMeadowSchemaFilename: 'MeadowModel-Extended.json'
+	});
 
 _Fable.RetoldDataService.initializeService(
 	(pError) =>
@@ -54,13 +66,7 @@ _Fable.RetoldDataService.initializeService(
 	});
 ```
 
-## Installation
-
-```bash
-npm install retold-data-service
-```
-
-## How It Works
+## Architecture
 
 Retold Data Service orchestrates the full Meadow stack into a single initialization sequence:
 
@@ -72,7 +78,7 @@ Fable (Core)
         ├── Meadow (Data Access Layer)
         │     ├── Schema (from compiled Stricture model)
         │     ├── FoxHound (Query DSL)
-        │     └── Provider (MySQL / MSSQL / SQLite / ALASQL)
+        │     └── Provider (MySQL / MSSQL / PostgreSQL / SQLite / MongoDB / etc.)
         └── Meadow Endpoints (REST Routes)
               ├── Create   POST   /1.0/Entity
               ├── Read     GET    /1.0/Entity/:ID
@@ -93,19 +99,22 @@ Fable (Core)
 | `FullMeadowSchemaPath` | `process.cwd() + '/model/'` | Path to the compiled schema |
 | `FullMeadowSchemaFilename` | `'MeadowModel-Extended.json'` | Compiled model filename |
 | `AutoStartOrator` | `true` | Start the HTTP server automatically |
-| `APIServerPort` | `8080` | Port for the HTTP server |
+| `AutoInitializeDataService` | `true` | Auto-initialize on construction |
 
 ## SQLite Example
 
 For embedded or test scenarios, use the in-memory SQLite provider:
 
 ```javascript
+const libFable = require('fable');
+const libRetoldDataService = require('retold-data-service');
 const libMeadowConnectionSQLite = require('meadow-connection-sqlite');
 
-const _Fable = new libFable({
-	APIServerPort: 8086,
-	SQLite: { SQLiteFilePath: ':memory:' }
-});
+const _Fable = new libFable(
+	{
+		APIServerPort: 8086,
+		SQLite: { SQLiteFilePath: ':memory:' }
+	});
 
 _Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
 _Fable.serviceManager.addServiceType('MeadowSQLiteProvider', libMeadowConnectionSQLite);
@@ -114,12 +123,13 @@ _Fable.serviceManager.instantiateServiceProvider('MeadowSQLiteProvider');
 _Fable.MeadowSQLiteProvider.connectAsync(
 	(pError) =>
 	{
-		_Fable.serviceManager.instantiateServiceProvider('RetoldDataService', {
-			StorageProvider: 'SQLite',
-			StorageProviderModule: 'meadow-connection-sqlite',
-			FullMeadowSchemaPath: `${__dirname}/model/`,
-			FullMeadowSchemaFilename: 'MeadowModel-Extended.json'
-		});
+		_Fable.serviceManager.instantiateServiceProvider('RetoldDataService',
+			{
+				StorageProvider: 'SQLite',
+				StorageProviderModule: 'meadow-connection-sqlite',
+				FullMeadowSchemaPath: `${__dirname}/model/`,
+				FullMeadowSchemaFilename: 'MeadowModel-Extended.json'
+			});
 
 		_Fable.RetoldDataService.initializeService(
 			(pError) =>
@@ -185,7 +195,7 @@ _Fable.DAL.Book.doReads(tmpQuery,
 
 ## Backplane Endpoints
 
-For dynamic model loading at runtime, Retold Data Service provides backplane endpoints:
+For dynamic model loading and provider management at runtime:
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
@@ -216,15 +226,14 @@ npx docsify-cli serve docs
 
 ## Related Packages
 
-- [meadow](https://github.com/stevenvelozo/meadow) - Data access and ORM
-- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) - Auto-generated REST endpoints
-- [orator](https://github.com/stevenvelozo/orator) - API server abstraction
-- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+- [meadow](https://github.com/stevenvelozo/meadow) -- data access and ORM
+- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) -- auto-generated REST endpoints
+- [foxhound](https://github.com/stevenvelozo/foxhound) -- query DSL for SQL generation
+- [stricture](https://github.com/stevenvelozo/stricture) -- schema definition DDL compiler
+- [orator](https://github.com/stevenvelozo/orator) -- API server abstraction
+- [fable](https://github.com/stevenvelozo/fable) -- application services framework
+- [retold-harness](https://github.com/stevenvelozo/retold-harness) -- application harness using this service
 
 ## License
 
 MIT
-
-## Contributing
-
-Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).

package/docs/README.md

@@ -1,76 +1,34 @@
 # Retold Data Service
 
-Retold Data Service is an all-in-one module that combines Fable, Meadow, Orator, and Meadow Endpoints into a single service.  Given a compiled Stricture schema, it automatically creates a data access layer (DAL) and RESTful API endpoints for every entity in your model.
+An all-in-one Fable service that turns a compiled Stricture schema into a complete REST API. Combines Meadow (data access), Orator (API server), and Meadow Endpoints (REST routes) into a single service provider with lifecycle hooks and behavior injection.
 
-## Features
-
-- **Schema-Driven** — load a compiled Stricture model and get full CRUD endpoints for every table automatically
-- **Pluggable Storage** — configure any Meadow-compatible provider (MySQL, SQLite, MSSQL, ALASQL) via options
-- **Fable Service** — extends `fable-serviceproviderbase`, integrating with the Fable ecosystem for logging, configuration, and service management
-- **Lifecycle Hooks** — override `onBeforeInitialize`, `onInitialize`, and `onAfterInitialize` for custom startup logic
-- **Behavior Injection** — add pre- and post-operation hooks to any CRUD endpoint
-- **DAL Access** — query your data directly through `fable.DAL.<Entity>` for programmatic access alongside the REST API
-- **Auto-Start** — optionally start the Orator web server automatically on initialization
-
-## Quick Start
-
-```javascript
-const libFable = require('fable');
-const libRetoldDataService = require('retold-data-service');
-
-const _Fable = new libFable({
-    Product: 'MyApp',
-    APIServerPort: 8086,
-    MySQL: {
-        Server: '127.0.0.1',
-        Port: 3306,
-        User: 'root',
-        Password: 'secret',
-        Database: 'mydb',
-        ConnectionPoolLimit: 20
-    },
-    MeadowConnectionMySQLAutoConnect: true
-});
+## What It Does
 
-_Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
-_Fable.serviceManager.instantiateServiceProvider('RetoldDataService', {
-    FullMeadowSchemaPath: `${__dirname}/model/`,
-    FullMeadowSchemaFilename: 'MeadowModel-Extended.json',
-    StorageProvider: 'MySQL',
-    StorageProviderModule: 'meadow-connection-mysql',
-    AutoStartOrator: true
-});
+Retold Data Service orchestrates several Retold modules into a unified service:
 
-_Fable.RetoldDataService.initializeService(
-    (pError) =>
-    {
-        if (pError) return console.error('Startup failed:', pError);
-        console.log('Data service running on port 8086');
-    });
-```
+- **[Meadow](https://github.com/stevenvelozo/meadow)** provides the data access layer and ORM
+- **[Meadow Endpoints](https://github.com/stevenvelozo/meadow-endpoints)** generates REST routes for every entity
+- **[Orator](https://github.com/stevenvelozo/orator)** serves the HTTP API via Restify
+- **[FoxHound](https://github.com/stevenvelozo/foxhound)** builds SQL queries from a declarative DSL
+- **[Stricture](https://github.com/stevenvelozo/stricture)** compiles schema definitions into the model
 
-## Installation
+## Features
 
-```bash
-npm install retold-data-service
-```
+- **Zero-Boilerplate REST** -- Define your schema once, get full CRUD endpoints for every entity automatically
+- **Provider-Agnostic** -- Swap between MySQL, MSSQL, PostgreSQL, SQLite, MongoDB, DGraph, Solr, or ALASQL
+- **Schema-Driven** -- Stricture DDL compiles into a model that drives endpoint generation, validation, and defaults
+- **Lifecycle Hooks** -- `onBeforeInitialize`, `onInitialize`, and `onAfterInitialize` for custom startup logic
+- **Behavior Injection** -- Pre- and post-operation hooks on every CRUD operation
+- **DAL Access** -- Direct programmatic data access alongside the REST endpoints
+- **Backplane Endpoints** -- Dynamic model loading and provider switching at runtime
+- **Fable Service Provider** -- First-class service with logging, configuration, and DI
 
 ## Related Packages
 
-| Package | Purpose |
-|---------|---------|
-| [fable](https://github.com/stevenvelozo/fable) | Core service framework |
-| [meadow](https://github.com/stevenvelozo/meadow) | Data access layer and ORM |
-| [foxhound](https://github.com/stevenvelozo/foxhound) | Query DSL for SQL generation |
-| [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) | REST endpoint generation |
-| [orator](https://github.com/stevenvelozo/orator) | API server abstraction |
-| [stricture](https://github.com/stevenvelozo/stricture) | Schema definition DDL compiler |
-| [retold-harness](https://github.com/stevenvelozo/retold-harness) | Application harness using Retold Data Service |
-
-## Testing
-
-```bash
-npm test
-```
-
-Tests run against an in-memory SQLite database and require no external services.
+- [meadow](https://github.com/stevenvelozo/meadow) -- Data access layer and ORM
+- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) -- REST endpoint generation
+- [foxhound](https://github.com/stevenvelozo/foxhound) -- Query DSL for SQL generation
+- [stricture](https://github.com/stevenvelozo/stricture) -- Schema definition DDL compiler
+- [orator](https://github.com/stevenvelozo/orator) -- API server abstraction
+- [fable](https://github.com/stevenvelozo/fable) -- Application services framework
+- [retold-harness](https://github.com/stevenvelozo/retold-harness) -- Application harness using this service

package/docs/_cover.md

@@ -1,11 +1,11 @@
-# Retold Data Service <small>2</small>
+# Retold Data Service <small>v2.0.11</small>
 
-> All-in-one data service for the Retold ecosystem
+> Schema-driven REST API generation for the Retold ecosystem
 
-- Schema-driven REST API generation from Stricture DDL models
-- Automatic CRUD endpoints for every entity in your data model
-- Pluggable storage providers: MySQL, SQLite, MSSQL, ALASQL
-- Built on Fable, Meadow, and Orator with lifecycle hooks for customization
+- Zero-boilerplate CRUD endpoints from Stricture DDL models
+- Pluggable storage providers across SQL and NoSQL engines
+- Lifecycle hooks and behavior injection for custom logic
+- Direct DAL access for server-side data operations
 
+[Getting Started](#retold-data-service)
 [GitHub](https://github.com/stevenvelozo/retold-data-service)
-[Get Started](#retold-data-service)

package/docs/_sidebar.md

@@ -1,13 +1,26 @@
 - Getting Started
-  - [Introduction](/)
-  - [Architecture](architecture.md)
-  - [Configuration](configuration.md)
+	- [Overview](/)
+	- [Quick Start](quick-start.md)
+	- [Configuration](configuration.md)
+
+- Architecture
+	- [System Design](architecture.md)
+	- [Initialization](initialization.md)
+	- [Schema Definition](schema-definition.md)
+
 - Usage
-  - [Initialization](initialization.md)
-  - [Endpoints](endpoints.md)
-  - [DAL Access](dal-access.md)
-  - [Behavior Injection](behavior-injection.md)
-- Advanced
-  - [Lifecycle Hooks](lifecycle-hooks.md)
-  - [Storage Providers](storage-providers.md)
-  - [Schema Definition](schema-definition.md)
+	- [REST Endpoints](endpoints.md)
+	- [DAL Access](dal-access.md)
+	- [Behavior Injection](behavior-injection.md)
+	- [Lifecycle Hooks](lifecycle-hooks.md)
+
+- API Reference
+	- [Overview](api/reference.md)
+	- [constructor](api/constructor.md)
+	- [initializeService](api/initializeService.md)
+	- [stopService](api/stopService.md)
+	- [initializePersistenceEngine](api/initializePersistenceEngine.md)
+	- [initializeDataEndpoints](api/initializeDataEndpoints.md)
+	- [onBeforeInitialize](api/onBeforeInitialize.md)
+	- [onInitialize](api/onInitialize.md)
+	- [onAfterInitialize](api/onAfterInitialize.md)

package/docs/_topbar.md

@@ -0,0 +1,2 @@
+- [GitHub](https://github.com/stevenvelozo/retold-data-service)
+- [npm](https://www.npmjs.com/package/retold-data-service)

package/docs/api/constructor.md

@@ -0,0 +1,67 @@
+# constructor
+
+Create a new RetoldDataService instance with merged default and custom options.
+
+## Signature
+
+`constructor(pFable, pOptions, pServiceHash)`
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFable` | Fable | The Fable application instance |
+| `pOptions` | Object | Service configuration options |
+| `pServiceHash` | String | Optional service hash identifier |
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `StorageProvider` | String | `'MySQL'` | Meadow provider name |
+| `StorageProviderModule` | String | `'meadow-connection-mysql'` | npm module for the provider |
+| `FullMeadowSchemaPath` | String | `process.cwd() + '/model/'` | Path to compiled schema |
+| `FullMeadowSchemaFilename` | String | `'MeadowModel-Extended.json'` | Schema filename |
+| `AutoInitializeDataService` | Boolean | `true` | Auto-initialize on construction |
+| `AutoStartOrator` | Boolean | `true` | Start Orator web server during init |
+
+## What Happens
+
+1. Merges default options with provided `pOptions`
+2. Registers `OratorServiceServer` (Restify) as a Fable service
+3. Registers `Orator` as a Fable service
+4. Creates an internal Meadow instance
+5. Creates empty `_DAL` and `_MeadowEndpoints` maps
+6. Decorates `fable.DAL` and `fable.MeadowEndpoints` with these maps
+7. Sets `serviceInitialized = false`
+
+## Example
+
+```javascript
+const libFable = require('fable');
+const libRetoldDataService = require('retold-data-service');
+
+const _Fable = new libFable(
+	{
+		APIServerPort: 8086,
+		MySQL:
+		{
+			Server: '127.0.0.1',
+			Port: 3306,
+			User: 'root',
+			Password: 'secret',
+			Database: 'bookstore',
+			ConnectionPoolLimit: 20
+		},
+		MeadowConnectionMySQLAutoConnect: true
+	});
+
+_Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
+_Fable.serviceManager.instantiateServiceProvider('RetoldDataService',
+	{
+		StorageProvider: 'MySQL',
+		StorageProviderModule: 'meadow-connection-mysql',
+		FullMeadowSchemaPath: `${__dirname}/model/`,
+		FullMeadowSchemaFilename: 'MeadowModel-Extended.json'
+	});
+```

package/docs/api/initializeDataEndpoints.md

@@ -0,0 +1,54 @@
+# initializeDataEndpoints
+
+Core initialization step that loads the compiled Stricture model and creates a Meadow DAL and MeadowEndpoints controller for every entity.
+
+## Signature
+
+`initializeDataEndpoints(fCallback)`
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | Function | Callback `(pError)` when all endpoints are created |
+
+## Behavior
+
+1. Loads the compiled Stricture schema from `options.FullMeadowSchemaPath` + `options.FullMeadowSchemaFilename`
+2. Extracts the entity list from `fullModel.Tables`
+3. For each entity:
+   - Creates a Meadow DAL from the table's `MeadowSchema` property via `loadFromPackageObject()`
+   - Sets the DAL's storage provider to `options.StorageProvider`
+   - Creates a MeadowEndpoints controller wrapping the DAL
+   - Connects routes to the Orator service server via `connectRoutes()`
+4. Stores all DALs in `this._DAL` (also accessible via `fable.DAL`)
+5. Stores all endpoint controllers in `this._MeadowEndpoints` (also accessible via `fable.MeadowEndpoints`)
+
+## After Initialization
+
+```javascript
+// Access DAL for any entity
+let tmpBookDAL = _Fable.DAL.Book;
+
+// Access endpoints controller for any entity
+let tmpBookEndpoints = _Fable.MeadowEndpoints.Book;
+
+// List all entities
+console.log(_Fable.RetoldDataService.entityList);
+// ['Book', 'Author', 'BookAuthorJoin', ...]
+```
+
+## Generated Endpoints Per Entity
+
+For each entity (e.g. `Book`), these routes are connected:
+
+| Method | URL | Operation |
+|--------|-----|-----------|
+| GET | `/1.0/Book/:ID` | Read single record |
+| GET | `/1.0/Books/:Begin/:Cap` | Read multiple records |
+| POST | `/1.0/Book` | Create record |
+| PUT | `/1.0/Book` | Update record |
+| DELETE | `/1.0/Book/:ID` | Soft-delete record |
+| GET | `/1.0/Books/Count` | Count records |
+| GET | `/1.0/Book/Schema` | Get entity schema |
+| GET | `/1.0/Book/Schema/New` | Get default record |

package/docs/api/initializePersistenceEngine.md

@@ -0,0 +1,34 @@
+# initializePersistenceEngine
+
+Dynamically loads and instantiates the configured storage provider module.
+
+## Signature
+
+`initializePersistenceEngine(fCallback)`
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | Function | Callback `(pError)` when the provider is loaded |
+
+## Behavior
+
+Calls `fable.serviceManager.addAndInstantiateServiceType()` with:
+- Service name: `Meadow{StorageProvider}Provider` (e.g. `MeadowMySQLProvider`)
+- Module: `require(this.options.StorageProviderModule)`
+
+This is called automatically during `initializeService()`. You typically do not call this directly.
+
+## Supported Providers
+
+| StorageProvider | StorageProviderModule | Fable Service Name |
+|----------------|----------------------|-------------------|
+| `MySQL` | `meadow-connection-mysql` | `MeadowMySQLProvider` |
+| `SQLite` | `meadow-connection-sqlite` | `MeadowSQLiteProvider` |
+| `MSSQL` | `meadow-connection-mssql` | `MeadowMSSQLProvider` |
+| `PostgreSQL` | `meadow-connection-postgresql` | `MeadowPostgreSQLProvider` |
+| `MongoDB` | `meadow-connection-mongodb` | `MeadowMongoDBProvider` |
+| `DGraph` | `meadow-connection-dgraph` | `MeadowDGraphProvider` |
+| `Solr` | `meadow-connection-solr` | `MeadowSolrProvider` |
+| `ALASQL` | `meadow-connection-alasql` | `MeadowALASQLProvider` |

package/docs/api/initializeService.md

@@ -0,0 +1,44 @@
+# initializeService
+
+Main entry point for initializing the full service stack. Chains all lifecycle steps via Fable's Anticipate pattern.
+
+## Signature
+
+`initializeService(fCallback)`
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | Function | Callback `(pError)` when initialization completes |
+
+## Initialization Sequence
+
+1. Check for double-initialization (returns error if already initialized)
+2. `onBeforeInitialize()` -- custom pre-init hook
+3. Start Orator web server (if `AutoStartOrator` is `true`)
+4. `initializePersistenceEngine()` -- load storage provider
+5. `onInitialize()` -- custom mid-init hook
+6. `initializeDataEndpoints()` -- load model, create DALs and endpoints
+7. `onAfterInitialize()` -- custom post-init hook
+8. Set `serviceInitialized = true`
+
+## Error Handling
+
+- If already initialized, calls back with `Error("...already been initialized...")`
+- If any step in the chain fails, the error propagates to `fCallback`
+
+## Example
+
+```javascript
+_Fable.RetoldDataService.initializeService(
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('Initialization failed:', pError);
+			return process.exit(1);
+		}
+		console.log('REST API running on port', _Fable.settings.APIServerPort);
+	});
+```

package/docs/api/onAfterInitialize.md

@@ -0,0 +1,48 @@
+# onAfterInitialize
+
+Lifecycle hook called after all data endpoints are created and routes are connected.
+
+## Signature
+
+`onAfterInitialize(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')
+{
+	onAfterInitialize(fCallback)
+	{
+		this.fable.log.info('Injecting custom behaviors...');
+
+		this.fable.MeadowEndpoints.Book.controller.BehaviorInjection.setBehavior(
+			'Read-PostOperation',
+			(pRequest, pRequestState, fRequestComplete) =>
+			{
+				// Enrich book records with author data
+				pRequestState.Record.CustomField = 'injected';
+				return fRequestComplete(false);
+			});
+
+		return fCallback();
+	}
+}
+```
+
+## Use Cases
+
+- Behavior injection on entity endpoints
+- Cache warming
+- Background task scheduling
+- Custom endpoint registration after entity routes
+- Seed data verification

package/docs/api/onBeforeInitialize.md

@@ -0,0 +1,45 @@
+# onBeforeInitialize
+
+Lifecycle hook called before Orator starts and before the persistence engine loads.
+
+## Signature
+
+`onBeforeInitialize(fCallback)`
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | Function | Callback `(pError)` to continue the initialization chain |
+
+## Default Behavior
+
+No-op -- calls `fCallback()` immediately.
+
+## Override
+
+Subclass `RetoldDataService` to add custom pre-initialization logic:
+
+```javascript
+class MyDataService extends require('retold-data-service')
+{
+	onBeforeInitialize(fCallback)
+	{
+		this.fable.log.info('Validating environment...');
+
+		if (!process.env.DATABASE_URL)
+		{
+			return fCallback(new Error('DATABASE_URL is required'));
+		}
+
+		return fCallback();
+	}
+}
+```
+
+## Use Cases
+
+- Environment validation
+- Early configuration overrides
+- External service health checks
+- Feature flag loading