Fix monty-js readme (#92)

Author: petyosi

CLAUDE.md

@@ -382,17 +382,30 @@ The JavaScript package provides Node.js bindings for the Monty interpreter via n
 
 ### Current API
 
-The package currently exposes a single function:
+The package exposes:
+
+- `Monty` class - Parse and execute Python code with inputs, external functions, and resource limits
+- `MontySnapshot` / `MontyComplete` - For iterative execution with `start()` / `resume()`
+- `runMontyAsync()` - Helper for async external functions
+- `MontySyntaxError` / `MontyRuntimeError` / `MontyTypingError` - Error classes
 
 ```ts
-function run(code: string): RunResult
+import { Monty, MontySnapshot, runMontyAsync } from '@pydantic/monty'
+
+// Basic execution
+const m = new Monty('x + 1', { inputs: ['x'] })
+const result = m.run({ inputs: { x: 10 } }) // returns 11
 
-interface RunResult {
-  output: string  // Captured print() output
-  result: string  // Debug representation of final value
+// Iterative execution for external functions
+const m2 = new Monty('fetch(url)', { inputs: ['url'], externalFunctions: ['fetch'] })
+let progress = m2.start({ inputs: { url: 'https://...' } })
+if (progress instanceof MontySnapshot) {
+  progress = progress.resume({ returnValue: 'response data' })
 }
 ```
 
+See `crates/monty-js/README.md` for full API documentation.
+
 ### Building and Testing
 
 ```bash
@@ -428,14 +441,4 @@ npm test
 
 - Tests use [ava](https://github.com/avajs/ava) and live in `crates/monty-js/__test__/`
 - Tests are written in TypeScript
-- Follow the existing test style in `index.spec.ts`
-
-### Future Work
-
-The JS bindings currently only expose a simple `run()` function. Future work may expose:
-- Input variables
-- Resource limits
-- External functions
-- Snapshot/resume (iterative execution)
-
-These features mirror the Python package API and are implemented in the Rust core.
+- Follow the existing test style in the `__test__/` directory

crates/monty-js/README.md

@@ -1,35 +1,210 @@
 # @pydantic/monty
 
-JavaScript bindings for the Monty sandboxed Python interpreter.
+JavaScript/TypeScript bindings for the Monty sandboxed Python interpreter.
 
 ## Installation
 
 ```bash
 npm install @pydantic/monty
 ```
 
-## Usage (CommonJS)
+## Basic Usage
 
-```js
-const monty = require('@pydantic/monty')
+```ts
+import { Monty } from '@pydantic/monty'
+
+// Create interpreter and run code
+const m = new Monty('1 + 2')
+const result = m.run() // returns 3
+```
+
+## Input Variables
+
+```ts
+const m = new Monty('x + y', { inputs: ['x', 'y'] })
+const result = m.run({ inputs: { x: 10, y: 20 } }) // returns 30
+```
 
-const { output, result } = monty.run('print("hello")\n1 + 2')
-console.log(output) // "hello\n"
-console.log(result) // debug representation of the final value
+## External Functions
+
+For synchronous external functions, pass them directly to `run()`:
+
+```ts
+const m = new Monty('add(2, 3)', { externalFunctions: ['add'] })
+
+const result = m.run({
+  externalFunctions: {
+    add: (a: number, b: number) => a + b,
+  },
+}) // returns 5
 ```
 
-## Usage (ESM / TypeScript)
+For async external functions, use `runMontyAsync()`:
 
 ```ts
-import monty from '@pydantic/monty'
+import { Monty, runMontyAsync } from '@pydantic/monty'
 
-const res = monty.run('print("hi")\n3 * 7')
-console.log(res.output)
-console.log(res.result)
+const m = new Monty('fetch_data(url)', {
+  inputs: ['url'],
+  externalFunctions: ['fetch_data'],
+})
+
+const result = await runMontyAsync(m, {
+  inputs: { url: 'https://example.com' },
+  externalFunctions: {
+    fetch_data: async (url: string) => {
+      const response = await fetch(url)
+      return response.text()
+    },
+  },
+})
 ```
 
-## API
+## Iterative Execution
+
+For fine-grained control over external function calls, use `start()` and `resume()`:
+
+```ts
+const m = new Monty('a() + b()', { externalFunctions: ['a', 'b'] })
+
+let progress = m.start()
+while (progress instanceof MontySnapshot) {
+  console.log(`Calling: ${progress.functionName}`)
+  console.log(`Args: ${progress.args}`)
+  // Provide the return value and resume
+  progress = progress.resume({ returnValue: 10 })
+}
+// progress is now MontyComplete
+console.log(progress.output) // 20
+```
+
+## Error Handling
+
+```ts
+import { Monty, MontySyntaxError, MontyRuntimeError, MontyTypingError } from '@pydantic/monty'
+
+try {
+  const m = new Monty('1 / 0')
+  m.run()
+} catch (error) {
+  if (error instanceof MontySyntaxError) {
+    console.log('Syntax error:', error.message)
+  } else if (error instanceof MontyRuntimeError) {
+    console.log('Runtime error:', error.message)
+    console.log('Traceback:', error.traceback())
+  } else if (error instanceof MontyTypingError) {
+    console.log('Type error:', error.displayDiagnostics())
+  }
+}
+```
+
+## Type Checking
+
+```ts
+const m = new Monty('"hello" + 1')
+try {
+  m.typeCheck()
+} catch (error) {
+  if (error instanceof MontyTypingError) {
+    console.log(error.displayDiagnostics('concise'))
+  }
+}
+
+// Or enable during construction
+const m2 = new Monty('1 + 1', { typeCheck: true })
+```
+
+## Resource Limits
+
+```ts
+const m = new Monty('1 + 1')
+const result = m.run({
+  limits: {
+    maxAllocations: 10000,
+    maxDurationSecs: 5,
+    maxMemory: 1024 * 1024, // 1MB
+    maxRecursionDepth: 100,
+  },
+})
+```
+
+## Serialization
+
+```ts
+// Save parsed code to avoid re-parsing
+const m = new Monty('complex_code()')
+const data = m.dump()
+
+// Later, restore without re-parsing
+const m2 = Monty.load(data)
+const result = m2.run()
+
+// Snapshots can also be serialized
+const snapshot = m.start()
+if (snapshot instanceof MontySnapshot) {
+  const snapshotData = snapshot.dump()
+  // Later, restore and resume
+  const restored = MontySnapshot.load(snapshotData)
+  const result = restored.resume({ returnValue: 42 })
+}
+```
+
+## API Reference
+
+### `Monty` Class
+
+- `constructor(code: string, options?: MontyOptions)` - Parse Python code
+- `run(options?: RunOptions)` - Execute and return the result
+- `start(options?: StartOptions)` - Start iterative execution
+- `typeCheck(prefixCode?: string)` - Perform static type checking
+- `dump()` - Serialize to binary format
+- `Monty.load(data)` - Deserialize from binary format
+- `scriptName` - The script name (default: `'main.py'`)
+- `inputs` - Declared input variable names
+- `externalFunctions` - Declared external function names
+
+### `MontyOptions`
+
+- `scriptName?: string` - Name used in tracebacks (default: `'main.py'`)
+- `inputs?: string[]` - Input variable names
+- `externalFunctions?: string[]` - External function names
+- `typeCheck?: boolean` - Enable type checking on construction
+- `typeCheckPrefixCode?: string` - Code to prepend for type checking
+
+### `RunOptions`
+
+- `inputs?: object` - Input variable values
+- `limits?: ResourceLimits` - Resource limits
+- `externalFunctions?: object` - External function callbacks
+
+### `ResourceLimits`
+
+- `maxAllocations?: number` - Maximum heap allocations
+- `maxDurationSecs?: number` - Maximum execution time in seconds
+- `maxMemory?: number` - Maximum heap memory in bytes
+- `gcInterval?: number` - Run GC every N allocations
+- `maxRecursionDepth?: number` - Maximum call stack depth (default: 1000)
+
+### `MontySnapshot` Class
+
+Returned by `start()` when execution pauses at an external function call.
+
+- `scriptName` - The script being executed
+- `functionName` - The external function being called
+- `args` - Positional arguments
+- `kwargs` - Keyword arguments
+- `resume(options: ResumeOptions)` - Resume with return value or exception
+- `dump()` / `MontySnapshot.load(data)` - Serialization
+
+### `MontyComplete` Class
+
+Returned by `start()` or `resume()` when execution completes.
+
+- `output` - The final result value
+
+### Error Classes
 
-- `run(code: string): { output: string, result: string }` — execute Python code
-  in a sandboxed Monty VM. `output` contains captured `print()` output; `result`
-  is the debug (`{:?}`) representation of the last expression's value.
+- `MontyError` - Base class for all Monty errors
+- `MontySyntaxError` - Syntax/parsing errors
+- `MontyRuntimeError` - Runtime exceptions (with `traceback()`)
+- `MontyTypingError` - Type checking errors (with `displayDiagnostics()`)