retold 1.0.6 → 4.0.1

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: #333;
+	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: #42b983;
+	text-decoration: none;
+}
+
+a:hover {
+	color: #38a373;
+}
+
+/* Application container */
+#Docuserve-Application-Container {
+	min-height: 100vh;
+}
+
+/* Utility: scrollbar styling */
+::-webkit-scrollbar {
+	width: 8px;
+}
+
+::-webkit-scrollbar-track {
+	background: #f1f1f1;
+}
+
+::-webkit-scrollbar-thumb {
+	background: #bdc3c7;
+	border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: #95a5a6;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+	html {
+		font-size: 14px;
+	}
+
+	#Docuserve-Sidebar-Container {
+		display: none;
+	}
+
+	.docuserve-body {
+		flex-direction: column;
+	}
+}

package/docs/fable.md

@@ -0,0 +1,198 @@
+# Fable — Core Ecosystem
+
+Fable is the foundation of every Retold application. It provides dependency injection, configuration management, logging, UUID generation, and a collection of utility services. Every other Retold module depends on Fable.
+
+## What Fable Provides
+
+When you create a Fable instance, you get:
+
+- **Service provider registry** — Register, discover, and inject services by type
+- **Configuration** — Merge settings from files, defaults, and runtime overrides
+- **Logging** — Six log levels with extensible output streams
+- **UUID generation** — RFC 4122 v4 UUIDs or configurable random strings
+- **Expression parser** — Evaluate mathematical and logical expressions with 80+ built-in functions
+- **REST client** — Make HTTP requests from Node.js or the browser
+- **Template engine** — Render templates with data binding
+- **Date utilities** — Date parsing and formatting
+- **Data format helpers** — Clean numbers, pad strings, format values
+
+## Core Service Modules
+
+### [Fable](/fable/fable/)
+
+The main module. Creates the service container and bundles all core services.
+
+```javascript
+const libFable = require('fable');
+
+let _Fable = new libFable({
+    Product: 'MyApp',
+    ProductVersion: '1.0.0',
+    LogLevel: 3
+});
+
+// All services are immediately available
+_Fable.log.info('Started');
+_Fable.log.trace(`UUID: ${_Fable.getUUID()}`);
+```
+
+**npm:** `fable` · **Version:** 3.1.x
+
+---
+
+### [Fable-ServiceProviderBase](/fable/fable-serviceproviderbase/)
+
+The base class that all Retold services extend. Provides the registration and dependency injection mechanics.
+
+Every service gets:
+- `this.fable` — Reference to the Fable instance
+- `this.log` — Shortcut to logging
+- `this.options` — Service-specific options
+- `this.serviceType` — The registered service type name
+- `this.Hash` — Unique identifier for this service instance
+
+```javascript
+const libServiceProviderBase = require('fable-serviceproviderbase');
+
+class MyService extends libServiceProviderBase
+{
+    constructor(pFable, pOptions, pServiceHash)
+    {
+        super(pFable, pOptions, pServiceHash);
+        this.serviceType = 'MyService';
+    }
+
+    doSomething()
+    {
+        this.log.info('MyService is doing something');
+        let tmpUUID = this.fable.getUUID();
+        return tmpUUID;
+    }
+}
+
+// Register with Fable
+_Fable.addAndInstantiateServiceType('MyService', MyService);
+```
+
+**npm:** `fable-serviceproviderbase` · **Version:** 3.0.x
+
+---
+
+### [Fable-Settings](/fable/fable-settings/)
+
+A tolerant configuration chain. Loads settings from files, merges with defaults, and allows runtime overrides.
+
+```javascript
+// Settings merge in order: defaults → file → constructor → runtime
+let _Fable = new libFable({
+    Product: 'MyApp',
+    MySQL: {
+        Server: 'localhost',
+        User: 'root',
+        Database: 'mydb'
+    }
+});
+
+// Access settings
+let tmpServer = _Fable.settings.MySQL.Server;
+
+// Override at runtime
+_Fable.settings.MySQL.Server = 'production-host';
+```
+
+**npm:** `fable-settings` · **Version:** 3.0.x
+
+---
+
+### [Fable-Log](/fable/fable-log/)
+
+Flexible logging with six levels and extensible output streams.
+
+| Level | Method | Use |
+|-------|--------|-----|
+| 0 | `log.trace()` | Granular debugging |
+| 1 | `log.debug()` | Development debugging |
+| 2 | `log.info()` | Normal operation |
+| 3 | `log.warn()` | Potential issues |
+| 4 | `log.error()` | Errors |
+| 5 | `log.fatal()` | Critical failures |
+
+Set `LogLevel` in configuration to control which messages appear. Messages at the configured level and above are shown.
+
+```javascript
+let _Fable = new libFable({ LogLevel: 2 }); // info and above
+
+_Fable.log.trace('Not shown');
+_Fable.log.info('Shown');
+_Fable.log.error('Shown');
+```
+
+**npm:** `fable-log` · **Version:** 3.0.x
+
+---
+
+### [Fable-UUID](/fable/fable-uuid/)
+
+UUID generation for identity and uniqueness.
+
+```javascript
+// RFC 4122 v4 UUID
+let tmpUUID = _Fable.getUUID();
+// → '83853f9c-732c-4225-9a20-abcde47c6ddb'
+
+// Random string (configurable length and character set)
+let tmpRandom = _Fable.fable.UUID.getUUID({ length: 12 });
+```
+
+**npm:** `fable-uuid` · **Version:** 3.0.x
+
+---
+
+### [Fable-Log-Logger-Bunyan](/fable/fable-log-logger-bunyan/)
+
+A structured logging provider that routes Fable-Log output to Bunyan for production environments with JSON-formatted, machine-parseable log streams.
+
+**npm:** `fable-log-logger-bunyan` · **Version:** 1.0.x
+
+## The Service Provider Pattern
+
+Fable's core design pattern: modules register as services and discover each other through the Fable instance.
+
+```mermaid
+graph LR
+  reg["Register Service"] --> fable
+
+  subgraph fable["Fable Instance"]
+    direction TB
+    core[".settings  .log  .getUUID()"]
+    subgraph registry["Service Registry"]
+      meadow["Meadow"]
+      orator["Orator"]
+      custom["MyCustomService"]
+    end
+  end
+
+  fable --> a1["_Fable.Meadow"]
+  fable --> a2["_Fable.Orator"]
+  fable --> a3["_Fable.MyCustomService"]
+
+  style fable fill:#fce4ec,stroke:#ef5350,color:#333
+  style registry fill:#fff,stroke:#ef9a9a,color:#333
+  style core fill:#fce4ec,stroke:none,color:#333
+  style a1 fill:#fff3e0,stroke:#ffa726,color:#333
+  style a2 fill:#e3f2fd,stroke:#42a5f5,color:#333
+  style a3 fill:#e8f5e9,stroke:#66bb6a,color:#333
+```
+
+Services can be registered by type (`addServiceType`) or instantiated on registration (`addAndInstantiateServiceType`). Multiple instances of the same type can coexist with different hashes.
+
+## Related Modules
+
+| Module | Description |
+|--------|-------------|
+| [fable](/fable/fable/) | Core module with all services |
+| [fable-serviceproviderbase](/fable/fable-serviceproviderbase/) | Base class for all services |
+| [fable-settings](/fable/fable-settings/) | Configuration management |
+| [fable-log](/fable/fable-log/) | Logging library |
+| [fable-uuid](/fable/fable-uuid/) | UUID generation |
+| [fable-log-logger-bunyan](/fable/fable-log-logger-bunyan/) | Bunyan log provider |

