npm - fable - Versions diffs - 3.1.50 → 3.1.52 - Mend

fable 3.1.50 → 3.1.52

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (148) hide show

package/docs/services/meta-template.md ADDED Viewed

@@ -0,0 +1,268 @@
+# MetaTemplate Service
+## Access
+```javascript
+// On-demand service - instantiate when needed
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
+```
+## Basic Usage
+### Simple Template
+```javascript
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
+const result = metaTemplate.render('Hello, {~Name~}!', { Name: 'World' });
+// Returns 'Hello, World!'
+```
+### Template Syntax
+MetaTemplate uses a different syntax from the standard Template service:
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `{~Property~}` | Simple substitution | `{~Name~}` |
+| `{~Object.Property~}` | Nested property | `{~User.Name~}` |
+| `{~Array[0]~}` | Array access | `{~Items[0]~}` |
+## Advanced Features
+### Conditional Rendering
+```javascript
+const template = `
+{~Begin:If:ShowGreeting~}
+Hello, {~Name~}!
+{~End:If:ShowGreeting~}
+`;
+metaTemplate.render(template, { ShowGreeting: true, Name: 'World' });
+// Returns 'Hello, World!'
+metaTemplate.render(template, { ShowGreeting: false, Name: 'World' });
+// Returns ''
+```
+### Iteration
+```javascript
+const template = `
+{~Begin:Each:Items~}
+- {~Record.Name~}: {~Record.Value~}
+{~End:Each:Items~}
+`;
+const data = {
+    Items: [
+        { Name: 'Apple', Value: 1.50 },
+        { Name: 'Banana', Value: 0.75 }
+    ]
+};
+metaTemplate.render(template, data);
+// Returns:
+// - Apple: 1.50
+// - Banana: 0.75
+```
+### Nested Templates
+```javascript
+const outerTemplate = `
+<div class="container">
+{~InnerContent~}
+</div>
+`;
+const innerContent = '<p>Hello, {~Name~}!</p>';
+// First render inner
+const inner = metaTemplate.render(innerContent, { Name: 'World' });
+// Then render outer
+const outer = metaTemplate.render(outerTemplate, { InnerContent: inner });
+```
+## Template Inheritance
+### Define Base Template
+```javascript
+const baseTemplate = `
+<!DOCTYPE html>
+<html>
+<head><title>{~Title~}</title></head>
+<body>
+    <header>{~Header~}</header>
+    <main>{~Content~}</main>
+    <footer>{~Footer~}</footer>
+</body>
+</html>
+`;
+```
+### Extend Template
+```javascript
+const pageData = {
+    Title: 'My Page',
+    Header: '<h1>Welcome</h1>',
+    Content: '<p>Main content here</p>',
+    Footer: '<p>&copy; 2024</p>'
+};
+const page = metaTemplate.render(baseTemplate, pageData);
+```
+## Use Cases
+### Email Templates
+```javascript
+const emailTemplate = `
+Dear {~Recipient.Name~},
+{~Begin:If:HasOrder~}
+Your order #{~Order.Number~} has been {~Order.Status~}.
+Items:
+{~Begin:Each:Order.Items~}
+- {~Record.Name~} x {~Record.Quantity~}: ${~Record.Price~}
+{~End:Each:Order.Items~}
+Total: ${~Order.Total~}
+{~End:If:HasOrder~}
+{~Begin:If:IsPromotion~}
+Special offer: {~Promotion.Message~}
+{~End:If:IsPromotion~}
+Best regards,
+{~Sender.Name~}
+`;
+const emailData = {
+    Recipient: { Name: 'John' },
+    HasOrder: true,
+    Order: {
+        Number: '12345',
+        Status: 'shipped',
+        Items: [
+            { Name: 'Widget', Quantity: 2, Price: '29.99' },
+            { Name: 'Gadget', Quantity: 1, Price: '49.99' }
+        ],
+        Total: '109.97'
+    },
+    IsPromotion: false,
+    Sender: { Name: 'Support Team' }
+};
+const email = metaTemplate.render(emailTemplate, emailData);
+```
+### Report Generation
+```javascript
+const reportTemplate = `
+# {~Report.Title~}
+Generated: {~Report.Date~}
+## Summary
+- Total Records: {~Summary.TotalRecords~}
+- Processed: {~Summary.Processed~}
+- Errors: {~Summary.Errors~}
+## Details
+{~Begin:Each:Details~}
+### {~Record.Category~}
+{~Record.Description~}
+Count: {~Record.Count~}
+{~End:Each:Details~}
+{~Begin:If:HasWarnings~}
+## Warnings
+{~Begin:Each:Warnings~}
+- {~Record~}
+{~End:Each:Warnings~}
+{~End:If:HasWarnings~}
+`;
+```
+### Configuration File Generation
+```javascript
+const configTemplate = `
+# Application Configuration
+# Generated for {~Environment~}
+server:
+  host: {~Server.Host~}
+  port: {~Server.Port~}
+database:
+  host: {~Database.Host~}
+  name: {~Database.Name~}
+  {~Begin:If:Database.UseSSL~}
+  ssl: true
+  {~End:If:Database.UseSSL~}
+{~Begin:Each:Features~}
+{~Record.Name~}:
+  enabled: {~Record.Enabled~}
+{~End:Each:Features~}
+`;
+const config = metaTemplate.render(configTemplate, {
+    Environment: 'production',
+    Server: { Host: '0.0.0.0', Port: 8080 },
+    Database: { Host: 'db.example.com', Name: 'myapp', UseSSL: true },
+    Features: [
+        { Name: 'cache', Enabled: true },
+        { Name: 'debug', Enabled: false }
+    ]
+});
+```
+### Dynamic Forms
+```javascript
+const formTemplate = `
+<form action="{~Form.Action~}" method="{~Form.Method~}">
+{~Begin:Each:Form.Fields~}
+    <div class="field">
+        <label for="{~Record.Id~}">{~Record.Label~}</label>
+        <input type="{~Record.Type~}" id="{~Record.Id~}" name="{~Record.Name~}"
+               {~Begin:If:Record.Required~}required{~End:If:Record.Required~}>
+    </div>
+{~End:Each:Form.Fields~}
+    <button type="submit">{~Form.SubmitText~}</button>
+</form>
+`;
+```
+## Comparison with Template Service
+| Feature | Template | MetaTemplate |
+|---------|----------|--------------|
+| Syntax | `<%= %>` / `<% %>` | `{~ ~}` |
+| Conditionals | JavaScript `if` | `{~Begin:If~}` |
+| Loops | JavaScript `for` | `{~Begin:Each~}` |
+| JavaScript execution | Yes | Limited |
+| Use case | Code-heavy templates | Data-driven templates |
+## Best Practices
+1. **Use MetaTemplate for data-driven content**: When templates are mostly about inserting values
+2. **Use Template for logic-heavy content**: When you need complex JavaScript logic
+3. **Keep templates readable**: Use clear section names
+4. **Validate data before rendering**: Ensure required properties exist
+## Notes
+- MetaTemplate is designed for safer, more declarative templates
+- Less JavaScript execution means less risk of injection
+- Templates can be stored in files and loaded dynamically
+- The `Record` variable is special within `Each` blocks

