fable 3.1.72 → 3.1.74

package/docs/services/settings-manager.md

@@ -5,10 +5,13 @@ The Settings Manager provides centralized configuration management for Fable app
 ## Access
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'SettingsDemo', ProductVersion: '1.0.0' });
+
 // Pre-initialized, available directly
-fable.SettingsManager
-fable.settings  // Shorthand for SettingsManager.settings
-fable.settingsManager  // Alias
+console.log('fable.SettingsManager:', typeof fable.SettingsManager);
+console.log('fable.settings:',        typeof fable.settings,        '(shorthand for SettingsManager.settings)');
+console.log('fable.settingsManager:', typeof fable.settingsManager, '(alias)');
 ```
 
 ## Basic Usage
@@ -16,12 +19,21 @@ fable.settingsManager  // Alias
 ### Reading Settings
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({
+    Product: 'MyApplication',
+    ProductVersion: '1.0.0',
+    Database: { Host: 'localhost' }
+});
+
 // Access settings directly
 const productName = fable.settings.Product;
-const version = fable.settings.ProductVersion;
+const version     = fable.settings.ProductVersion;
 
 // Access nested settings
 const dbHost = fable.settings.Database.Host;
+
+console.log('productName:', productName, 'version:', version, 'dbHost:', dbHost);
 ```
 
 ### Providing Configuration
@@ -29,7 +41,9 @@ const dbHost = fable.settings.Database.Host;
 Pass settings when creating a Fable instance:
 
 ```javascript
-const fable = new Fable({
+const libFable = require('fable');
+
+const fable = new libFable({
     Product: 'MyApplication',
     ProductVersion: '1.0.0',
 
@@ -44,6 +58,9 @@ const fable = new Fable({
         Timeout: 30000
     }
 });
+
+console.log('Database.Host:', fable.settings.Database.Host);
+console.log('API.BaseURL:',   fable.settings.API.BaseURL);
 ```
 
 ## Default Settings
