fable 3.1.72 → 3.1.74

package/docs/services/logging.md

@@ -5,9 +5,12 @@ The Logging service provides a pluggable logging system that supports multiple o
 ## Access
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LoggingDemo', ProductVersion: '1.0.0' });
+
 // Pre-initialized, available directly
-fable.log
-fable.Logging
+console.log('fable.log:',     typeof fable.log);
+console.log('fable.Logging:', typeof fable.Logging);
 ```
 
 ## Log Levels
@@ -24,6 +27,9 @@ From most to least verbose:
 ## Basic Logging
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LoggingDemo', ProductVersion: '1.0.0' });
+
 fable.log.trace('Detailed trace information');
 fable.log.debug('Debug message');
 fable.log.info('Application started');
@@ -37,6 +43,9 @@ fable.log.fatal('Critical system failure');
 Pass additional context as a second parameter:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LoggingDemo', ProductVersion: '1.0.0' });
+
 fable.log.info('User logged in', { userId: 123, username: 'john' });
 fable.log.error('Database connection failed', { host: 'db.example.com', port: 5432 });
 ```
@@ -46,28 +55,23 @@ fable.log.error('Database connection failed', { host: 'db.example.com', port: 54
 Configure logging when creating a Fable instance:
 
 ```javascript
-const fable = new Fable({
+const libFable = require('fable');
+
+const fable = new libFable({
     Product: 'MyApp',
     ProductVersion: '1.0.0',
 
     LogStreams: [
         // Console output at info level
-        { level: 'info' },
-
-        // File output for errors
-        {
-            level: 'error',
-            path: '/var/log/myapp/error.log'
-        },
-
-        // MongoDB stream
-        {
-            level: 'warn',
-            streamtype: 'mongodb',
-            // MongoDB-specific configuration
-        }
+        { level: 'info' }
+
+        // In Node.js you can add file and external streams:
+        // { level: 'error', path: '/var/log/myapp/error.log' },
+        // { level: 'warn',  streamtype: 'mongodb' /* MongoDB-specific config */ }
     ]
 });
+
+fable.log.info('Logging configured with', fable.settings.LogStreams.length, 'stream(s)');
 ```
 
 ### Stream Configuration
@@ -85,7 +89,11 @@ Each log stream can have:
 Get the current timestamp:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LoggingDemo', ProductVersion: '1.0.0' });
+
 const timestamp = fable.log.getTimeStamp();
+console.log('timestamp:', timestamp);
 // Returns milliseconds since epoch
 ```
 
@@ -94,12 +102,21 @@ const timestamp = fable.log.getTimeStamp();
 Create custom log providers by extending `LogProviderBase`:
 
 ```javascript
-const LogProviderBase = require('fable').LogProviderBase;
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LoggingDemo', ProductVersion: '1.0.0' });
+
+// A stub connection for the playground demo
+function createConnection() {
+    return { send: (entry) => console.log('CustomLogProvider received entry:', entry) };
+}
+
+const LogProviderBase = require('fable-log').LogProviderBase;
 
 class CustomLogProvider extends LogProviderBase {
     initialize() {
         // Setup code
         this.myConnection = createConnection();
+        console.log('CustomLogProvider initialized');
     }
 
     write(pLogEntry) {
@@ -114,20 +131,24 @@ class CustomLogProvider extends LogProviderBase {
     }
 }
 
-// Register the custom provider
-fable.Logging.addStream(new CustomLogProvider(fable.Logging));
+// Register the custom provider with fable.Logging
+const customProvider = new CustomLogProvider(fable.Logging, { level: 'trace' });
+customProvider.initialize();
+fable.Logging.addLogger(customProvider);
+fable.log.info('CustomLogProvider registered — fable.log calls now also hit it');
 ```
 
 ### Log Entry Structure
 
 ```javascript
-{
+const sampleLogEntry = {
     dt: 1704067200000,           // Timestamp (milliseconds)
     lvl: 'info',                 // Log level
     src: 'MyApp v1.0.0',         // Product/version
     msg: 'User logged in',       // Message
     dat: { userId: 123 }         // Additional data (optional)
-}
+};
+console.log('sampleLogEntry:', sampleLogEntry);
 ```
 
 ## Log Streams
@@ -137,20 +158,22 @@ fable.Logging.addStream(new CustomLogProvider(fable.Logging));
 Outputs to standard console:
 
 ```javascript
-{
+const consoleStreamConfig = {
     level: 'info'  // Shows info and above
-}
+};
+console.log('consoleStreamConfig:', consoleStreamConfig);
 ```
 
 ### File Stream
 
-Writes to a file:
+Writes to a file (Node.js only):
 
 ```javascript
-{
+const fileStreamConfig = {
     level: 'error',
     path: '/var/log/myapp/error.log'
-}
+};
+console.log('fileStreamConfig:', fileStreamConfig);
 ```
 
 ### Multiple Streams
@@ -158,18 +181,21 @@ Writes to a file:
 Configure multiple outputs:
 
 ```javascript
-const fable = new Fable({
+const libFable = require('fable');
+
+const fable = new libFable({
     LogStreams: [
         // Development console (all levels)
-        { level: 'trace' },
-
-        // Production file (warnings and above)
-        { level: 'warn', path: '/var/log/app.log' },
+        { level: 'trace' }
 
-        // Error alerting service
-        { level: 'error', streamtype: 'alerting' }
+        // In Node.js you can add file and external streams:
+        // { level: 'warn',  path: '/var/log/app.log' },
+        // { level: 'error', streamtype: 'alerting' }
     ]
 });
+
+console.log('Configured streams:', fable.settings.LogStreams.length);
+fable.log.trace('Trace-level message (visible because lowest stream level is trace)');
 ```
 
 ## Noisiness Control
@@ -177,9 +203,17 @@ const fable = new Fable({
 Control the verbosity of internal Fable logging:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LoggingDemo', ProductVersion: '1.0.0' });
+
 fable.LogNoisiness = 0;  // Quiet (default)
+console.log('LogNoisiness =', fable.LogNoisiness);
+
 fable.LogNoisiness = 1;  // Normal
+console.log('LogNoisiness =', fable.LogNoisiness);
+
 fable.LogNoisiness = 2;  // Verbose
+console.log('LogNoisiness =', fable.LogNoisiness);
 ```
 
 ## Integration with Services
@@ -187,20 +221,29 @@ fable.LogNoisiness = 2;  // Verbose
 All Fable services have access to logging via `this.log`:
 
 ```javascript
+const libFable = require('fable');
+const libFableServiceBase = require('fable-serviceproviderbase');
+const fable = new libFable({ Product: 'LoggingDemo', ProductVersion: '1.0.0' });
+
 class MyService extends libFableServiceBase {
     constructor(pFable, pOptions, pServiceHash) {
         super(pFable, pOptions, pServiceHash);
+        this.serviceType = 'MyService';
     }
 
     doSomething() {
         this.log.info('Doing something');
         try {
             // operation
+            throw new Error('demo failure');
         } catch (error) {
             this.log.error('Operation failed', { error: error.message });
         }
     }
 }
+
+fable.addAndInstantiateServiceType('MyService', MyService);
+fable.MyService.doSomething();
 ```
 
 ## Best Practices
@@ -212,6 +255,11 @@ class MyService extends libFableServiceBase {
 5. **Use trace for detailed debugging**: Enable only when needed
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LoggingDemo', ProductVersion: '1.0.0' });
+
+const order = { id: 'order-001', total: 49.99 };
+
 // Good
 fable.log.info('Order processed', { orderId: order.id, total: order.total });
 
@@ -224,14 +272,22 @@ fable.log.info('Order processed: ' + JSON.stringify(order));
 Set up different logging based on environment:
 
 ```javascript
-const logStreams = process.env.NODE_ENV === 'production'
+const libFable = require('fable');
+
+const nodeEnv = (typeof process !== 'undefined' && process.env)
+    ? process.env.NODE_ENV
+    : 'browser';
+
+const logStreams = nodeEnv === 'production'
     ? [
-        { level: 'warn', path: '/var/log/app.log' },
+        { level: 'warn',  path: '/var/log/app.log' },
         { level: 'error', streamtype: 'alerting' }
       ]
     : [
         { level: 'trace' }  // Console only in development
       ];
 
-const fable = new Fable({ LogStreams: logStreams });
+const fable = new libFable({ LogStreams: logStreams });
+console.log('nodeEnv:', nodeEnv);
+console.log('LogStreams configured:', fable.settings.LogStreams);
 ```

package/docs/services/logic.md

@@ -5,8 +5,11 @@ The Logic service provides comparison and conditional operations, supporting bot
 ## Access
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
 // Auto-instantiated, available directly
-fable.Logic
+console.log('fable.Logic:', typeof fable.Logic);
 ```
 
 ## Conditional Check (checkIf)
@@ -14,7 +17,11 @@ fable.Logic
 Perform comparisons and return different values based on the result:
 
 ```javascript
-fable.Logic.checkIf(left, operator, right, onTrue, onFalse);
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
+// Signature shape — see the examples below for runnable invocations.
+console.log('checkIf signature: (left, operator, right, onTrue, onFalse) =>', typeof fable.Logic.checkIf);
 ```
 
 ### Parameters
@@ -43,13 +50,16 @@ fable.Logic.checkIf(left, operator, right, onTrue, onFalse);
 When both values can be parsed as numbers, arbitrary precision comparison is used:
 
 ```javascript
-fable.Logic.checkIf(10, '>', 5, 'greater', 'not greater');
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
+console.log(fable.Logic.checkIf(10, '>', 5, 'greater', 'not greater'));
 // Returns 'greater'
 
-fable.Logic.checkIf('3.14159', '==', '3.14159', 'equal', 'not equal');
+console.log(fable.Logic.checkIf('3.14159', '==', '3.14159', 'equal', 'not equal'));
 // Returns 'equal' (with small tolerance for ==)
 
-fable.Logic.checkIf('100', 'LTE', '50', 'yes', 'no');
+console.log(fable.Logic.checkIf('100', 'LTE', '50', 'yes', 'no'));
 // Returns 'no'
 ```
 
@@ -58,25 +68,31 @@ fable.Logic.checkIf('100', 'LTE', '50', 'yes', 'no');
 When either value is not a number, standard string comparison is used:
 
 ```javascript
-fable.Logic.checkIf('apple', '<', 'banana', 'first', 'second');
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
+console.log(fable.Logic.checkIf('apple', '<', 'banana', 'first', 'second'));
 // Returns 'first' (alphabetical order)
 
-fable.Logic.checkIf('Hello', '===', 'Hello', 'match', 'no match');
+console.log(fable.Logic.checkIf('Hello', '===', 'Hello', 'match', 'no match'));
 // Returns 'match'
 
-fable.Logic.checkIf('hello', '===', 'Hello', 'match', 'no match');
+console.log(fable.Logic.checkIf('hello', '===', 'Hello', 'match', 'no match'));
 // Returns 'no match' (case sensitive)
 ```
 
 #### Default False Values
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
 // String comparison defaults to empty string
-fable.Logic.checkIf('a', '>', 'b', 'yes');
+console.log(JSON.stringify(fable.Logic.checkIf('a', '>', 'b', 'yes')));
 // Returns '' (empty string) when false
 
 // Numeric comparison defaults to '0'
-fable.Logic.checkIf(5, '>', 10, 'yes');
+console.log(fable.Logic.checkIf(5, '>', 10, 'yes'));
 // Returns '0' when false
 ```
 
@@ -85,7 +101,11 @@ fable.Logic.checkIf(5, '>', 10, 'yes');
 Return different values based on whether a value is truthy:
 
 ```javascript
-fable.Logic.when(checkValue, onTrue, onFalse);
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
+// Signature shape — see the examples below for runnable invocations.
+console.log('when signature: (checkValue, onTrue, onFalse) =>', typeof fable.Logic.when);
 ```
 
 ### Parameters
@@ -104,23 +124,26 @@ The `when` method considers the following as falsy:
 ### Examples
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
 // Basic truthy check
-fable.Logic.when(true, 'yes', 'no');      // Returns 'yes'
-fable.Logic.when(false, 'yes', 'no');     // Returns 'no'
-fable.Logic.when('hello', 'yes', 'no');   // Returns 'yes'
-fable.Logic.when('', 'yes', 'no');        // Returns 'no'
+console.log(fable.Logic.when(true, 'yes', 'no'));      // Returns 'yes'
+console.log(fable.Logic.when(false, 'yes', 'no'));     // Returns 'no'
+console.log(fable.Logic.when('hello', 'yes', 'no'));   // Returns 'yes'
+console.log(fable.Logic.when('', 'yes', 'no'));        // Returns 'no'
 
 // With numbers
-fable.Logic.when(42, 'has value', 'empty');     // Returns 'has value'
-fable.Logic.when(0, 'has value', 'empty');      // Returns 'empty'
+console.log(fable.Logic.when(42, 'has value', 'empty'));     // Returns 'has value'
+console.log(fable.Logic.when(0, 'has value', 'empty'));      // Returns 'empty'
 
 // With arrays
-fable.Logic.when([1, 2, 3], 'has items', 'empty');  // Returns 'has items'
-fable.Logic.when([], 'has items', 'empty');         // Returns 'empty'
+console.log(fable.Logic.when([1, 2, 3], 'has items', 'empty'));  // Returns 'has items'
+console.log(fable.Logic.when([], 'has items', 'empty'));         // Returns 'empty'
 
 // With objects
-fable.Logic.when({ a: 1 }, 'has props', 'empty');   // Returns 'has props'
-fable.Logic.when({}, 'has props', 'empty');         // Returns 'empty'
+console.log(fable.Logic.when({ a: 1 }, 'has props', 'empty'));   // Returns 'has props'
+console.log(fable.Logic.when({}, 'has props', 'empty'));         // Returns 'empty'
 ```
 
 ## Use Cases
@@ -128,24 +151,41 @@ fable.Logic.when({}, 'has props', 'empty');         // Returns 'empty'
 ### Form Validation
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
+const formData = { age: 21 };
 const age = formData.age;
 const message = fable.Logic.checkIf(age, '>=', 18, 'Welcome!', 'Must be 18 or older');
+console.log(message);
 ```
 
 ### Conditional Display
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
+function getItems() { return ['apple', 'banana']; }
+
 const items = getItems();
 const display = fable.Logic.when(items, `Found ${items.length} items`, 'No items found');
+console.log(display);
 ```
 
 ### Numeric Thresholds
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
+function calculateScore() { return 85; }
+
 const score = calculateScore();
 const grade = fable.Logic.checkIf(score, '>=', 90, 'A',
               fable.Logic.checkIf(score, '>=', 80, 'B',
               fable.Logic.checkIf(score, '>=', 70, 'C', 'F')));
+console.log('score:', score, '-> grade:', grade);
 ```
 
 ### Template Conditionals
@@ -153,9 +193,17 @@ const grade = fable.Logic.checkIf(score, '>=', 90, 'A',
 Combined with the Template service:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'LogicDemo', ProductVersion: '1.0.0' });
+
+const user = { premium: true };
+// Use double-quoted strings inside <%= ... %> so underscore's template compiler
+// doesn't collide with the single-quoted wrapper it generates internally.
 const template = fable.Utility.template(`
-    <%= fable.Logic.when(user.premium, 'Premium Member', 'Free User') %>
+    <%= fable.Logic.when(user.premium, "Premium Member", "Free User") %>
 `);
+// The template references `fable` and `user`; pass them explicitly when rendering.
+console.log(template({ fable: fable, user: user }));
 ```
 
 ## Notes