fable-serviceproviderbase 3.0.16 → 3.0.18

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to Retold
+
+We welcome contributions to Retold and its modules. This guide covers the expectations and process for contributing.
+
+## Code of Conduct
+
+The Retold community values **empathy**, **equity**, **kindness**, and **thoughtfulness**. We expect all participants to treat each other with respect, assume good intent, and engage constructively. These values apply to all interactions: pull requests, issues, discussions, and code review.
+
+## How to Contribute
+
+### Pull Requests
+
+Pull requests are the preferred method for contributing changes. To submit one:
+
+1. Fork the module repository you want to change
+2. Create a branch for your work
+3. Make your changes, following the code style of the module you are editing
+4. Ensure your changes have test coverage (see below)
+5. Open a pull request against the module's main branch
+
+**Submitting a pull request does not guarantee it will be accepted.** Maintainers review contributions for fit, quality, and alignment with the project's direction. A PR may be declined, or you may be asked to revise it. This is normal and not a reflection on the quality of your effort.
+
+### Reporting Issues
+
+If you find a bug or have a feature suggestion, open an issue on the relevant module's repository. Include enough detail to reproduce the problem or understand the proposal.
+
+## Test Coverage
+
+Every commit must include test coverage for the changes it introduces. Retold modules use Mocha in TDD style. Before submitting:
+
+- **Write tests** for any new functionality or bug fixes
+- **Run the existing test suite** with `npm test` and confirm all tests pass
+- **Check coverage** with `npm run coverage` if the module supports it
+
+Pull requests that break existing tests or lack coverage for new code will not be merged.
+
+## Code Style
+
+Follow the conventions of the module you are working in. The general Retold style is:
+
+- **Tabs** for indentation, never spaces
+- **Plain JavaScript** only (no TypeScript)
+- **Allman-style braces** (opening brace on its own line)
+- **Variable naming:** `pVariable` for parameters, `tmpVariable` for temporaries, `libSomething` for imports
+
+When in doubt, match what the surrounding code does.
+
+## Repository Structure
+
+Each module is its own git repository. The [retold](https://github.com/stevenvelozo/retold) repository tracks module organization but does not contain module source code. Direct your pull request to the specific module repository where your change belongs.

package/README.md

@@ -1,71 +1,223 @@
-# Fable Service Provider
+# Fable Service Provider Base
 
-A very basic set of base classes to provide the interface for Fable services.
-This is used for instantiating connections to databases, extending core
-services and whatever other services.
+The base class for all services in the Fable ecosystem. Provides a standard interface for dependency injection, options handling, unique identification, and lifecycle management — used to build database connectors, API servers, template engines, view controllers, and any other service that plugs into a Fable application.
 
-Some service types Fable provides out of the box:
+[![Build Status](https://github.com/stevenvelozo/fable-serviceproviderbase/workflows/Fable-ServiceProviderBase/badge.svg)](https://github.com/stevenvelozo/fable-serviceproviderbase/actions)
+[![npm version](https://badge.fury.io/js/fable-serviceproviderbase.svg)](https://badge.fury.io/js/fable-serviceproviderbase)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-* settings
-* logging
-* uuid
-* templating
+---
 
+## Features
 
-## Basic Services
+- **Service Base Class** - Standard constructor accepting a Fable instance, options object, and service hash
+- **Dependency Injection** - Automatic access to `this.fable`, `this.log`, `this.services`, and `this.servicesMap` when connected to a Fable instance
+- **Unique Identification** - Every service instance receives a UUID from Fable (or a random fallback) and a configurable Hash for service map lookups
+- **Pre-Initialization Support** - Core services can be constructed before Fable is initialized and connected later via `connectFable()`
+- **Standalone Mode** - Services can be instantiated without a Fable instance at all, receiving options and a random UUID
+- **TypeScript Definitions** - Ships with `.d.ts` type declarations for editor support
 
-There are two types of services -- just requiring the class provides a base 
-class for most services.  The constructor for this type takes in a fully
-initialized fable object.
+## Installation
 
+```bash
+npm install fable-serviceproviderbase
 ```
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
 const libFableServiceProviderBase = require('fable-serviceproviderbase');
 
-class SimpleService extends libFableServiceProviderBase
+class GreeterService extends libFableServiceProviderBase
 {
-    constructor(pFable, pOptions, pServiceHash)
-    {
-        super(pFable, pOptions, pServiceHash);
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
 
-        this.serviceType = 'SimpleService';
-    }
+		this.serviceType = 'GreeterService';
+	}
 
-    doSomething()
-    {
-        this.fable.log.info(`SimpleService ${this.UUID}::${this.Hash} is doing something.`);
-    }
+	greet(pName)
+	{
+		this.log.info(`Hello, ${pName}! I am service ${this.Hash}.`);
+	}
 }
-```
 
-## Core Pre-initialization Services
+let fable = new libFable();
 
-For some service types, we want to instantiate behaviors before the fable
-class has been initialized.  These use a special service base that defers
-the connection of an initialized fable object until after it's created.
+fable.serviceManager.addServiceType('GreeterService', GreeterService);
+fable.serviceManager.instantiateServiceProvider('GreeterService',
+	{ greeting: 'Hello' }, 'PrimaryGreeter');
 
-The one caveat here is the fable service doesn't provide consistent settings,
-log or uuid functionality until they have been initialized and mapped in.
+fable.services.GreeterService.greet('World');
+```
 
-If you want to use this base class, please refer to the fable service 
-manager code as well to get a good understanding of how initialization 
-differs from the basic services.
+## Usage
 
+### Basic Services
 
-```
+Most services extend the base class directly and receive a fully initialized Fable instance:
+
+```javascript
 const libFableServiceProviderBase = require('fable-serviceproviderbase');
 
 class SimpleService extends libFableServiceProviderBase
 {
-    constructor(pFable, pOptions, pServiceHash)
-    {
-        super(pFable, pOptions, pServiceHash);
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
 
-        this.serviceType = 'SimpleService';
-    }
+		this.serviceType = 'SimpleService';
+	}
 
-    doSomething()
-    {
-        this.fable.log.info(`SimpleService ${this.UUID}::${this.Hash} is doing something.`);
-    }
+	doSomething()
+	{
+		this.fable.log.info(`SimpleService ${this.UUID}::${this.Hash} is doing something.`);
+	}
 }
 ```
+
+Register and use through the Fable service manager:
+
+```javascript
+let fable = new libFable();
+
+fable.serviceManager.addServiceType('SimpleService', SimpleService);
+fable.serviceManager.instantiateServiceProvider('SimpleService',
+	{ SomeOption: true }, 'SimpleService-123');
+
+// Access via the services map
+fable.services.SimpleService.doSomething();
+
+// Or look up a specific instance by hash
+fable.servicesMap.SimpleService['SimpleService-123'].doSomething();
+```
+
+### Core Pre-Initialization Services
+
+Some services need to exist before Fable is fully initialized (e.g., logging, settings, UUID generation). These use the `CoreServiceProviderBase` export and connect to Fable later:
+
+```javascript
+const libCoreServiceBase = require('fable-serviceproviderbase').CoreServiceProviderBase;
+
+class EarlyService extends libCoreServiceBase
+{
+	constructor(pOptions, pServiceHash)
+	{
+		super(pOptions, pServiceHash);
+
+		this.serviceType = 'EarlyService';
+	}
+
+	earlyWork()
+	{
+		console.log(`EarlyService ${this.UUID}::${this.Hash} is working.`);
+	}
+}
+
+// Create before Fable exists
+let earlyService = new EarlyService({ SomeOption: true }, 'EarlyService-1');
+earlyService.earlyWork();
+
+// Later, connect to Fable
+let fable = new libFable();
+fable.serviceManager.connectPreinitServiceProviderInstance(earlyService);
+
+// Now it has full fable access
+earlyService.fable.log.info('Connected to Fable!');
+```
+
+### Standalone Mode
+
+Services can be instantiated without any Fable instance. They receive a random UUID and the first parameter is treated as the options object:
+
+```javascript
+let standalone = new SimpleService({ Setting: 'Something' });
+// standalone.options.Setting === 'Something'
+// standalone.UUID is a random string like 'CORE-SVC-12345'
+// standalone.fable === false
+```
+
+## API
+
+### Constructor
+
+```javascript
+new FableServiceProviderBase(pFable, pOptions, pServiceHash)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFable` | `Fable \| Object` | A Fable instance, or an options object if no Fable is available |
+| `pOptions` | `Object \| String` | Options object, or service hash string if no Fable is available |
+| `pServiceHash` | `String` | Identifier for this service instance in the services map |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `connectFable(pFable)` | Attach a Fable instance after construction. Sets `this.fable`, `this.log`, `this.services`, and `this.servicesMap`. Returns `true` on success or an `Error` on failure. |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `fable` | `Fable \| false` | The connected Fable instance, or `false` if standalone |
+| `UUID` | `String` | Unique identifier assigned by Fable or generated randomly |
+| `Hash` | `String` | Service hash for lookups in the services map (defaults to UUID) |
+| `serviceType` | `String` | Service type identifier (set by the deriving class) |
+| `options` | `Object` | Options object passed at construction |
+| `log` | `Object` | Reference to `fable.Logging` (available after Fable connection) |
+| `services` | `Object` | Reference to `fable.services` (available after Fable connection) |
+| `servicesMap` | `Object` | Reference to `fable.servicesMap` (available after Fable connection) |
+
+### Static Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isFableService` | `Boolean` | Always `true` — used to identify Fable service classes |
+
+### Exports
+
+| Export | Description |
+|--------|-------------|
+| `require('fable-serviceproviderbase')` | The `FableServiceProviderBase` class |
+| `require('fable-serviceproviderbase').CoreServiceProviderBase` | Same class (alias for pre-init service pattern) |
+
+## Part of the Retold Framework
+
+Fable Service Provider Base is the foundation class for all services in the ecosystem:
+
+- [fable](https://github.com/stevenvelozo/fable) - Application services framework and service manager
+- [fable-log](https://github.com/stevenvelozo/fable-log) - Logging framework (core service)
+- [fable-uuid](https://github.com/stevenvelozo/fable-uuid) - UUID generation (core service)
+- [meadow](https://github.com/stevenvelozo/meadow) - ORM built as Fable services
+- [orator](https://github.com/stevenvelozo/orator) - API server built as Fable services
+- [pict](https://github.com/stevenvelozo/pict) - MVC framework built as Fable services
+
+## Testing
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Run with coverage:
+
+```bash
+npm run coverage
+```
+
+## Related Packages
+
+- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+
+## 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

@@ -0,0 +1,111 @@
+# Fable Service Provider Base
+
+The base class that every Retold service extends. It provides the contract for registration, dependency injection, and lifecycle management within a Fable instance.
+
+## What It Does
+
+When you extend `FableServiceProviderBase`, your class gains:
+
+- `this.fable` -- Reference to the Fable instance (or `false` if standalone)
+- `this.log` -- Shortcut to Fable's logging service
+- `this.services` -- Access to all registered services
+- `this.servicesMap` -- The full service registry map
+- `this.options` -- Service-specific configuration
+- `this.serviceType` -- The registered type name (set this in your constructor)
+- `this.Hash` -- Unique identifier for this specific instance
+- `this.UUID` -- Auto-generated unique ID
+
+## Quick Start
+
+```javascript
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+class MyService extends libFableServiceProviderBase
+{
+    constructor(pFable, pOptions, pServiceHash)
+    {
+        super(pFable, pOptions, pServiceHash);
+        this.serviceType = 'MyService';
+    }
+
+    doSomething()
+    {
+        this.log.info('MyService is doing something');
+        return this.fable.getUUID();
+    }
+}
+```
+
+Register with a Fable instance:
+
+```javascript
+const libFable = require('fable');
+let _Fable = new libFable();
+
+// Register the type and create an instance
+_Fable.serviceManager.addServiceType('MyService', MyService);
+_Fable.serviceManager.instantiateServiceProvider('MyService', { SomeOption: true }, 'MyService-1');
+
+// Access via the services shortcut
+_Fable.services.MyService.doSomething();
+```
+
+Or use the shorthand:
+
+```javascript
+_Fable.addAndInstantiateServiceType('MyService', MyService);
+_Fable.services.MyService.doSomething();
+```
+
+## Three Initialization Patterns
+
+The constructor is flexible and supports three modes. See [Initialization Patterns](initialization-patterns.md) for details.
+
+**With Fable** -- The standard pattern for application services:
+
+```javascript
+let tmpService = new MyService(fableInstance, optionsObject, serviceHash);
+```
+
+**Pre-initialization** -- For core services needed before Fable is ready:
+
+```javascript
+let tmpCore = new MyCoreService(optionsObject, serviceHash);
+// Later, after Fable is ready:
+fableInstance.serviceManager.connectPreinitServiceProviderInstance(tmpCore);
+```
+
+**Standalone** -- For testing or non-Fable contexts:
+
+```javascript
+let tmpService = new MyService({ Setting: 'value' });
+// tmpService.fable === false
+```
+
+## Multiple Instances
+
+You can create multiple instances of the same service type, each with a different hash:
+
+```javascript
+_Fable.serviceManager.instantiateServiceProvider('DatabaseService', { Host: 'primary-db' }, 'Primary');
+_Fable.serviceManager.instantiateServiceProvider('DatabaseService', { Host: 'replica-db' }, 'Replica');
+
+// Access the default (first registered)
+_Fable.services.DatabaseService.connect();
+
+// Access a specific instance
+_Fable.servicesMap.DatabaseService['Replica'].connect();
+
+// Change the default
+_Fable.serviceManager.setDefaultServiceInstantiation('DatabaseService', 'Replica');
+```
+
+## API Reference
+
+See the [API Reference](api.md) for complete method and property documentation.
+
+## Learn More
+
+- [Initialization Patterns](initialization-patterns.md) -- The three ways to construct a service
+- [API Reference](api.md) -- Properties, methods, and static members
+- [Fable Service Provider Pattern](/fable/fable/) -- How services compose in the Fable ecosystem

package/docs/_sidebar.md

@@ -0,0 +1,15 @@
+- Getting Started
+
+  - [Overview](README.md)
+  - [Initialization Patterns](initialization-patterns.md)
+
+- Reference
+
+  - [API Reference](api.md)
+
+- Retold Ecosystem
+
+  - [Fable](/fable/fable/)
+  - [Fable-Settings](/fable/fable-settings/)
+  - [Fable-Log](/fable/fable-log/)
+  - [Fable-UUID](/fable/fable-uuid/)

package/docs/_topbar.md

@@ -0,0 +1,5 @@
+# Fable Service Provider Base
+
+- [Overview](README.md)
+- [API Reference](api.md)
+- [GitHub](https://github.com/stevenvelozo/fable-serviceproviderbase)

package/docs/api.md

@@ -0,0 +1,132 @@
+# API Reference
+
+## Class: FableServiceProviderBase
+
+The base class for all Fable services. Import it and extend it to create your own services.
+
+```javascript
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+class MyService extends libFableServiceProviderBase
+{
+    constructor(pFable, pOptions, pServiceHash)
+    {
+        super(pFable, pOptions, pServiceHash);
+        this.serviceType = 'MyService';
+    }
+}
+```
+
+## Constructor
+
+```javascript
+new FableServiceProviderBase(pFable, pOptions, pServiceHash)
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pFable` | Fable instance or object | No | A Fable instance, or an options object if no Fable is available |
+| `pOptions` | object or string | No | Options for the service, or the service hash if no Fable |
+| `pServiceHash` | string | No | Unique identifier for this service instance |
+
+See [Initialization Patterns](initialization-patterns.md) for detailed usage of each parameter combination.
+
+## Instance Properties
+
+### fable
+
+- **Type:** Fable instance or `false`
+- **Description:** Reference to the connected Fable instance. Set to `false` when no Fable is connected.
+
+### log
+
+- **Type:** object or `undefined`
+- **Description:** Shortcut to `fable.Logging`. Provides `trace()`, `debug()`, `info()`, `warn()`, `error()`, and `fatal()` methods.
+
+### UUID
+
+- **Type:** string
+- **Description:** Unique identifier for this service instance. Generated by Fable's UUID service when connected, or a random `CORE-SVC-XXXXX` string when standalone.
+
+### Hash
+
+- **Type:** string
+- **Description:** The service instance hash, used to look up this specific instance in the service registry. Defaults to the UUID if not provided.
+
+### serviceType
+
+- **Type:** string
+- **Description:** The registered type name for this service. Defaults to `'Unknown-{UUID}'`. Subclasses should set this in their constructor.
+
+### options
+
+- **Type:** object
+- **Description:** Service-specific configuration passed during construction.
+
+### services
+
+- **Type:** object or `undefined`
+- **Description:** Reference to `fable.services`. Provides shortcut access to the default instance of each registered service type.
+
+### servicesMap
+
+- **Type:** object or `undefined`
+- **Description:** Reference to `fable.servicesMap`. A two-level map: `servicesMap[serviceType][hash]` returns a specific service instance.
+
+### _PackageFableServiceProvider
+
+- **Type:** object
+- **Description:** The `package.json` contents of fable-serviceproviderbase. Useful for version checking.
+
+## Instance Methods
+
+### connectFable(pFable)
+
+Connects a Fable instance to this service. Used for core services that were constructed before Fable was initialized.
+
+```javascript
+let tmpResult = myService.connectFable(fableInstance);
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pFable` | Fable instance | Yes | Must have `isFable` property set to `true` |
+
+**Returns:** `true` on success, or an `Error` if the parameter is not a valid Fable instance.
+
+**Behavior:**
+- Sets `this.fable` if not already set
+- Sets `this.log` to `fable.Logging` if not already set
+- Sets `this.services` to `fable.services` if not already set
+- Sets `this.servicesMap` to `fable.servicesMap` if not already set
+- Idempotent: calling multiple times will not overwrite existing references
+
+## Static Properties
+
+### isFableService
+
+- **Type:** boolean
+- **Value:** `true`
+- **Description:** Class-level flag that identifies a class as a Fable service. Used by the service manager to validate service types.
+
+## Exports
+
+### Default Export
+
+The `FableServiceProviderBase` class itself.
+
+```javascript
+const libBase = require('fable-serviceproviderbase');
+class MyService extends libBase { ... }
+```
+
+### CoreServiceProviderBase
+
+An alias for `FableServiceProviderBase`. They are the same class.
+
+```javascript
+const libBase = require('fable-serviceproviderbase');
+class MyCoreService extends libBase.CoreServiceProviderBase { ... }
+```
+
+The alias exists for readability when building services that are designed to be constructed before Fable is initialized.

package/docs/cover.md

@@ -0,0 +1,14 @@
+# Fable Service Provider Base
+
+> The foundation class for every Retold service
+
+A lightweight base class that provides registration, dependency injection, and lifecycle management. Every service in the Fable ecosystem -- from logging to data access to views -- extends this class.
+
+- **Dependency Injection** -- Access logging, configuration, and other services through `this.fable`
+- **Service Registry** -- Register by type, instantiate with unique hashes, discover via `this.services`
+- **Flexible Initialization** -- Construct with Fable, before Fable, or without Fable at all
+- **Multiple Instances** -- Run several instances of the same service type with different configurations
+
+[Get Started](README.md)
+[API Reference](api.md)
+[GitHub](https://github.com/stevenvelozo/fable-serviceproviderbase)

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;
+	}
+}

package/docs/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="Documentation powered by pict-docuserve">
+
+		<title>Documentation</title>
+
+		<!-- Application Stylesheet -->
+		<link href="css/docuserve.css" rel="stylesheet">
+		<!-- KaTeX stylesheet for LaTeX equation rendering -->
+		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+//<![CDATA[
+		Pict.safeOnDocumentReady(() => { Pict.safeLoadPictApplication(PictDocuserve, 2)});
+//]]>
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Mermaid diagram rendering -->
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({ startOnLoad: false, theme: 'default' });</script>
+		<!-- KaTeX for LaTeX equation rendering -->
+		<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
+		<!-- Load the Docuserve PICT Application Bundle from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>

package/docs/initialization-patterns.md

@@ -0,0 +1,123 @@
+# Initialization Patterns
+
+The `FableServiceProviderBase` constructor supports three initialization modes. The same base class handles all three -- it detects whether a Fable instance was passed in and adjusts behavior accordingly.
+
+## Pattern 1: With Fable
+
+The standard pattern for application services. Pass a Fable instance as the first argument.
+
+```javascript
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+class MyService extends libFableServiceProviderBase
+{
+    constructor(pFable, pOptions, pServiceHash)
+    {
+        super(pFable, pOptions, pServiceHash);
+        this.serviceType = 'MyService';
+    }
+}
+
+const libFable = require('fable');
+let _Fable = new libFable();
+
+let tmpService = new MyService(_Fable, { ConnectionTimeout: 5000 }, 'Primary');
+```
+
+After construction:
+
+| Property | Value |
+|----------|-------|
+| `this.fable` | The Fable instance |
+| `this.log` | `fable.Logging` |
+| `this.services` | `fable.services` |
+| `this.servicesMap` | `fable.servicesMap` |
+| `this.UUID` | Generated by Fable's UUID service |
+| `this.options` | `{ ConnectionTimeout: 5000 }` |
+| `this.Hash` | `'Primary'` |
+
+## Pattern 2: Pre-initialization (Core Services)
+
+Some services need to exist before Fable is fully initialized -- for example, logging or settings services that Fable itself depends on. These are constructed without a Fable instance and connected later.
+
+```javascript
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+class MyCoreService extends libFableServiceProviderBase.CoreServiceProviderBase
+{
+    constructor(pOptions, pServiceHash)
+    {
+        super(pOptions, pServiceHash);
+        this.serviceType = 'MyCoreService';
+    }
+
+    earlyBehavior()
+    {
+        // This works even before Fable is initialized
+        console.log(`Core service ${this.Hash} is ready`);
+    }
+}
+
+// Create the service early
+let tmpCore = new MyCoreService({ SomeOption: true }, 'CoreInstance-1');
+tmpCore.earlyBehavior();
+
+// Later, when Fable is ready, connect it
+let _Fable = new libFable();
+_Fable.serviceManager.connectPreinitServiceProviderInstance(tmpCore);
+
+// Now tmpCore.fable, tmpCore.log, tmpCore.services are all available
+```
+
+After construction (before `connectFable`):
+
+| Property | Value |
+|----------|-------|
+| `this.fable` | `false` |
+| `this.log` | `undefined` |
+| `this.services` | `undefined` |
+| `this.UUID` | `'CORE-SVC-XXXXX'` (random 5-digit number) |
+| `this.options` | `{ SomeOption: true }` |
+| `this.Hash` | `'CoreInstance-1'` |
+
+After `connectFable` or `connectPreinitServiceProviderInstance`:
+
+| Property | Value |
+|----------|-------|
+| `this.fable` | The Fable instance |
+| `this.log` | `fable.Logging` |
+| `this.services` | `fable.services` |
+
+Note: `CoreServiceProviderBase` is an alias for `FableServiceProviderBase`. They are the same class. The alias exists for readability -- it signals that the service is designed for pre-initialization use.
+
+## Pattern 3: Standalone (No Fable)
+
+For testing or non-Fable contexts, services can be constructed with just an options object:
+
+```javascript
+let tmpService = new MyService({ Setting: 'value' });
+```
+
+After construction:
+
+| Property | Value |
+|----------|-------|
+| `this.fable` | `false` |
+| `this.log` | `undefined` |
+| `this.UUID` | `'CORE-SVC-XXXXX'` (random) |
+| `this.options` | `{ Setting: 'value' }` |
+| `this.Hash` | Same as UUID |
+
+The service works but has no access to Fable's logging, configuration, or other services. You can call `connectFable(fableInstance)` later to wire everything up.
+
+## Constructor Parameter Detection
+
+The constructor uses a simple heuristic: if the first parameter is an object with an `isFable` property set to `true`, it treats it as a Fable instance. Otherwise, the first parameter is treated as the options object.
+
+```
+new Service(fable, options, hash)   →  fable.isFable is true  →  Pattern 1
+new Service(options, hash)          →  options.isFable is falsy →  Pattern 2/3
+new Service()                       →  no arguments             →  Pattern 3
+```
+
+The `pServiceHash` parameter sets `this.Hash`. If omitted, the hash defaults to the UUID. When no Fable is present, if the second parameter is a string, it is used as the hash.

package/docs/retold-catalog.json

@@ -0,0 +1,41 @@
+{
+	"Generated": "2026-02-18T03:21:49.210Z",
+	"GitHubOrg": "stevenvelozo",
+	"DefaultBranch": "master",
+	"Groups": [
+		{
+			"Name": "Dist",
+			"Key": "dist",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "indoctrinate_content_staging",
+					"Repo": "indoctrinate_content_staging",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		},
+		{
+			"Name": "Types",
+			"Key": "types",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "source",
+					"Repo": "source",
+					"Group": "types",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		}
+	]
+}

package/docs/retold-keyword-index.json

@@ -0,0 +1,19 @@
+{
+	"Generated": "2026-02-18T03:21:49.288Z",
+	"DocumentCount": 0,
+	"LunrIndex": {
+		"version": "2.3.9",
+		"fields": [
+			"title",
+			"module",
+			"group",
+			"body"
+		],
+		"fieldVectors": [],
+		"invertedIndex": [],
+		"pipeline": [
+			"stemmer"
+		]
+	},
+	"Documents": {}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fable-serviceproviderbase",
-    "version": "3.0.16",
+    "version": "3.0.18",
     "description": "Simple base classes for fable services.",
     "main": "source/Fable-ServiceProviderBase.js",
     "scripts": {
@@ -47,8 +47,8 @@
     "homepage": "https://github.com/stevenvelozo/fable-serviceproviderbase",
     "devDependencies": {
         "@types/mocha": "^10.0.10",
-        "fable": "^3.1.51",
-        "quackage": "^1.0.45",
+        "fable": "^3.1.55",
+        "quackage": "^1.0.51",
         "typescript": "^5.9.3"
     }
 }