diff options
Diffstat (limited to 'js/scripting-lang/docs/repl/baba-yaga/0.0.1/REPL.html')
| -rw-r--r-- | js/scripting-lang/docs/repl/baba-yaga/0.0.1/REPL.html | 4197 |
1 files changed, 0 insertions, 4197 deletions
diff --git a/js/scripting-lang/docs/repl/baba-yaga/0.0.1/REPL.html b/js/scripting-lang/docs/repl/baba-yaga/0.0.1/REPL.html deleted file mode 100644 index eeafb58..0000000 --- a/js/scripting-lang/docs/repl/baba-yaga/0.0.1/REPL.html +++ /dev/null @@ -1,4197 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> -<head> - <meta charset="utf-8"> - <title>JSDoc: Class: REPL</title> - - <script src="scripts/prettify/prettify.js"> </script> - <script src="scripts/prettify/lang-css.js"> </script> - <!--[if lt IE 9]> - <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script> - <![endif]--> - <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> - <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> -</head> - -<body> - -<div id="main"> - - <h1 class="page-title">Class: REPL</h1> - - - - - - -<section> - -<header> - - <h2><span class="attribs"><span class="type-signature"></span></span>REPL<span class="signature">()</span><span class="type-signature"></span></h2> - - <div class="class-description">Baba Yaga REPL Class - -This class demonstrates integration of the Baba Yaga language -with the functional harness architecture. It serves as both a language -playground and a reference for harness integration patterns. - -## Architecture Principles Demonstrated - -1. **Separation of Concerns**: Script execution vs. side effects -2. **Adapter Pattern**: Pluggable side-effect handlers -3. **State Management**: Versioned state with history and rollback -4. **Command Processing**: Structured communication between pure and impure code - -## Key Methods for Integration Reference - -- `init()`: Harness initialization and setup -- `executeScript()`: Core script execution with harness integration -- `processAdapterCommand()`: Adapter routing and command processing -- `handleInput()`: Input parsing and command routing - -## State Flow - -``` -User Input → handleInput() → executeScript() → harness.update() - ↓ - { model, commands, version } - ↓ - processAdapterCommand() - ↓ - adapter.process(command) -```</div> - - -</header> - -<article> - <div class="container-overview"> - - - - - <h2>Constructor</h2> - - - - <h4 class="name" id="REPL"><span class="type-signature"></span>new REPL<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Initialize the REPL with harness integration - -This constructor sets up the core components needed for both -language playground functionality and harness integration demonstration. - -## Key Components - -### 1. Readline Interface -Handles user input with multi-line support and history management. - -### 2. Harness Instance -The FunctionalHarness that manages script execution and state. - -### 3. Adapter Registry -Side-effect handlers that demonstrate the adapter pattern. - -## Integration Pattern - -This constructor demonstrates how to set up harness integration: - -```javascript -// 1. Create harness instance -this.harness = new FunctionalHarness(scriptPath, config); - -// 2. Define adapters for side effects -this.adapters = { - console: { process: async (command) => { // handle console output } }, - file: { process: async (command) => { // handle file operations } }, - network: { process: async (command) => { // handle HTTP requests } } -}; - -// 3. Initialize state tracking -this.currentState = {}; -this.currentVersion = 0; -``` - -## Adapter Pattern Explanation - -Adapters are the bridge between script execution and side effects. -Each adapter handles a specific type of side effect: - -- **Console Adapter**: Handles output and logging -- **File Adapter**: Handles file system operations -- **Network Adapter**: Handles HTTP requests - -This pattern allows the harness to focus on script execution while -enabling real-world functionality through structured command processing. -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line125">line 125</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - </div> - - - - - - - - - - - - - - - <h3 class="subsection-title">Members</h3> - - - -<h4 class="name" id="adapters"><span class="type-signature"></span>adapters<span class="type-signature"></span></h4> - - - - -<div class="description"> - Adapter Registry - Side Effect Handlers - -This registry demonstrates the adapter pattern, where each adapter -handles a specific type of side effect. This allows the harness -to remain pure while enabling real-world functionality. - -## Adapter Structure - -Each adapter has: -- `name`: Human-readable identifier -- `description`: Purpose and capabilities -- `process(command)`: Async function that handles commands - -## Command Format - -Commands are structured objects with: -- `type`: Usually 'emit' for side effects -- `value`: Action-specific data (e.g., { action: 'http_request', url: '...' }) - -## Integration Example - -```javascript -// Script generates command -..emit { action: 'save_file', filename: 'data.json', data: { x: 1 } }; - -// Harness extracts command -const result = await harness.update({ script: userCode }); -// result.commands = [{ type: 'emit', value: { action: 'save_file', ... } }] - -// REPL routes to appropriate adapter -await this.processAdapterCommand(result.commands[0]); -// Routes to file adapter's process() method -``` -</div> - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line227">line 227</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - <h3 class="subsection-title">Methods</h3> - - - - - - - - <h4 class="name" id="addToHistory"><span class="type-signature"></span>addToHistory<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Add command to history -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2372">line 2372</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="autoFormatScript"><span class="type-signature"></span>autoFormatScript<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Auto-format multi-line script for better readability -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1042">line 1042</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="cleanup"><span class="type-signature">(async) </span>cleanup<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Cleanup on exit -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2405">line 2405</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="clearState"><span class="type-signature"></span>clearState<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Clear current state -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1746">line 1746</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="createBranch"><span class="type-signature">(async) </span>createBranch<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Enhanced branch creation with better feedback -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1988">line 1988</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="displayError"><span class="type-signature"></span>displayError<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Display error -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1386">line 1386</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="displayResult"><span class="type-signature"></span>displayResult<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Display execution result -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1351">line 1351</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="executeMultiLine"><span class="type-signature">(async) </span>executeMultiLine<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Execute multi-line script -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1028">line 1028</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="executeScript"><span class="type-signature">(async) </span>executeScript<span class="signature">(script)</span><span class="type-signature"> → {Promise.<void>}</span></h4> - - - - - - -<div class="description"> - Execute Baba Yaga script using the functional harness - -This method demonstrates harness integration by: -- Initializing the harness on first use (lazy initialization) -- Executing scripts with the current state -- Processing side effects through adapters -- Managing state versioning -- Handling errors gracefully - -## Core Integration Pattern - -This method implements the harness integration flow: - -```javascript -// 1. Lazy harness initialization -if (!this.harness) { - this.harness = new FunctionalHarness(script, config); - await this.harness.initialize(); -} - -// 2. Execute script with current state -const result = await this.harness.update(this.currentState); -// result = { model: newState, commands: [...], version: 1 } - -// 3. Update application state -this.currentState = result.model; -this.currentVersion = result.version; - -// 4. Process side effects through adapters -for (const command of result.commands) { - await this.processAdapterCommand(command); -} - -// 5. Display results to user -this.displayResult(result); -``` - -## Key Design Principles - -### 1. Script Execution -Scripts are executed in a controlled environment managed by the harness. -Side effects are extracted as commands and processed separately. - -### 2. State Management -State is managed with automatic versioning. Each script execution -creates a new version, enabling history tracking and rollback capabilities. - -### 3. Side Effect Isolation -Side effects (I/O, network, etc.) are isolated from script execution -through the command/adapter pattern. - -### 4. Error Handling -Errors are caught and displayed gracefully, with the harness maintaining -its state even when scripts fail. - -## Integration Example - -When integrating the harness into your own application: - -```javascript -class MyApp { - async executeUserScript(script) { - try { - // 1. Initialize harness if needed - if (!this.harness) { - this.harness = new FunctionalHarness(script, config); - await this.harness.initialize(); - } - - // 2. Execute script with current state - const result = await this.harness.update(this.currentState); - - // 3. Update application state - this.currentState = result.model; - this.currentVersion = result.version; - - // 4. Process side effects - for (const command of result.commands) { - await this.processCommand(command); - } - - // 5. Handle results - this.handleResult(result); - - } catch (error) { - this.handleError(error); - } - } -} -``` - -## State Flow - -``` -User Input → executeScript() → harness.update(currentState) - ↓ - { model, commands, version } - ↓ - Update currentState & version - ↓ - Process commands through adapters - ↓ - Display results to user -``` -</div> - - - - - - - - - - <h5>Parameters:</h5> - - -<table class="params"> - <thead> - <tr> - - <th>Name</th> - - - <th>Type</th> - - - - - - <th class="last">Description</th> - </tr> - </thead> - - <tbody> - - - <tr> - - <td class="name"><code>script</code></td> - - - <td class="type"> - - -<span class="param-type">string</span> - - - - </td> - - - - - - <td class="description last">The Baba Yaga script to execute</td> - </tr> - - - </tbody> -</table> - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1162">line 1162</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - -<h5>Returns:</h5> - - -<div class="param-desc"> - - Resolves when script execution is complete -</div> - - - -<dl> - <dt> - Type - </dt> - <dd> - -<span class="param-type">Promise.<void></span> - - - </dd> -</dl> - - - - - - - - - - - - - - <h4 class="name" id="findLastResult"><span class="type-signature"></span>findLastResult<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Find the last result from the model (usually the last defined variable) -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1365">line 1365</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="formatValue"><span class="type-signature"></span>formatValue<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Format value for display -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1399">line 1399</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="getPrompt"><span class="type-signature"></span>getPrompt<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Get current prompt -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line974">line 974</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="handleInput"><span class="type-signature">(async) </span>handleInput<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Handle user input -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line984">line 984</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="init"><span class="type-signature">(async) </span>init<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Initialize the REPL and harness integration - -This method sets up the complete REPL environment, including: -- Display welcome message and feature overview -- Load command history from file -- Set up readline interface for user interaction -- Initialize the harness (deferred until first script execution) - -## Integration Pattern - -This method demonstrates the initialization sequence for a harness-integrated application: - -```javascript -// 1. Display application information -console.log('Welcome to Baba Yaga REPL'); - -// 2. Load persistent state (history, configuration) -await this.loadHistory(); - -// 3. Set up user interface -this.setupReadline(); - -// 4. Harness initialization is deferred until first use -// This improves startup performance and allows for lazy loading -``` - -## Key Design Decisions - -### Lazy Harness Initialization -The harness is not initialized here but deferred until the first script execution. -This improves startup performance and allows the REPL to start even if there are -issues with the harness setup. - -### History Management -Command history is loaded from a persistent file, demonstrating how to maintain -user state across sessions. - -### User Interface Setup -The readline interface is configured with custom prompts and event handlers, -showing how to create an interactive command-line interface. - -## Usage in Integration - -When integrating the harness into your own application, follow this pattern: - -```javascript -class MyApp { - async init() { - // 1. Set up your application UI/interface - this.setupInterface(); - - // 2. Load any persistent state - await this.loadState(); - - // 3. Set up harness (or defer until needed) - this.harness = new FunctionalHarness(scriptPath, config); - - // 4. Start your application - this.start(); - } -} -``` -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line925">line 925</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="loadExample"><span class="type-signature">(async) </span>loadExample<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Load an example -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1654">line 1654</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="loadHistory"><span class="type-signature">(async) </span>loadHistory<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Load history from file -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2382">line 2382</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="loadState"><span class="type-signature">(async) </span>loadState<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Load state from file -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1773">line 1773</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="menuCompareVersions"><span class="type-signature">(async) </span>menuCompareVersions<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Menu option: Compare versions -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2303">line 2303</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="menuCreateBranch"><span class="type-signature">(async) </span>menuCreateBranch<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Menu option: Create branch -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2268">line 2268</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="menuRollbackToVersion"><span class="type-signature">(async) </span>menuRollbackToVersion<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Menu option: Rollback to version -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2232">line 2232</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="menuShowCurrentState"><span class="type-signature">(async) </span>menuShowCurrentState<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Menu option: Show current state -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2363">line 2363</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="menuViewVersionDetails"><span class="type-signature">(async) </span>menuViewVersionDetails<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Menu option: View version details -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2185">line 2185</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="processAdapterCommand"><span class="type-signature">(async) </span>processAdapterCommand<span class="signature">(command)</span><span class="type-signature"> → {Promise.<void>}</span></h4> - - - - - - -<div class="description"> - Process commands through the adapter registry - -This method demonstrates the adapter pattern by routing commands -from script execution to side-effect handlers (adapters). - -## Adapter Pattern Implementation - -The adapter pattern allows the harness to focus on script execution while -enabling side effects through structured command processing: - -```javascript -// Script generates command -..emit { action: 'save_file', filename: 'data.json', data: { x: 1 } }; - -// Harness extracts command -const result = await harness.update(currentState); -// result.commands = [{ type: 'emit', value: { action: 'save_file', ... } }] - -// REPL routes to appropriate adapter -await this.processAdapterCommand(result.commands[0]); -// Routes to file adapter's process() method -``` - -## Command Routing Strategy - -This implementation uses a "broadcast" strategy where each command is -sent to all adapters. Each adapter decides whether to handle the command -based on its content: - -```javascript -// Each adapter checks if it should handle the command -if (command.type === 'emit' && command.value.action === 'save_file') { - // File adapter handles this command - await fs.writeFile(command.value.filename, JSON.stringify(command.value.data)); -} - -if (command.type === 'emit' && command.value.action === 'http_request') { - // Network adapter handles this command - const response = await fetch(command.value.url, options); -} -``` - -## Command Structure - -Commands are structured objects with: -- `type`: Usually 'emit' for side effects -- `value`: Action-specific data (e.g., { action: 'http_request', url: '...' }) - -## Error Handling - -Each adapter processes commands independently. If one adapter fails, -others continue processing. This provides error isolation. - -## Integration Example - -When implementing adapters in your own application: - -```javascript -class MyApp { - constructor() { - this.adapters = { - database: { - name: 'Database Adapter', - process: async (command) => { - if (command.type === 'emit' && command.value.action === 'save_record') { - await this.db.save(command.value.table, command.value.data); - } - } - }, - email: { - name: 'Email Adapter', - process: async (command) => { - if (command.type === 'emit' && command.value.action === 'send_email') { - await this.emailService.send(command.value.to, command.value.subject); - } - } - } - }; - } - - async processCommand(command) { - for (const [name, adapter] of Object.entries(this.adapters)) { - try { - await adapter.process(command); - } catch (error) { - console.error(`[${adapter.name}] Error:`, error.message); - } - } - } -} -``` - -## Alternative Routing Strategies - -Instead of broadcasting to all adapters, you could implement: - -### 1. Action-Based Routing -```javascript -const action = command.value?.action; -const adapter = this.adapters[action]; -if (adapter) { - await adapter.process(command); -} -``` - -### 2. Type-Based Routing -```javascript -const type = command.type; -const adapter = this.adapters[type]; -if (adapter) { - await adapter.process(command); -} -``` - -### 3. Priority-Based Routing -```javascript -const adapters = Object.values(this.adapters).sort((a, b) => b.priority - a.priority); -for (const adapter of adapters) { - if (await adapter.canHandle(command)) { - await adapter.process(command); - break; // Stop after first handler - } -} -``` -</div> - - - - - - - - - - <h5>Parameters:</h5> - - -<table class="params"> - <thead> - <tr> - - <th>Name</th> - - - <th>Type</th> - - - - - - <th class="last">Description</th> - </tr> - </thead> - - <tbody> - - - <tr> - - <td class="name"><code>command</code></td> - - - <td class="type"> - - -<span class="param-type">Object</span> - - - - </td> - - - - - - <td class="description last">The command object from harness execution - <h6>Properties</h6> - - -<table class="params"> - <thead> - <tr> - - <th>Name</th> - - - <th>Type</th> - - - - - - <th class="last">Description</th> - </tr> - </thead> - - <tbody> - - - <tr> - - <td class="name"><code>type</code></td> - - - <td class="type"> - - -<span class="param-type">string</span> - - - - </td> - - - - - - <td class="description last">Command type (usually 'emit')</td> - </tr> - - - - <tr> - - <td class="name"><code>value</code></td> - - - <td class="type"> - - -<span class="param-type">Object</span> - - - - </td> - - - - - - <td class="description last">Action-specific data</td> - </tr> - - - </tbody> -</table> - - </td> - </tr> - - - </tbody> -</table> - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1337">line 1337</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - -<h5>Returns:</h5> - - -<div class="param-desc"> - - Resolves when all adapters have processed the command -</div> - - - -<dl> - <dt> - Type - </dt> - <dd> - -<span class="param-type">Promise.<void></span> - - - </dd> -</dl> - - - - - - - - - - - - - - <h4 class="name" id="processCommand"><span class="type-signature">(async) </span>processCommand<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Process REPL commands -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1433">line 1433</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="replayFromVersion"><span class="type-signature">(async) </span>replayFromVersion<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Replay from a specific version with new state -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1926">line 1926</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="rollbackToVersion"><span class="type-signature">(async) </span>rollbackToVersion<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Rollback to version -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1712">line 1712</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="runScriptFile"><span class="type-signature">(async) </span>runScriptFile<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Run script from file -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1789">line 1789</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="saveHistory"><span class="type-signature">(async) </span>saveHistory<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Save history to file -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2394">line 2394</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="saveState"><span class="type-signature">(async) </span>saveState<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Save state to file -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1756">line 1756</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="setupReadline"><span class="type-signature"></span>setupReadline<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Set up readline interface -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line957">line 957</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="showAdapters"><span class="type-signature"></span>showAdapters<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Show available adapters -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1735">line 1735</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="showExamples"><span class="type-signature"></span>showExamples<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Show available examples -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1641">line 1641</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="showHelp"><span class="type-signature"></span>showHelp<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Show help information -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1522">line 1522</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="showHistory"><span class="type-signature"></span>showHistory<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Show version history -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1687">line 1687</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="showInteractiveMenu"><span class="type-signature">(async) </span>showInteractiveMenu<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Show interactive menu for navigating history and branches -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line2015">line 2015</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="showState"><span class="type-signature"></span>showState<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Show current state -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1674">line 1674</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="showStateDiff"><span class="type-signature"></span>showStateDiff<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Show state diff between versions -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1874">line 1874</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - <h4 class="name" id="simulateErrorRecovery"><span class="type-signature">(async) </span>simulateErrorRecovery<span class="signature">()</span><span class="type-signature"></span></h4> - - - - - - -<div class="description"> - Simulate error recovery scenarios -</div> - - - - - - - - - - - - - -<dl class="details"> - - - - - - - - - - - - - - - - - - - - - - - - - - - <dt class="tag-source">Source:</dt> - <dd class="tag-source"><ul class="dummy"><li> - <a href="repl.js.html">repl.js</a>, <a href="repl.js.html#line1946">line 1946</a> - </li></ul></dd> - - - - - - - -</dl> - - - - - - - - - - - - - - - - - - - - - - - - - - -</article> - -</section> - - - - -</div> - -<nav> - <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="REPL.html">REPL</a></li></ul> -</nav> - -<br class="clear"> - -<footer> - Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.4</a> on Tue Jul 29 2025 14:41:59 GMT-0400 (Eastern Daylight Time) -</footer> - -<script> prettyPrint(); </script> -<script src="scripts/linenumber.js"> </script> -</body> -</html> \ No newline at end of file |