package/docs/services/object-cache.md ADDED Viewed

@@ -0,0 +1,171 @@
+# ObjectCache Service
+The ObjectCache service (powered by [cachetrax](https://github.com/stevenvelozo/cachetrax)) provides in-memory object caching with size-based and time-based expiration, backed by a linked list for efficient eviction.
+## Access
+```javascript
+// On-demand service - instantiate when needed
+const cache = fable.instantiateServiceProvider('ObjectCache');
+// Create named caches for different purposes
+const userCache = fable.instantiateServiceProvider('ObjectCache', {}, 'user-cache');
+const sessionCache = fable.instantiateServiceProvider('ObjectCache', {}, 'session-cache');
+```
+## Basic Operations
+### Put (Add or Update)
+```javascript
+cache.put('some-data', 'my-key');
+// Stores 'some-data' with hash 'my-key'
+// If 'my-key' already exists, updates the stored datum
+cache.put({ name: 'John', age: 30 }, 'user-123');
+// Stores an object with hash 'user-123'
+```
+### Read
+```javascript
+const data = cache.read('my-key');
+// Returns the stored datum, or false if not found
+```
+### Expire (Remove)
+```javascript
+cache.expire('my-key');
+// Removes the entry from the cache and returns the removed node
+// Returns false if the key doesn't exist
+```
+### Touch (Refresh)
+```javascript
+cache.touch('my-key');
+// Moves the entry to the tail of the list and resets its timestamp
+// Useful for keeping frequently accessed items fresh
+```
+## Size-Based Expiration
+### maxLength
+Set `maxLength` to automatically evict the oldest entry when the cache exceeds the limit:
+```javascript
+cache.maxLength = 2;
+cache.put('A', 'ABC');
+cache.put('D', 'DEF');
+// Cache: [ABC, DEF] (length 2)
+cache.put('G', 'GHI');
+// ABC is automatically evicted
+// Cache: [DEF, GHI] (length 2)
+```
+Setting `maxLength` to `0` (the default) disables automatic size-based eviction on insert. To enforce a new smaller `maxLength` on existing entries, call `prune()`.
+## Time-Based Expiration
+### maxAge
+Set `maxAge` (in milliseconds) to expire entries older than the specified age when `prune()` is called:
+```javascript
+cache.maxAge = 60000; // 1 minute
+```
+## Pruning
+### prune(callback)
+Prune the cache based on both `maxAge` and `maxLength` rules. Expired entries are removed first, then size limits are enforced:
+```javascript
+cache.maxLength = 2;
+// After adding many entries...
+cache.prune((removedRecords) => {
+    console.log(`Pruned ${removedRecords.length} entries`);
+    // Cache is now within maxLength
+});
+```
+### pruneBasedOnExpiration(callback, removedRecords)
+Prune only entries older than `maxAge`:
+```javascript
+cache.maxAge = 30000; // 30 seconds
+cache.pruneBasedOnExpiration((removed) => {
+    console.log(`Expired ${removed.length} old entries`);
+});
+```
+### pruneBasedOnLength(callback, removedRecords)
+Prune only based on `maxLength`, popping entries from the head (oldest) of the list:
+```javascript
+cache.pruneBasedOnLength((removed) => {
+    console.log(`Evicted ${removed.length} entries for length`);
+});
+```
+### pruneCustom(callback, pruneFunction, removedRecords)
+Prune entries using a custom function. The function receives `(datum, hash, node)` and should return `true` to expire the entry:
+```javascript
+cache.pruneCustom(
+    (removed) => { console.log(`Custom pruned ${removed.length}`); },
+    (datum, hash, node) => {
+        // Expire entries where datum starts with 'temp'
+        return typeof datum === 'string' && datum.startsWith('temp');
+    }
+);
+```
+## Low-Level Access
+### getNode(hash)
+Get the full linked list node (including metadata) for a hash:
+```javascript
+const node = cache.getNode('my-key');
+// node.Datum — the stored data
+// node.Hash — the hash key
+// node.Metadata.Created — timestamp (ms) when the entry was created
+```
+### RecordMap
+Access the record map directly (a plain object mapping hashes to data):
+```javascript
+const allRecords = cache.RecordMap;
+// { 'my-key': 'some-data', 'user-123': { name: 'John', age: 30 } }
+```
+### Internal List
+The cache is backed by a linked list accessible via `cache._List`:
+```javascript
+cache._List.length  // Number of entries in the cache
+cache._List.head    // First (oldest) node
+cache._List.tail    // Last (newest) node
+```
+## Notes
+- Cache is in-memory only; data is lost on restart
+- `maxLength` of `0` means no automatic size limit
+- `maxAge` of `0` means no automatic time-based expiration
+- Automatic eviction on `put()` only removes one entry at a time; use `prune()` for bulk cleanup
+- Each node tracks its creation time in `node.Metadata.Created`

package/docs/services/operation.md ADDED Viewed

@@ -0,0 +1,207 @@
+# Operation Service
+The Operation service provides phased step execution with built-in progress tracking and logging, designed for complex multi-step workflows.
+## Access
+```javascript
+// On-demand service - instantiate when needed
+const operation = fable.instantiateServiceProvider('Operation', { Name: 'My Operation' }, 'MY-OP-1');
+```
+## Basic Usage
+### Create an Operation
+```javascript
+const operation = fable.instantiateServiceProvider('Operation', {
+    Name: 'Data Import'
+}, 'IMPORT-123');
+```
+### Add Steps
+Use `addStep()` to register sequential steps. Each step function receives a completion callback and runs with a bound context:
+```javascript
+operation.addStep(
+    function (fStepComplete) {
+        this.log.info('Validating input...');
+        // ... validation logic ...
+        fStepComplete();
+    },
+    {},                    // Step metadata (accessible as this.metadata / this.options)
+    'Validate',            // Step name
+    'Validate input data', // Step description
+    'VALIDATE-STEP'        // Step GUID (optional)
+);
+operation.addStep(
+    function (fStepComplete) {
+        this.log.info('Processing records...');
+        // ... processing logic ...
+        fStepComplete();
+    },
+    {},
+    'Process',
+    'Process all records',
+    'PROCESS-STEP'
+);
+```
+### Execute the Operation
+Steps execute sequentially in the order they were added:
+```javascript
+operation.execute((pError) => {
+    if (pError) {
+        fable.log.error('Operation failed', { error: pError.message });
+    } else {
+        fable.log.info('Operation completed successfully');
+    }
+});
+```
+## Step Context
+Inside a step function, `this` is bound to a context object with these properties:
+| Property | Description |
+|----------|-------------|
+| `this.log` | Logger (writes to both fable.log and operation state log) |
+| `this.fable` | Reference to the Fable instance |
+| `this.options` | Step metadata object (same as `this.metadata`) |
+| `this.metadata` | Step metadata object |
+| `this.ProgressTracker` | Progress tracker for this step |
+| `this.logProgressTrackerStatus()` | Log the current progress status |
+| `this.OperationState` | The full operation state object |
+| `this.StepState` | This step's state entry |
+## Progress Tracking
+### Set Total Operations for a Step
+```javascript
+operation.addStep(
+    function (fStepComplete) {
+        // ... step work ...
+        fStepComplete();
+    },
+    {}, 'Process Records', 'Process all records', 'PROCESS-STEP'
+);
+// Set expected total operations for the step
+operation.setStepTotalOperations('PROCESS-STEP', 100);
+```
+### Increment Progress Within a Step
+```javascript
+operation.addStep(
+    function (fStepComplete) {
+        this.ProgressTracker.setProgressTrackerTotalOperations(items.length);
+        let tmpAnticipate = this.fable.newAnticipate();
+        for (let i = 0; i < items.length; i++) {
+            tmpAnticipate.anticipate((fWorkComplete) => {
+                processItem(items[i]);
+                this.ProgressTracker.incrementProgressTracker(1);
+                this.logProgressTrackerStatus();
+                fWorkComplete();
+            });
+        }
+        tmpAnticipate.wait(fStepComplete);
+    },
+    {}, 'Process Items', 'Process each item with tracking', 'ITEMS-STEP'
+);
+```
+## Operation State and Logging
+The operation maintains a structured state object:
+```javascript
+operation.state.Metadata.UUID    // Unique identifier
+operation.state.Metadata.Name    // Operation name
+operation.state.Status.StepCount // Number of registered steps
+operation.state.Steps            // Array of step state entries
+operation.state.Log              // Array of log strings
+operation.state.Errors           // Array of error strings
+```
+### Built-in Log Methods
+The operation provides logging methods that write to both fable.log and the operation's internal log:
+```javascript
+operation.log.trace('Trace message');
+operation.log.debug('Debug message');
+operation.log.info('Info message');
+operation.log.warn('Warning message');
+operation.log.error('Error message');    // Also writes to state.Errors
+operation.log.fatal('Fatal message');    // Also writes to state.Errors
+```
+### Logging with Data
+```javascript
+operation.log.debug('Processing', { TestData: 'Ignition Complete' });
+// Appends JSON stringified data to the log
+```
+## Use Cases
+### Multi-Step Async Workflow
+```javascript
+function createImportOperation(fable, records) {
+    const operation = fable.instantiateServiceProvider('Operation', {
+        Name: 'Record Import'
+    });
+    operation.addStep(
+        function (fStepComplete) {
+            this.log.info(`Importing ${records.length} records...`);
+            this.ProgressTracker.setProgressTrackerTotalOperations(records.length);
+            let tmpAnticipate = this.fable.newAnticipate();
+            for (let i = 0; i < records.length; i++) {
+                tmpAnticipate.anticipate((fWorkComplete) => {
+                    importRecord(records[i], () => {
+                        this.ProgressTracker.incrementProgressTracker(1);
+                        this.logProgressTrackerStatus();
+                        fWorkComplete();
+                    });
+                });
+            }
+            tmpAnticipate.wait(fStepComplete);
+        },
+        {}, 'Import', 'Import all records', 'IMPORT'
+    );
+    operation.addStep(
+        function (fStepComplete) {
+            this.log.info('Finalizing...');
+            finalizeImport(fStepComplete);
+        },
+        {}, 'Finalize', 'Finalize the import'
+    );
+    return operation;
+}
+```
+## Notes
+- Steps execute sequentially in the order they were added
+- An operation can only be executed once; calling `execute()` again returns an error
+- Step functions are bound to a custom context (not the operation itself)
+- The service type is `'PhasedOperation'`
+- Each step gets its own progress tracker automatically
+- The operation tracks an overall progress tracker across all steps