examples: persistent REPL (Repl API); use persistent REPL in examples/js; add tests and docs

Author: ssrlive

README.md

@@ -96,7 +96,7 @@ The crate provides an example CLI binary with REPL support:
 ```bash
 cargo run --example js -- -e "console.log('Hello World!')"
 cargo run --example js script.js
-cargo run --example js  # no args -> enter a quick REPL (non-persistent environment)
+cargo run --example js  # no args -> enter persistent REPL (state is retained across inputs)
 ```
 
 ## API Reference

examples/js.rs

@@ -36,7 +36,9 @@ fn main() {
         // No script argument -> start simple REPL (non-persistent environment per-line)
         // We intentionally use evaluate_script (safe API) which builds a fresh env per execution.
         use std::io::{self, Write};
-        println!("JavaScript REPL (quick, non-persistent). Type 'exit' or Ctrl-D to quit.");
+        println!("JavaScript REPL (persistent environment). Type 'exit' or Ctrl-D to quit.");
+        // persistent environment so definitions persist across inputs
+        let repl = javascript::Repl::new();
         loop {
             print!("js> ");
             let _ = io::stdout().flush();
@@ -55,7 +57,7 @@ fn main() {
                     if line.is_empty() {
                         continue;
                     }
-                    match javascript::evaluate_script(line) {
+                    match repl.eval(line) {
                         Ok(result) => print_eval_result(&result),
                         Err(e) => eprintln!("Error: {:?}", e),
                     }

src/core.rs

@@ -1021,6 +1021,100 @@ pub fn evaluate_script<T: AsRef<str>>(script: T) -> Result<Value, JSError> {
     }
 }
 
+/// A small persistent REPL environment wrapper.
+///
+/// Notes:
+/// - `Repl::new()` creates a persistent environment and initializes built-ins.
+/// - `Repl::eval(&self, code)` evaluates the provided code in the persistent env
+///   so variables, functions and imports persist between calls.
+pub struct Repl {
+    env: JSObjectDataPtr,
+}
+
+impl Default for Repl {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Repl {
+    /// Create a new persistent REPL environment (with built-ins initialized).
+    pub fn new() -> Self {
+        let env: JSObjectDataPtr = Rc::new(RefCell::new(JSObjectData::new()));
+        env.borrow_mut().is_function_scope = true;
+        // Initialize built-in constructors once for the persistent environment
+        initialize_global_constructors(&env);
+        Repl { env }
+    }
+
+    /// Evaluate a script in the persistent environment.
+    /// Returns the evaluation result or an error.
+    pub fn eval<T: AsRef<str>>(&self, script: T) -> Result<Value, JSError> {
+        let script = script.as_ref();
+        let filtered = filter_input_script(script);
+
+        // Parse tokens and statements
+        let mut tokens = tokenize(&filtered)?;
+        let statements = parse_statements(&mut tokens)?;
+
+        // Inject simple host `std` / `os` shims when importing with the pattern:
+        //   import * as NAME from "std";
+        for line in script.lines() {
+            let l = line.trim();
+            if l.starts_with("import * as")
+                && l.contains("from")
+                && let (Some(as_idx), Some(from_idx)) = (l.find("as"), l.find("from"))
+            {
+                let name_part = &l[as_idx + 2..from_idx].trim();
+                let name = PropertyKey::String(name_part.trim().to_string());
+                if let Some(start_quote) = l[from_idx..].find(|c: char| ['"', '\''].contains(&c)) {
+                    let quote_char = l[from_idx + start_quote..].chars().next().unwrap();
+                    let rest = &l[from_idx + start_quote + 1..];
+                    if let Some(end_quote) = rest.find(quote_char) {
+                        let module = &rest[..end_quote];
+                        if module == "std" {
+                            obj_set_value(&self.env, &name, Value::Object(crate::js_std::make_std_object()?))?;
+                        } else if module == "os" {
+                            obj_set_value(&self.env, &name, Value::Object(crate::js_os::make_os_object()?))?;
+                        }
+                    }
+                }
+            }
+        }
+
+        match evaluate_statements(&self.env, &statements) {
+            Ok(v) => {
+                // If the result is a Promise object (wrapped in Object with __promise property), wait for it to resolve
+                if let Value::Object(obj) = &v
+                    && let Some(promise_val_rc) = obj_get_value(obj, &"__promise".into())?
+                    && let Value::Promise(promise) = &*promise_val_rc.borrow()
+                {
+                    // Run the event loop until the promise is resolved
+                    loop {
+                        run_event_loop()?;
+                        let promise_borrow = promise.borrow();
+                        match &promise_borrow.state {
+                            PromiseState::Fulfilled(val) => return Ok(val.clone()),
+                            PromiseState::Rejected(reason) => {
+                                return Err(JSError::EvaluationError {
+                                    message: format!("Promise rejected: {}", value_to_string(reason)),
+                                });
+                            }
+                            PromiseState::Pending => {
+                                // Continue running the event loop
+                            }
+                        }
+                    }
+                }
+                // Run event loop once to process any queued asynchronous tasks
+                run_event_loop()?;
+                Ok(v)
+            }
+            Err(e) => Err(e),
+        }
+    }
+}
+
 pub fn parse_statements(tokens: &mut Vec<Token>) -> Result<Vec<Statement>, JSError> {
     let mut statements = Vec::new();
     while !tokens.is_empty() && !matches!(tokens[0], Token::RBrace) {

src/lib.rs

@@ -25,8 +25,8 @@ pub(crate) mod tmpfile;
 
 pub use core::{
     JS_DefinePropertyValue, JS_DupValue, JS_Eval, JS_FreeContext, JS_FreeRuntime, JS_FreeValue, JS_GetProperty, JS_NewContext,
-    JS_NewObject, JS_NewRuntime, JS_NewString, JS_SetProperty, JSClassDef, JSObject, JSStackFrame, JSString, JSValue, PropertyKey, Value,
-    evaluate_script, get_prop_env, obj_get_value, tokenize,
+    JS_NewObject, JS_NewRuntime, JS_NewString, JS_SetProperty, JSClassDef, JSObject, JSStackFrame, JSString, JSValue, PropertyKey, Repl,
+    Value, evaluate_script, get_prop_env, obj_get_value, tokenize,
 };
 pub use core::{
     JS_FLOAT64_NAN, JS_GC_OBJ_TYPE_ASYNC_FUNCTION, JS_GC_OBJ_TYPE_FUNCTION_BYTECODE, JS_GC_OBJ_TYPE_JS_CONTEXT, JS_GC_OBJ_TYPE_JS_OBJECT,

tests/repl_tests.rs

@@ -0,0 +1,27 @@
+use javascript::Repl;
+// use javascript::evaluate_script; // Commenting out unused import
+
+#[test]
+fn repl_persists_values_between_calls() {
+    let repl = Repl::new();
+    // define x
+    let r1 = repl.eval("let x = 42;");
+    assert!(r1.is_ok());
+    // now retrieve
+    let r2 = repl.eval("x");
+    match r2 {
+        Ok(javascript::Value::Number(n)) => assert_eq!(n, 42.0),
+        other => panic!("Expected number 42 from repl, got {:?}", other),
+    }
+}
+
+#[test]
+fn repl_allows_function_persistence() {
+    let repl = Repl::new();
+    let _ = repl.eval("function add(a,b){ return a + b; }");
+    let r = repl.eval("add(2,3)");
+    match r {
+        Ok(javascript::Value::Number(n)) => assert_eq!(n, 5.0),
+        other => panic!("Expected number 5 from repl, got {:?}", other),
+    }
+}