fable 3.1.72 → 3.1.74

package/docs/services/README.md

@@ -45,23 +45,35 @@ These services are created when first requested:
 ### Accessing Services
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'ServicesDemo', ProductVersion: '1.0.0' });
+
 // Auto-instantiated services are available directly
-fable.Dates.dayJS().format('YYYY-MM-DD');
-fable.Math.addPrecise('1', '2');
+console.log('Today:',    fable.Dates.dayJS().format('YYYY-MM-DD'));
+console.log('1 + 2 =',   fable.Math.addPrecise('1', '2'));
 
 // On-demand services need to be instantiated first
 const restClient = fable.instantiateServiceProvider('RestClient');
-restClient.getJSON('https://api.example.com/data', (err, res, data) => {
-    console.log(data);
-});
+console.log('restClient instantiated:', typeof restClient);
+
+// In Node.js you would then call:
+// restClient.getJSON('https://api.example.com/data', (err, res, data) => console.log(data));
+// (Network calls are skipped here so the playground demo stays self-contained.)
 ```
 
 ### Creating Multiple Instances
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'ServicesDemo', ProductVersion: '1.0.0' });
+
 // Create named instances for different purposes
-const apiClient = fable.instantiateServiceProvider('RestClient', {}, 'api');
+const apiClient  = fable.instantiateServiceProvider('RestClient', {}, 'api');
 const authClient = fable.instantiateServiceProvider('RestClient', {}, 'auth');
+console.log('apiClient typeof:',  typeof apiClient);
+console.log('authClient typeof:', typeof authClient);
+console.log('Both instances live in fable.servicesMap.RestClient — keys:',
+    Object.keys(fable.servicesMap.RestClient));
 ```
 
 ### Service Options
@@ -69,8 +81,13 @@ const authClient = fable.instantiateServiceProvider('RestClient', {}, 'auth');
 Most services accept an options object during instantiation:
 
 ```javascript
-const service = fable.instantiateServiceProvider('ServiceType', {
-    option1: 'value1',
-    option2: 'value2'
+const libFable = require('fable');
+const fable = new libFable({ Product: 'ServicesDemo', ProductVersion: '1.0.0' });
+
+// Shape of the call — replace 'Template' with whichever service you want.
+const service = fable.instantiateServiceProvider('Template', {
+    // option1: 'value1',
+    // option2: 'value2'
 }, 'optional-hash');
+console.log('Service instantiated via the generic pattern:', typeof service);
 ```

package/docs/services/anticipate.md

@@ -5,11 +5,16 @@ The Anticipate service provides asynchronous operation sequencing, allowing you
 ## Access
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
 // On-demand service - instantiate when needed
-const tmpAnticipate = fable.instantiateServiceProvider('Anticipate');
+const tmpAnticipateService = fable.instantiateServiceProvider('Anticipate');
+console.log('Service instance:', typeof tmpAnticipateService);
 
 // Or use the factory method (creates unregistered instance)
-const tmpAnticipate = fable.newAnticipate();
+const tmpAnticipateFactory = fable.newAnticipate();
+console.log('Factory instance:', typeof tmpAnticipateFactory);
 ```
 
 ## Basic Usage
@@ -17,6 +22,9 @@ const tmpAnticipate = fable.newAnticipate();
 ### Sequential Operations
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
 const tmpAnticipate = fable.newAnticipate();
 
 tmpAnticipate.anticipate(function (fCallback)
@@ -60,6 +68,14 @@ tmpAnticipate.wait(function (pError)
 Since Anticipate callbacks receive only `fCallback`, use closure scope or external variables to share data between steps:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
+// Stubbed async helpers for the playground demo
+function fetchUser(pId, fCallback) { setTimeout(() => fCallback({ id: pId, name: 'User#' + pId }), 5); }
+function loadPreferences(pId, fCallback) { setTimeout(() => fCallback({ theme: 'dark' }), 5); }
+function render(pUser, pPrefs) { console.log('rendered:', pUser, pPrefs); }
+
 const tmpAnticipate = fable.newAnticipate();
 let tmpUser = null;
 let tmpPreferences = null;
@@ -91,6 +107,10 @@ tmpAnticipate.wait(function (pError)
 	{
 		console.error('Workflow failed:', pError);
 	}
+	else
+	{
+		console.log('Workflow done.');
+	}
 });
 ```
 