package/docs/getting-started.md

@@ -0,0 +1,272 @@
+# Getting Started
+
+This guide walks through building a Retold application step by step, adding one layer at a time. See the [Architecture](architecture.md) page for a full description of the layer model.
+
+> **Working examples:** Each step below has a corresponding runnable example in
+> [`examples/quickstart/`](../examples/quickstart/). Clone the repo and follow
+> along with real code.
+
+## Step 1: Fable — The Foundation
+
+> **Layer 1 — Fable (Core Ecosystem):** DI, configuration, logging, UUID, expressions
+>
+> Working example: [`examples/quickstart/layer1/`](../examples/quickstart/layer1/)
+
+Every Retold application starts with a Fable instance. Fable gives you dependency injection, configuration, and logging.
+
+```bash
+npm install fable
+```
+
+```javascript
+const libFable = require('fable');
+
+let _Fable = new libFable({
+    Product: 'BookStore',
+    ProductVersion: '1.0.0',
+    LogLevel: 2   // info and above
+});
+
+_Fable.log.info('BookStore starting up...');
+_Fable.log.trace(`Instance UUID: ${_Fable.getUUID()}`);
+```
+
+Configuration can come from the constructor, a `.fable.config.json` file, or a combination:
+
+```json
+{
+    "Product": "BookStore",
+    "LogLevel": 2,
+    "MySQL": {
+        "Server": "localhost",
+        "User": "root",
+        "Password": "",
+        "Database": "bookstore",
+        "ConnectionPoolLimit": 20
+    }
+}
+```
+
+## Step 2: Meadow — Define Your Data
+
+> **Layer 2 — Meadow + FoxHound + Stricture:** Data broker, SQL generation, schema definitions
+>
+> Working example: [`examples/quickstart/layer2/`](../examples/quickstart/layer2/)
+
+Add Meadow to define data entities and connect to a database.
+
+```bash
+npm install meadow foxhound stricture meadow-connection-mysql
+```
+
+Define a schema for your entity. Stricture's MicroDDL is the simplest approach, but you can also write JSON directly:
+
+```json
+{
+    "title": "Book",
+    "description": "A book in the bookstore",
+    "defaultIdentifier": "IDBook",
+    "defaultGUIDIdentifier": "GUIDBook",
+    "columns": [
+        { "Column": "IDBook", "Type": "AutoIdentity" },
+        { "Column": "GUIDBook", "Type": "AutoGUID" },
+        { "Column": "Title", "Size": 200, "Type": "String" },
+        { "Column": "Author", "Size": 200, "Type": "String" },
+        { "Column": "YearPublished", "Type": "Integer" },
+        { "Column": "CreateDate", "Type": "DateTime" },
+        { "Column": "CreatingIDUser", "Type": "Integer" },
+        { "Column": "UpdateDate", "Type": "DateTime" },
+        { "Column": "UpdatingIDUser", "Type": "Integer" },
+        { "Column": "Deleted", "Type": "Boolean" },
+        { "Column": "DeleteDate", "Type": "DateTime" },
+        { "Column": "DeletingIDUser", "Type": "Integer" }
+    ]
+}
+```
+
+Create the Meadow entity:
+
+```javascript
+const libMeadow = require('meadow');
+const BookSchema = require('./Book-Schema.json');
+
+let _BookMeadow = _Fable.instantiateServiceProvider('Meadow',
+{
+    Scope: 'Book',
+    DefaultSchema: BookSchema
+});
+
+// Perform data operations
+_BookMeadow.doCreate({ Title: 'The Hobbit', Author: 'Tolkien', YearPublished: 1937 },
+    function(pError, pQuery, pRecord)
+    {
+        _Fable.log.info(`Created book with ID ${pRecord.IDBook}`);
+    });
+```
+
+## Step 3: Meadow-Endpoints — Auto-Generate Your API
+
+> **Layer 3 — Meadow-Endpoints:** Auto-generated CRUD routes, behavior hooks
+
+Add Meadow-Endpoints to automatically create RESTful routes from your entity.
+
+```bash
+npm install meadow-endpoints
+```
+
+```javascript
+const libMeadowEndpoints = require('meadow-endpoints');
+
+let _BookEndpoints = _Fable.instantiateServiceProvider('MeadowEndpoints',
+{
+    Entity: _BookMeadow
+});
+
+// Add authentication behavior
+_BookEndpoints.BehaviorModifications.setBehavior('Create-Authorize',
+    function(pRequest, fCallback)
+    {
+        // Only authenticated users can create books
+        if (!pRequest.UserSession || !pRequest.UserSession.LoggedIn)
+        {
+            pRequest.CommonServices.log.warn('Unauthorized create attempt');
+            return fCallback('Unauthorized');
+        }
+        return fCallback();
+    });
+```
+
+This generates endpoints for: `GET /Books`, `GET /Book/:id`, `POST /Book`, `PUT /Book`, `DEL /Book/:id`, `GET /Books/Count`, `GET /Book/Schema`, and `DEL /Book/:id/Undelete`.
+
+## Step 4: Orator — Serve Your API
+
+> **Layer 4 — Orator (API Server):** HTTP lifecycle, middleware, static files, proxy
+>
+> Working example: [`examples/quickstart/layer3/`](../examples/quickstart/layer3/)
+
+Add Orator to host everything over HTTP.
+
+```bash
+npm install orator orator-serviceserver-restify
+```
+
+```javascript
+const libOrator = require('orator');
+require('orator-serviceserver-restify');
+
+let _Orator = _Fable.instantiateServiceProvider('Orator');
+
+// Wire the auto-generated endpoints to the HTTP server
+_BookEndpoints.connectRoutes(_Orator);
+
+// Add a custom health check route
+_Orator.addRoute('GET', '/health', function(pRequest, pResponse, fNext)
+{
+    pResponse.send({ status: 'ok', product: _Fable.settings.Product });
+    return fNext();
+});
+
+// Start the server
+_Orator.startService(function(pError)
+{
+    if (pError)
+    {
+        _Fable.log.error(`Failed to start: ${pError}`);
+        return;
+    }
+    _Fable.log.info(`${_Fable.settings.Product} running on port ${_Fable.settings.APIServerPort}`);
+});
+```
+
+Your API is now running. Test it:
+
+```bash
+# Create a book
+curl -X POST http://localhost:8086/Book \
+  -H "Content-Type: application/json" \
+  -d '{"Title": "The Hobbit", "Author": "Tolkien", "YearPublished": 1937}'
+
+# List all books
+curl http://localhost:8086/Books
+
+# Get a specific book
+curl http://localhost:8086/Book/1
+
+# Get the count
+curl http://localhost:8086/Books/Count
+```
+
+## Step 5: Pict — Add a Browser UI (Optional)
+
+> **Pict (MVC Tools):** Views, templates, providers, application lifecycle — sits alongside the server stack
+>
+> Working example: [`examples/quickstart/layer4/`](../examples/quickstart/layer4/)
+
+If your application has a browser interface, add Pict for MVC.
+
+```bash
+npm install pict pict-view pict-application
+```
+
+```javascript
+const libPict = require('pict');
+
+let _Pict = new libPict({
+    Product: 'BookStoreUI'
+});
+
+// Register templates
+_Pict.TemplateProvider.addTemplate('BookList',
+    '<ul>{~Each:AppData.Books:BookItem~}</ul>');
+_Pict.TemplateProvider.addTemplate('BookItem',
+    '<li>{~Data:Record.Title~} by {~Data:Record.Author~} ({~Data:Record.YearPublished~})</li>');
+
+// Load data from your API
+fetch('/Books')
+    .then(r => r.json())
+    .then(books =>
+    {
+        _Pict.AppData.Books = books;
+        // Render into the page
+        document.getElementById('book-list').innerHTML =
+            _Pict.parseTemplate('BookList', {});
+    });
+```
+
+## The Shortcut: Retold-Data-Service
+
+For the common case of "schema → full REST API", **retold-data-service** wraps Layers 2–3 (Meadow + Meadow-Endpoints) into a single call:
+
+```bash
+npm install retold-data-service
+```
+
+```javascript
+const libRetoldDataService = require('retold-data-service');
+
+let _BookService = _Fable.instantiateServiceProvider('RetoldDataService',
+{
+    Scope: 'Book',
+    Schema: BookSchema
+});
+
+// Full CRUD endpoints ready — wire to Orator and go
+_BookService.connectRoutes(_Orator);
+```
+
+## Utility Modules
+
+> **Utility Layer:** Build tools, manifest management, documentation, process supervision
+>
+> Working example: [`examples/quickstart/layer5/`](../examples/quickstart/layer5/) (Manyfest)
+
+Supporting the application stack are utility modules like **Manyfest** (schema-driven object navigation), **Quackage** (browser bundling), **Indoctrinate** (documentation generation), and **Ultravisor** (process supervision). These are used throughout the stack but don't live in the numbered layer model.
+
+## Next Steps
+
+- **[Architecture](architecture.md)** — Understand the layer model in depth
+- **[Fable](fable.md)** — Deep dive into the core ecosystem and service provider pattern
+- **[Meadow](meadow.md)** — Data access, FoxHound queries, and Stricture schemas
+- **[Orator](orator.md)** — Server configuration, lifecycle hooks, and middleware
+- **[Pict](pict.md)** — Views, templates, providers, and application lifecycle
+- **[All Modules](modules.md)** — Every repository in the Retold suite

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 -->
+		<script src="./js/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 -->
+		<script src="./pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>