fable 3.1.51 → 3.1.52

package/docs/services/settings-manager.md

@@ -0,0 +1,265 @@
+# Settings Manager Service
+
+The Settings Manager provides centralized configuration management for Fable applications, with support for environment-aware settings and default value merging.
+
+## Access
+
+```javascript
+// Pre-initialized, available directly
+fable.SettingsManager
+fable.settings  // Shorthand for SettingsManager.settings
+fable.settingsManager  // Alias
+```
+
+## Basic Usage
+
+### Reading Settings
+
+```javascript
+// Access settings directly
+const productName = fable.settings.Product;
+const version = fable.settings.ProductVersion;
+
+// Access nested settings
+const dbHost = fable.settings.Database.Host;
+```
+
+### Providing Configuration
+
+Pass settings when creating a Fable instance:
+
+```javascript
+const fable = new Fable({
+    Product: 'MyApplication',
+    ProductVersion: '1.0.0',
+
+    Database: {
+        Host: 'localhost',
+        Port: 5432,
+        Name: 'myapp'
+    },
+
+    API: {
+        BaseURL: 'https://api.example.com',
+        Timeout: 30000
+    }
+});
+```
+
+## Default Settings
+
+Fable provides sensible defaults that your configuration extends:
+
+```javascript
+{
+    Product: 'Fable',
+    ProductVersion: '0.0.0',
+
+    UUID: {
+        DataCenter: 0,
+        Worker: 0
+    },
+
+    LogStreams: [
+        { level: 'info' }
+    ]
+}
+```
+
+Your settings are merged with these defaults using [precedent](https://github.com/stevenvelozo/precedent).
+
+## Environment-Aware Configuration
+
+### Using Environment Variables
+
+```javascript
+const fable = new Fable({
+    Product: 'MyApp',
+
+    Database: {
+        Host: process.env.DB_HOST || 'localhost',
+        Port: parseInt(process.env.DB_PORT) || 5432,
+        Password: process.env.DB_PASSWORD
+    }
+});
+```
+
+### Environment-Specific Config Files
+
+```javascript
+const environment = process.env.NODE_ENV || 'development';
+const config = require(`./config/${environment}.json`);
+
+const fable = new Fable(config);
+```
+
+## Precedent Integration
+
+The Settings Manager uses precedent for deep configuration merging:
+
+```javascript
+// Base configuration
+const baseConfig = {
+    API: {
+        Timeout: 5000,
+        RetryCount: 3
+    }
+};
+
+// Environment override
+const envConfig = {
+    API: {
+        Timeout: 30000  // Override just the timeout
+    }
+};
+
+// Result: { API: { Timeout: 30000, RetryCount: 3 } }
+```
+
+## Configuration Patterns
+
+### 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({
+    ...defaults,
+    ...environment,
+    ...local
+});
+```
+
+### Feature Flags
+
+```javascript
+const fable = new Fable({
+    Features: {
+        NewDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
+        BetaAPI: false
+    }
+});
+
+// Usage
+if (fable.settings.Features.NewDashboard) {
+    // New dashboard code
+}
+```
+
+### Service Configuration
+
+```javascript
+const fable = new Fable({
+    Services: {
+        Email: {
+            Provider: 'sendgrid',
+            APIKey: process.env.SENDGRID_API_KEY
+        },
+        Storage: {
+            Provider: 's3',
+            Bucket: 'my-app-storage'
+        }
+    }
+});
+```
+
+## Accessing Settings in Services
+
+All Fable services can access settings:
+
+```javascript
+class MyService extends libFableServiceBase {
+    constructor(pFable, pOptions, pServiceHash) {
+        super(pFable, pOptions, pServiceHash);
+
+        // Access global settings
+        this.apiUrl = this.fable.settings.API.BaseURL;
+
+        // Access service-specific options
+        this.localOption = this.options.myOption;
+    }
+}
+```
+
+## Common Configuration Options
+
+### Product Information
+
+```javascript
+{
+    Product: 'MyApp',
+    ProductVersion: '1.0.0'
+}
+```
+
+### UUID Configuration
+
+```javascript
+{
+    UUID: {
+        DataCenter: 1,  // 0-31
+        Worker: 5       // 0-31
+    }
+}
+```
+
+### Logging Configuration
+
+```javascript
+{
+    LogStreams: [
+        { level: 'info' },
+        { level: 'error', path: '/var/log/app/error.log' }
+    ]
+}
+```
+
+### REST Client Configuration
+
+```javascript
+{
+    RestClientURLPrefix: 'https://api.example.com/v1'
+}
+```
+
+## Best Practices
+
+1. **Don't hardcode secrets**: Use environment variables
+2. **Use typed configuration**: Define interfaces for your config shape
+3. **Provide sensible defaults**: Make configuration optional where possible
+4. **Document your settings**: List all configuration options
+5. **Validate on startup**: Check for required settings early
+
+```javascript
+// Validation example
+const fable = new Fable(config);
+
+if (!fable.settings.Database?.Host) {
+    throw new Error('Database.Host is required');
+}
+```
+
+## 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);
+```
+
+## Runtime Configuration Updates
+
+While generally not recommended, settings can be modified at runtime:
+
+```javascript
+// Not recommended, but possible
+fable.settings.MyFeature.Enabled = true;
+
+// Better: Use a service for dynamic configuration
+```

package/docs/services/template.md