@@ -101,11 +121,17 @@ tmpAnticipate.wait(function (pError)
 Add an asynchronous operation to the queue. Operations run sequentially by default (one at a time).
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+const tmpAnticipate = fable.newAnticipate();
+
 tmpAnticipate.anticipate(function (fCallback)
 {
 	// Do async work
+	console.log('async work running');
 	fCallback();  // Call when done, or fCallback(pError) to signal failure
 });
+tmpAnticipate.wait(function (pError) { console.log('wait done, pError:', pError); });
 ```
 
 The step function receives one parameter:
@@ -116,12 +142,21 @@ The step function receives one parameter:
 Register a callback to run when all queued operations complete (or when an error occurs):
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+const tmpAnticipate = fable.newAnticipate();
+
+tmpAnticipate.anticipate(function (fCallback) { console.log('step done'); fCallback(); });
 tmpAnticipate.wait(function (pError)
 {
 	if (pError)
 	{
 		console.error('Error:', pError);
 	}
+	else
+	{
+		console.log('All operations completed');
+	}
 });
 ```
 
@@ -130,8 +165,12 @@ tmpAnticipate.wait(function (pError)
 Control concurrency. Default is `1` (sequential). Set higher for parallel execution:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
 const tmpAnticipate = fable.newAnticipate();
 tmpAnticipate.maxOperations = 5;  // Run up to 5 operations concurrently
+console.log('maxOperations:', tmpAnticipate.maxOperations);
 ```
 
 ## Error Handling
@@ -141,6 +180,9 @@ tmpAnticipate.maxOperations = 5;  // Run up to 5 operations concurrently
 When an operation passes an error to its callback, remaining queued operations are skipped and the `wait` callback fires immediately with the error:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
 const tmpAnticipate = fable.newAnticipate();
 let tmpPostErrorRan = false;
 
@@ -162,8 +204,8 @@ tmpAnticipate.anticipate(function (fCallback)
 });
 tmpAnticipate.wait(function (pError)
 {
-	console.log('Error:', pError);          // Error: Something went wrong
-	console.log('Step 3 ran:', tmpPostErrorRan);  // false
+	console.log('Caught error:', pError && pError.message);   // Something went wrong
+	console.log('Step 3 ran:',   tmpPostErrorRan);            // false
 });
 ```
 
@@ -172,6 +214,11 @@ tmpAnticipate.wait(function (pError)
 To handle errors without bailing out, catch them inside the step and continue:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
+function riskyOperation() { throw new Error('demo failure'); }
+
 const tmpAnticipate = fable.newAnticipate();
 let tmpRecoveredError = null;
 
@@ -192,13 +239,13 @@ tmpAnticipate.anticipate(function (fCallback)
 {
 	if (tmpRecoveredError)
 	{
-		console.log('Recovered from:', tmpRecoveredError);
+		console.log('Recovered from:', tmpRecoveredError.message);
 	}
 	fCallback();
 });
 tmpAnticipate.wait(function (pError)
 {
-	console.log('Pipeline completed');
+	console.log('Pipeline completed, pError:', pError);
 });
 ```
 
@@ -207,6 +254,12 @@ tmpAnticipate.wait(function (pError)
 ### Database Migrations
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
+// Stub DB driver for the playground demo
+const db = { query: (sql, cb) => { console.log('SQL:', sql); cb(null); } };
+
 const tmpMigrate = fable.newAnticipate();
 
 tmpMigrate.anticipate(function (fCallback)
@@ -231,6 +284,17 @@ tmpMigrate.wait(function (pError)
 ### API Request Chains
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
+// Stub API + credentials + process for the playground demo
+const credentials = { user: 'demo', pass: 'demo' };
+const api = {
+	login:   (creds, cb) => setTimeout(() => cb('tok-' + Math.floor(Math.random() * 1000)), 5),
+	getData: (tok,   cb) => setTimeout(() => cb({ rows: 3, tok }), 5)
+};
+function processData(pData) { console.log('processed data:', pData); }
+
 const tmpWorkflow = fable.newAnticipate();
 let tmpToken = null;
 let tmpData = null;
@@ -253,33 +317,33 @@ tmpWorkflow.anticipate(function (fCallback)
 });
 tmpWorkflow.anticipate(function (fCallback)
 {
-	process(tmpData);
+	processData(tmpData);
 	fCallback();
 });
 tmpWorkflow.wait(function (pError)
 {
 	if (pError) console.error('Workflow failed:', pError);
+	else console.log('Workflow OK; token:', tmpToken);
 });
 ```
 
 ### Parallel Operations
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
+// Stub fetchers for the playground demo
+function fetchFromServiceA(cb) { setTimeout(() => { console.log('A done'); cb(); }, 5); }
+function fetchFromServiceB(cb) { setTimeout(() => { console.log('B done'); cb(); }, 5); }
+function fetchFromServiceC(cb) { setTimeout(() => { console.log('C done'); cb(); }, 5); }
+
 const tmpParallel = fable.newAnticipate();
 tmpParallel.maxOperations = 3;  // Run up to 3 at a time
 
-tmpParallel.anticipate(function (fCallback)
-{
-	fetchFromServiceA(function () { fCallback(); });
-});
-tmpParallel.anticipate(function (fCallback)
-{
-	fetchFromServiceB(function () { fCallback(); });
-});
-tmpParallel.anticipate(function (fCallback)
-{
-	fetchFromServiceC(function () { fCallback(); });
-});
+tmpParallel.anticipate(function (fCallback) { fetchFromServiceA(function () { fCallback(); }); });
+tmpParallel.anticipate(function (fCallback) { fetchFromServiceB(function () { fCallback(); }); });
+tmpParallel.anticipate(function (fCallback) { fetchFromServiceC(function () { fCallback(); }); });
 tmpParallel.wait(function (pError)
 {
 	console.log('All fetches complete');
@@ -289,24 +353,21 @@ tmpParallel.wait(function (pError)
 ### Build Pipeline
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
+// Stub build steps for the playground demo
+function cleanBuildDir(cb) { console.log('clean'); cb(); }
+function compile(cb)       { console.log('compile'); cb(); }
+function bundle(cb)        { console.log('bundle'); cb(); }
+function minify(cb)        { console.log('minify'); cb(); }
+
 const tmpBuild = fable.newAnticipate();
 
-tmpBuild.anticipate(function (fCallback)
-{
-	cleanBuildDir(fCallback);
-});
-tmpBuild.anticipate(function (fCallback)
-{
-	compile(fCallback);
-});
-tmpBuild.anticipate(function (fCallback)
-{
-	bundle(fCallback);
-});
-tmpBuild.anticipate(function (fCallback)
-{
-	minify(fCallback);
-});
+tmpBuild.anticipate(function (fCallback) { cleanBuildDir(fCallback); });
+tmpBuild.anticipate(function (fCallback) { compile(fCallback); });
+tmpBuild.anticipate(function (fCallback) { bundle(fCallback); });
+tmpBuild.anticipate(function (fCallback) { minify(fCallback); });
 tmpBuild.wait(function (pError)
 {
 	if (pError) throw pError;
@@ -319,13 +380,16 @@ tmpBuild.wait(function (pError)
 Create multiple independent workflows:
 
 ```javascript
-const tmpUserWorkflow = fable.newAnticipate();
+const libFable = require('fable');
+const fable = new libFable({ Product: 'AnticipateDemo', ProductVersion: '1.0.0' });
+
+const tmpUserWorkflow  = fable.newAnticipate();
 const tmpOrderWorkflow = fable.newAnticipate();
 
 // These run independently
-tmpUserWorkflow.anticipate(function (fCallback) { /* ... */ fCallback(); });
-tmpUserWorkflow.wait(function (pError) { /* ... */ });
+tmpUserWorkflow.anticipate(function (fCallback) { console.log('user step');  fCallback(); });
+tmpUserWorkflow.wait(function (pError) { console.log('user workflow done'); });
 
-tmpOrderWorkflow.anticipate(function (fCallback) { /* ... */ fCallback(); });
-tmpOrderWorkflow.wait(function (pError) { /* ... */ });
+tmpOrderWorkflow.anticipate(function (fCallback) { console.log('order step'); fCallback(); });
+tmpOrderWorkflow.wait(function (pError) { console.log('order workflow done'); });
 ```

package/docs/services/csv-parser.md

@@ -5,8 +5,12 @@ The CSVParser service provides line-by-line CSV parsing with support for multi-l
 ## Access
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'CSVDemo', ProductVersion: '1.0.0' });
+
 // On-demand service - instantiate when needed
 const csvParser = fable.instantiateServiceProvider('CSVParser', {}, 'CSV Parser-123');
+console.log('csvParser:', typeof csvParser);
 ```
 
 ## Basic Usage
@@ -16,28 +20,32 @@ const csvParser = fable.instantiateServiceProvider('CSVParser', {}, 'CSV Parser-
 The primary method is `parseCSVLine()`, which processes one line at a time and returns a parsed record (or `false` if the line is part of a multi-line quoted field or is the header row):
 
 ```javascript
-const libFS = require('fs');
-const libReadline = require('readline');
-
+const libFable = require('fable');
+const fable = new libFable({ Product: 'CSVDemo', ProductVersion: '1.0.0' });
 const csvParser = fable.instantiateServiceProvider('CSVParser');
-const records = [];
 
-const rl = libReadline.createInterface({
-    input: libFS.createReadStream('data.csv'),
-    crlfDelay: Infinity
-});
-
-rl.on('line', (line) => {
-    let record = csvParser.parseCSVLine(line);
-    if (record) {
+// In Node.js the typical streaming pattern is:
+//   const libFS = require('fs');
+//   const libReadline = require('readline');
+//   const rl = libReadline.createInterface({ input: libFS.createReadStream('data.csv'), crlfDelay: Infinity });
+//   rl.on('line', line => { const rec = csvParser.parseCSVLine(line); if (rec) records.push(rec); });
+//   rl.on('close', () => console.log(`Parsed ${records.length} records`));
+//
+// The browser playground has no fs/readline, so the snippet below parses an
+// in-memory CSV string line-by-line using the exact same parseCSVLine() loop:
+
+const csvSource = "name,age,city\nJohn,30,New York\nJane,25,Boston";
+const records   = [];
+for (const line of csvSource.split('\n'))
+{
+    const record = csvParser.parseCSVLine(line);
+    if (record)
+    {
         records.push(record);
     }
-});
-
-rl.on('close', () => {
-    console.log(`Parsed ${records.length} records`);
-    // records[0] is an object like { name: 'John', age: '30', city: 'New York' }
-});
+}
+console.log(`Parsed ${records.length} records`);
+console.log('records[0]:', records[0]);
 ```
 
 ### Using FilePersistence Wrapper
@@ -45,17 +53,13 @@ rl.on('close', () => {
 The FilePersistence service provides a convenience method for CSV reading:
 
 ```javascript
-fable.instantiateServiceProvider('FilePersistence');
-
-fable.FilePersistence.readFileCSV('data.csv', {},
-    (record) => {
-        // Called for each parsed record (as a JSON object)
-        console.log(record.name, record.age);
-    },
-    () => {
-        // Called when parsing is complete
-        console.log('Done!');
-    });
+// Node.js reference — fable.FilePersistence.readFileCSV uses fs, which the
+// browser playground doesn't expose. The shape of the call:
+console.info("In Node.js:");
+console.info("    fable.instantiateServiceProvider('FilePersistence');");
+console.info("    fable.FilePersistence.readFileCSV('data.csv', {},");
+console.info("        (record) => console.log(record.name, record.age),");
+console.info("        () => console.log('Done!'));");
 ```
 
 ## How Parsing Works
@@ -77,6 +81,9 @@ The CSVParser is stateful and processes lines sequentially:
 Set these properties on the parser instance after creation:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'CSVDemo', ProductVersion: '1.0.0' });
+
 const csvParser = fable.instantiateServiceProvider('CSVParser');
 
 csvParser.Delimiter = ';';           // Default: ','
@@ -86,6 +93,11 @@ csvParser.HeaderLineIndex = 0;       // Default: 0 - which line is the header
 csvParser.EmitJSON = true;           // Default: true - emit objects vs arrays
 csvParser.EmitHeader = false;        // Default: false - return header row or skip it
 csvParser.EscapedQuoteString = '"';  // Default: '"' - replacement for escaped quotes
+
+console.log('Delimiter:',       csvParser.Delimiter);
+console.log('QuoteCharacter:',  csvParser.QuoteCharacter);
+console.log('HasHeader:',       csvParser.HasHeader);
+console.log('EmitJSON:',        csvParser.EmitJSON);
 ```
 
 ## Methods
@@ -99,7 +111,12 @@ Parse a single line of CSV. Returns a record object, an array, or `false`.
 Manually set column headers (an array of strings):
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'CSVDemo', ProductVersion: '1.0.0' });
+const csvParser = fable.instantiateServiceProvider('CSVParser');
+
 csvParser.setHeader(['name', 'age', 'city']);
+console.log('Header set; field names:', csvParser.HeaderFieldNames);
 ```
 
 ### `marshalRowToJSON(rowArray)`
@@ -107,8 +124,12 @@ csvParser.setHeader(['name', 'age', 'city']);
 Convert a row array into a JSON object using the current headers:
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'CSVDemo', ProductVersion: '1.0.0' });
+const csvParser = fable.instantiateServiceProvider('CSVParser');
+
 csvParser.setHeader(['name', 'age']);
-csvParser.marshalRowToJSON(['John', '30']);
+console.log(csvParser.marshalRowToJSON(['John', '30']));
 // Returns { name: 'John', age: '30' }
 ```
 
@@ -123,11 +144,18 @@ Emit the currently accumulated row. If `formatAsJSON` is true (default), returns
 ## Parser State Properties
 
 ```javascript
-csvParser.LinesParsed   // Total number of lines processed
-csvParser.RowsEmitted   // Total number of data rows emitted
-csvParser.InQuote       // Whether currently inside a quoted field
-csvParser.Header        // Current header array
-csvParser.HeaderFieldNames  // Trimmed header field names used as object keys
+const libFable = require('fable');
+const fable = new libFable({ Product: 'CSVDemo', ProductVersion: '1.0.0' });
+const csvParser = fable.instantiateServiceProvider('CSVParser');
+
+// Parse a small CSV inline so the state properties have something to show:
+for (const line of "name,age\nJohn,30".split('\n')) csvParser.parseCSVLine(line);
+
+console.log('LinesParsed:',       csvParser.LinesParsed);
+console.log('RowsEmitted:',       csvParser.RowsEmitted);
+console.log('InQuote:',           csvParser.InQuote);
+console.log('Header:',            csvParser.Header);
+console.log('HeaderFieldNames:',  csvParser.HeaderFieldNames);
 ```
 
 ## Handling Special Cases