@@ -51,7 +68,7 @@ const fable = new Fable({
 Fable provides sensible defaults that your configuration extends:
 
 ```javascript
-{
+const defaultSettingsShape = {
     Product: 'Fable',
     ProductVersion: '0.0.0',
 
@@ -63,7 +80,8 @@ Fable provides sensible defaults that your configuration extends:
     LogStreams: [
         { level: 'info' }
     ]
-}
+};
+console.log('defaultSettingsShape:', defaultSettingsShape);
 ```
 
 Your settings are merged with these defaults using [precedent](https://github.com/stevenvelozo/precedent).
@@ -73,24 +91,41 @@ Your settings are merged with these defaults using [precedent](https://github.co
 ### Using Environment Variables
 
 ```javascript
-const fable = new Fable({
+const libFable = require('fable');
+
+const env = (typeof process !== 'undefined' && process.env) ? process.env : {};
+
+const fable = new libFable({
     Product: 'MyApp',
 
     Database: {
-        Host: process.env.DB_HOST || 'localhost',
-        Port: parseInt(process.env.DB_PORT) || 5432,
-        Password: process.env.DB_PASSWORD
+        Host:     env.DB_HOST || 'localhost',
+        Port:     parseInt(env.DB_PORT) || 5432,
+        Password: env.DB_PASSWORD
     }
 });
+
+console.log('Database.Host:', fable.settings.Database.Host);
+console.log('Database.Port:', fable.settings.Database.Port);
 ```
 
 ### Environment-Specific Config Files
 
 ```javascript
-const environment = process.env.NODE_ENV || 'development';
-const config = require(`./config/${environment}.json`);
+const libFable = require('fable');
+
+const environment = (typeof process !== 'undefined' && process.env && process.env.NODE_ENV)
+    ? process.env.NODE_ENV
+    : 'development';
+
+// In Node.js you would load config like this:
+//   const config = require(`./config/${environment}.json`);
+// In this playground we just construct an in-memory equivalent.
+const config = { Product: 'MyApp', Environment: environment };
 
-const fable = new Fable(config);
+const fable = new libFable(config);
+console.log('environment:', environment);
+console.log('Configured product:', fable.settings.Product);
 ```
 
 ## Precedent Integration
@@ -98,6 +133,8 @@ const fable = new Fable(config);
 The Settings Manager uses precedent for deep configuration merging:
 
 ```javascript
+const libFable = require('fable');
+
 // Base configuration
 const baseConfig = {
     API: {
@@ -113,6 +150,10 @@ const envConfig = {
     }
 };
 
+// Merge happens automatically through Fable's settings layer (precedent)
+const fable = new libFable(baseConfig);
+fable.settingsManager.fill(envConfig);
+console.log('Merged API settings:', fable.settings.API);
 // Result: { API: { Timeout: 30000, RetryCount: 3 } }
 ```
 
@@ -121,41 +162,60 @@ const envConfig = {
 ### Layered Configuration
 
 ```javascript
-const defaults = require('./config/default.json');
-const environment = require(`./config/${process.env.NODE_ENV}.json`);
-const local = require('./config/local.json');  // gitignored
-
-const fable = new Fable({
+const libFable = require('fable');
+
+// In Node.js you would load these from JSON files on disk:
+//   const defaults    = require('./config/default.json');
+//   const environment = require(`./config/${process.env.NODE_ENV}.json`);
+//   const local       = require('./config/local.json');  // gitignored
+// For the playground we use in-memory objects to show the layering shape:
+const defaults    = { Product: 'MyApp', API: { Timeout: 5000 } };
+const environment = { API: { Timeout: 30000 } };
+const local       = { API: { BaseURL: 'http://localhost:8080' } };
+
+const fable = new libFable({
     ...defaults,
     ...environment,
     ...local
 });
+
+console.log('Layered config result:', fable.settings.API);
 ```
 
 ### Feature Flags
 
 ```javascript
-const fable = new Fable({
+const libFable = require('fable');
+
+const env = (typeof process !== 'undefined' && process.env) ? process.env : {};
+
+const fable = new libFable({
     Features: {
-        NewDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
+        NewDashboard: env.FEATURE_NEW_DASHBOARD === 'true',
         BetaAPI: false
     }
 });
 
 // Usage
 if (fable.settings.Features.NewDashboard) {
-    // New dashboard code
+    console.log('NewDashboard feature is ON');
+} else {
+    console.log('NewDashboard feature is OFF (set FEATURE_NEW_DASHBOARD=true to enable)');
 }
 ```
 
 ### Service Configuration
 
 ```javascript
-const fable = new Fable({
+const libFable = require('fable');
+
+const env = (typeof process !== 'undefined' && process.env) ? process.env : {};
+
+const fable = new libFable({
     Services: {
         Email: {
             Provider: 'sendgrid',
-            APIKey: process.env.SENDGRID_API_KEY
+            APIKey: env.SENDGRID_API_KEY
         },
         Storage: {
             Provider: 's3',
@@ -163,6 +223,9 @@ const fable = new Fable({
         }
     }
 });
+
+console.log('Email provider:', fable.settings.Services.Email.Provider);
+console.log('Storage bucket:', fable.settings.Services.Storage.Bucket);
 ```
 
 ## Accessing Settings in Services
@@ -170,9 +233,17 @@ const fable = new Fable({
 All Fable services can access settings:
 
 ```javascript
+const libFable = require('fable');
+const libFableServiceBase = require('fable-serviceproviderbase');
+const fable = new libFable({
+    Product: 'SettingsServiceDemo',
+    API: { BaseURL: 'https://api.example.com' }
+});
+
 class MyService extends libFableServiceBase {
     constructor(pFable, pOptions, pServiceHash) {
         super(pFable, pOptions, pServiceHash);
+        this.serviceType = 'MyService';
 
         // Access global settings
         this.apiUrl = this.fable.settings.API.BaseURL;
@@ -181,6 +252,11 @@ class MyService extends libFableServiceBase {
         this.localOption = this.options.myOption;
     }
 }
+
+fable.addAndInstantiateServiceType('MyService', MyService);
+const svc = fable.instantiateServiceProvider('MyService', { myOption: 'demo-value' }, 'demo');
+console.log('apiUrl:',      svc.apiUrl);
+console.log('localOption:', svc.localOption);
 ```
 
 ## Common Configuration Options
@@ -188,40 +264,44 @@ class MyService extends libFableServiceBase {
 ### Product Information
 
 ```javascript
-{
+const productInfoConfig = {
     Product: 'MyApp',
     ProductVersion: '1.0.0'
-}
+};
+console.log('productInfoConfig:', productInfoConfig);
 ```
 
 ### UUID Configuration
 
 ```javascript
-{
+const uuidConfig = {
     UUID: {
         DataCenter: 1,  // 0-31
         Worker: 5       // 0-31
     }
-}
+};
+console.log('uuidConfig:', uuidConfig);
 ```
 
 ### Logging Configuration
 
 ```javascript
-{
+const loggingConfig = {
     LogStreams: [
         { level: 'info' },
         { level: 'error', path: '/var/log/app/error.log' }
     ]
-}
+};
+console.log('loggingConfig:', loggingConfig);
 ```
 
 ### REST Client Configuration
 
 ```javascript
-{
+const restClientConfig = {
     RestClientURLPrefix: 'https://api.example.com/v1'
-}
+};
+console.log('restClientConfig:', restClientConfig);
 ```
 
 ## Best Practices
@@ -233,24 +313,28 @@ class MyService extends libFableServiceBase {
 5. **Validate on startup**: Check for required settings early
 
 ```javascript
+const libFable = require('fable');
+
 // Validation example
-const fable = new Fable(config);
+const config = { Product: 'MyApp', Database: { Host: 'localhost' } };
+const fable = new libFable(config);
 
 if (!fable.settings.Database?.Host) {
     throw new Error('Database.Host is required');
 }
+console.log('Validation passed — Database.Host =', fable.settings.Database.Host);
 ```
 
 ## Reading External Config Files
 
 ```javascript
-const fs = require('fs');
-const path = require('path');
-
-const configPath = path.join(__dirname, 'config.json');
-const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-
-const fable = new Fable(config);
+// Node.js reference — this pattern uses fs which is not available in the browser playground.
+console.info("In Node.js:");
+console.info("    const fs   = require('fs');");
+console.info("    const path = require('path');");
+console.info("    const configPath = path.join(__dirname, 'config.json');");
+console.info("    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));");
+console.info("    const fable = new (require('fable'))(config);");
 ```
 
 ## Runtime Configuration Updates
@@ -258,8 +342,17 @@ const fable = new Fable(config);
 While generally not recommended, settings can be modified at runtime:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({
+    Product: 'RuntimeMutationDemo',
+    MyFeature: { Enabled: false }
+});
+
+console.log('Before:', fable.settings.MyFeature.Enabled);
+
 // Not recommended, but possible
 fable.settings.MyFeature.Enabled = true;
 
+console.log('After:',  fable.settings.MyFeature.Enabled);
 // Better: Use a service for dynamic configuration
 ```

package/docs/services/template.md

@@ -5,11 +5,16 @@ The Template service provides underscore/lodash-style template compilation and r
 ## Access
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+
 // On-demand service - instantiate when needed
 const template = fable.instantiateServiceProvider('Template');
+console.log('template service:', typeof template);
 
 // Or use the Utility service shorthand
 const renderFn = fable.Utility.template('Hello, <%= name %>!');
+console.log('renderFn:', typeof renderFn);
 ```
 
 ## Template Syntax
@@ -19,10 +24,13 @@ const renderFn = fable.Utility.template('Hello, <%= name %>!');
 Output a value:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+
 const template = fable.instantiateServiceProvider('Template');
 const render = template.buildTemplateFunction('Hello, <%= name %>!');
 
-render({ name: 'World' });  // Returns 'Hello, World!'
+console.log(render({ name: 'World' }));  // Returns 'Hello, World!'
 ```
 
 ### Evaluation (`<% %>`)
@@ -30,13 +38,17 @@ render({ name: 'World' });  // Returns 'Hello, World!'
 Execute JavaScript code:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+const template = fable.instantiateServiceProvider('Template');
+
 const render = template.buildTemplateFunction(`
     <% for (var i = 0; i < items.length; i++) { %>
         Item: <%= items[i] %>
     <% } %>
 `);
 
-render({ items: ['Apple', 'Banana', 'Cherry'] });
+console.log(render({ items: ['Apple', 'Banana', 'Cherry'] }));
 ```
 
 ## Basic Usage
@@ -44,14 +56,17 @@ render({ items: ['Apple', 'Banana', 'Cherry'] });
 ### Create and Use Template
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+
 const template = fable.instantiateServiceProvider('Template');
 
 // Build the template function
 const greetingTemplate = template.buildTemplateFunction('Hello, <%= name %>!');
 
 // Use it multiple times
-greetingTemplate({ name: 'Alice' });  // 'Hello, Alice!'
-greetingTemplate({ name: 'Bob' });    // 'Hello, Bob!'
+console.log(greetingTemplate({ name: 'Alice' }));  // 'Hello, Alice!'
+console.log(greetingTemplate({ name: 'Bob' }));    // 'Hello, Bob!'
 ```
 
 ### Immediate Rendering
@@ -59,7 +74,12 @@ greetingTemplate({ name: 'Bob' });    // 'Hello, Bob!'
 Pass data as the second argument to render immediately:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+const template = fable.instantiateServiceProvider('Template');
+
 const result = template.buildTemplateFunction('Sum: <%= a + b %>', { a: 5, b: 3 });
+console.log(result);
 // Returns 'Sum: 8'
 ```
 
@@ -68,12 +88,15 @@ const result = template.buildTemplateFunction('Sum: <%= a + b %>', { a: 5, b: 3
 The Utility service provides a convenient wrapper:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+
 // Create a template function
 const greet = fable.Utility.template('Hello, <%= name %>!');
-greet({ name: 'World' });
+console.log(greet({ name: 'World' }));
 
 // Or render immediately
-fable.Utility.template('Hello, <%= name %>!', { name: 'World' });
+console.log(fable.Utility.template('Hello, <%= name %>!', { name: 'World' }));
 ```
 
 ### Hashed Templates
@@ -81,6 +104,9 @@ fable.Utility.template('Hello, <%= name %>!', { name: 'World' });
 Register templates for reuse by name:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+
 // Register a template
 fable.Utility.buildHashedTemplate('user-card', `
     <div class="card">
@@ -90,7 +116,7 @@ fable.Utility.buildHashedTemplate('user-card', `
 `);
 
 // Use the registered template
-fable.Utility.templates['user-card']({ user: { name: 'John', email: 'john@example.com' } });
+console.log(fable.Utility.templates['user-card']({ user: { name: 'John', email: 'john@example.com' } }));
 ```
 
 ## Examples
@@ -98,6 +124,10 @@ fable.Utility.templates['user-card']({ user: { name: 'John', email: 'john@exampl
 ### HTML Generation
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+const template = fable.instantiateServiceProvider('Template');
+
 const cardTemplate = template.buildTemplateFunction(`
     <div class="card">
         <h2><%= title %></h2>
@@ -108,17 +138,21 @@ const cardTemplate = template.buildTemplateFunction(`
     </div>
 `);
 
-cardTemplate({
+console.log(cardTemplate({
     title: 'Welcome',
     description: 'This is a card component',
     showButton: true,
     buttonText: 'Click Me'
-});
+}));
 ```
 
 ### Lists and Loops
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+const template = fable.instantiateServiceProvider('Template');
+
 const listTemplate = template.buildTemplateFunction(`
     <ul>
         <% for (var i = 0; i < items.length; i++) { %>
@@ -127,33 +161,41 @@ const listTemplate = template.buildTemplateFunction(`
     </ul>
 `);
 
-listTemplate({
+console.log(listTemplate({
     items: [
-        { name: 'Apple', price: 1.50 },
+        { name: 'Apple',  price: 1.50 },
         { name: 'Banana', price: 0.75 }
     ]
-});
+}));
 ```
 
 ### Conditional Content
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+const template = fable.instantiateServiceProvider('Template');
+
 const statusTemplate = template.buildTemplateFunction(`
-    <% if (status === 'active') { %>
+    <% if (status === "active") { %>
         <span class="badge-green">Active</span>
-    <% } else if (status === 'pending') { %>
+    <% } else if (status === "pending") { %>
         <span class="badge-yellow">Pending</span>
     <% } else { %>
         <span class="badge-red">Inactive</span>
     <% } %>
 `);
 
-statusTemplate({ status: 'active' });
+console.log(statusTemplate({ status: 'active' }));
 ```
 
 ### Nested Data
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+const template = fable.instantiateServiceProvider('Template');
+
 const profileTemplate = template.buildTemplateFunction(`
     <div class="profile">
         <h1><%= user.name %></h1>
@@ -166,7 +208,7 @@ const profileTemplate = template.buildTemplateFunction(`
     </div>
 `);
 
-profileTemplate({
+console.log(profileTemplate({
     user: {
         name: 'John Doe',
         contact: {
@@ -178,7 +220,7 @@ profileTemplate({
             { street: '456 Oak Ave', city: 'Other City' }
         ]
     }
-});
+}));
 ```
 
 ### Print Function
@@ -186,11 +228,15 @@ profileTemplate({
 Use `print()` for inline output:
 
 ```javascript
-const template = template.buildTemplateFunction(`
-    <% print('Hello'); print(' '); print('World'); %>
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+const template = fable.instantiateServiceProvider('Template');
+
+const printTemplate = template.buildTemplateFunction(`
+    <% print("Hello"); print(" "); print("World"); %>
 `);
 
-template({});  // Returns 'Hello World'
+console.log(printTemplate({}));  // Returns 'Hello World'
 ```
 
 ## Template Source Access
@@ -198,12 +244,15 @@ template({});  // Returns 'Hello World'
 After building a template, you can access the generated source:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'TemplateDemo', ProductVersion: '1.0.0' });
+
 const tpl = fable.instantiateServiceProvider('Template');
 tpl.buildTemplateFunction('Hello, <%= name %>!');
 
 // Access the generated function source
-console.log(tpl.TemplateSource);
-console.log(tpl.TemplateSourceCompiled);
+console.log('TemplateSource:',         tpl.TemplateSource);
+console.log('TemplateSourceCompiled:', tpl.TemplateSourceCompiled);
 ```
 
 ## Escape Handling