@@ -0,0 +1,233 @@
+# Template Service
+
+The Template service provides underscore/lodash-style template compilation and rendering. It compiles string templates into reusable functions.
+
+## Access
+
+```javascript
+// On-demand service - instantiate when needed
+const template = fable.instantiateServiceProvider('Template');
+
+// Or use the Utility service shorthand
+const renderFn = fable.Utility.template('Hello, <%= name %>!');
+```
+
+## Template Syntax
+
+### Interpolation (`<%= %>`)
+
+Output a value:
+
+```javascript
+const template = fable.instantiateServiceProvider('Template');
+const render = template.buildTemplateFunction('Hello, <%= name %>!');
+
+render({ name: 'World' });  // Returns 'Hello, World!'
+```
+
+### Evaluation (`<% %>`)
+
+Execute JavaScript code:
+
+```javascript
+const render = template.buildTemplateFunction(`
+    <% for (var i = 0; i < items.length; i++) { %>
+        Item: <%= items[i] %>
+    <% } %>
+`);
+
+render({ items: ['Apple', 'Banana', 'Cherry'] });
+```
+
+## Basic Usage
+
+### Create and Use Template
+
+```javascript
+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!'
+```
+
+### Immediate Rendering
+
+Pass data as the second argument to render immediately:
+
+```javascript
+const result = template.buildTemplateFunction('Sum: <%= a + b %>', { a: 5, b: 3 });
+// Returns 'Sum: 8'
+```
+
+## Using the Utility Shorthand
+
+The Utility service provides a convenient wrapper:
+
+```javascript
+// Create a template function
+const greet = fable.Utility.template('Hello, <%= name %>!');
+greet({ name: 'World' });
+
+// Or render immediately
+fable.Utility.template('Hello, <%= name %>!', { name: 'World' });
+```
+
+### Hashed Templates
+
+Register templates for reuse by name:
+
+```javascript
+// Register a template
+fable.Utility.buildHashedTemplate('user-card', `
+    <div class="card">
+        <h2><%= user.name %></h2>
+        <p><%= user.email %></p>
+    </div>
+`);
+
+// Use the registered template
+fable.Utility.templates['user-card']({ user: { name: 'John', email: 'john@example.com' } });
+```
+
+## Examples
+
+### HTML Generation
+
+```javascript
+const cardTemplate = template.buildTemplateFunction(`
+    <div class="card">
+        <h2><%= title %></h2>
+        <p><%= description %></p>
+        <% if (showButton) { %>
+            <button><%= buttonText %></button>
+        <% } %>
+    </div>
+`);
+
+cardTemplate({
+    title: 'Welcome',
+    description: 'This is a card component',
+    showButton: true,
+    buttonText: 'Click Me'
+});
+```
+
+### Lists and Loops
+
+```javascript
+const listTemplate = template.buildTemplateFunction(`
+    <ul>
+        <% for (var i = 0; i < items.length; i++) { %>
+            <li><%= items[i].name %>: $<%= items[i].price %></li>
+        <% } %>
+    </ul>
+`);
+
+listTemplate({
+    items: [
+        { name: 'Apple', price: 1.50 },
+        { name: 'Banana', price: 0.75 }
+    ]
+});
+```
+
+### Conditional Content
+
+```javascript
+const statusTemplate = template.buildTemplateFunction(`
+    <% if (status === 'active') { %>
+        <span class="badge-green">Active</span>
+    <% } else if (status === 'pending') { %>
+        <span class="badge-yellow">Pending</span>
+    <% } else { %>
+        <span class="badge-red">Inactive</span>
+    <% } %>
+`);
+
+statusTemplate({ status: 'active' });
+```
+
+### Nested Data
+
+```javascript
+const profileTemplate = template.buildTemplateFunction(`
+    <div class="profile">
+        <h1><%= user.name %></h1>
+        <p>Email: <%= user.contact.email %></p>
+        <p>Phone: <%= user.contact.phone %></p>
+        <h3>Addresses:</h3>
+        <% for (var i = 0; i < user.addresses.length; i++) { %>
+            <p><%= user.addresses[i].street %>, <%= user.addresses[i].city %></p>
+        <% } %>
+    </div>
+`);
+
+profileTemplate({
+    user: {
+        name: 'John Doe',
+        contact: {
+            email: 'john@example.com',
+            phone: '555-1234'
+        },
+        addresses: [
+            { street: '123 Main St', city: 'Anytown' },
+            { street: '456 Oak Ave', city: 'Other City' }
+        ]
+    }
+});
+```
+
+### Print Function
+
+Use `print()` for inline output:
+
+```javascript
+const template = template.buildTemplateFunction(`
+    <% print('Hello'); print(' '); print('World'); %>
+`);
+
+template({});  // Returns 'Hello World'
+```
+
+## Template Source Access
+
+After building a template, you can access the generated source:
+
+```javascript
+const tpl = fable.instantiateServiceProvider('Template');
+tpl.buildTemplateFunction('Hello, <%= name %>!');
+
+// Access the generated function source
+console.log(tpl.TemplateSource);
+console.log(tpl.TemplateSourceCompiled);
+```
+
+## Escape Handling
+
+The template engine handles these escape sequences:
+
+- `\\` - Backslash
+- `'` - Single quote
+- `\r` - Carriage return
+- `\n` - Newline
+- `\t` - Tab
+- `\u2028` - Line separator
+- `\u2029` - Paragraph separator
+
+## Notes
+
+- This implementation is compatible with underscore/lodash template syntax
+- Does NOT implement underscore's escape expressions (`<%- %>`)
+- Does NOT implement automatic browser variable assignment
+- Templates are compiled to JavaScript functions for performance
+- URL-encoded content in templates is automatically decoded
+
+## Performance Tips
+
+1. **Compile once, use many times**: Store template functions and reuse them
+2. **Use hashed templates**: For frequently used templates, register them with `buildHashedTemplate`
+3. **Avoid complex logic**: Keep template logic simple; move complex operations to the data preparation phase