@pydantic/monty 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @pydantic/monty
 
-JavaScript bindings for the Monty sandboxed Python interpreter.
+JavaScript/TypeScript bindings for the Monty sandboxed Python interpreter.
 
 ## Installation
 
@@ -8,28 +8,203 @@ JavaScript bindings for the Monty sandboxed Python interpreter.
 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()`)

package/index.d.ts

@@ -1,26 +1,311 @@
-/* auto-generated by NAPI-RS */
-/* eslint-disable */
+// index-header.d.ts - header will be written into index.d.ts on build
+
+type JsMontyObject = any
 /**
- * Runs Python code and returns the result as a string.
+ * A sandboxed Python interpreter instance.
  *
- * The code is executed in a sandboxed environment with no resource limits.
- * Print statements are captured and returned along with the final result.
+ * Parses and compiles Python code on initialization, then can be run
+ * multiple times with different input values. This separates the parsing
+ * cost from execution, making repeated runs more efficient.
+ */
+export declare class Monty {
+  /**
+   * Creates a new Monty interpreter by parsing the given code.
+   *
+   * Returns either a Monty instance, a MontyException (for syntax errors), or a MontyTypingError.
+   * The wrapper should check the result type and throw the appropriate error.
+   *
+   * @param code - Python code to execute
+   * @param options - Configuration options
+   * @returns Monty instance on success, or error object on failure
+   */
+  static create(code: string, options?: MontyOptions | undefined | null): Self | MontyException | MontyTypingError
+  /**
+   * Performs static type checking on the code.
+   *
+   * Returns either nothing (success) or a MontyTypingError.
+   *
+   * @param prefixCode - Optional code to prepend before type checking
+   * @returns null on success, or MontyTypingError on failure
+   */
+  typeCheck(prefixCode?: string | undefined | null): MontyTypingError | null
+  /**
+   * Executes the code and returns the result, or an exception object if execution fails.
+   *
+   * @param options - Execution options (inputs, limits, externalFunctions)
+   * @returns The result of the last expression, or a MontyException if execution fails
+   */
+  run(options?: RunOptions | undefined | null): JsMontyObject | MontyException
+  /**
+   * Starts execution and returns either a snapshot (paused at external call), completion, or error.
+   *
+   * This method enables iterative execution where code pauses at external function
+   * calls, allowing the host to provide return values or exceptions before resuming.
+   *
+   * @param options - Execution options (inputs, limits)
+   * @returns MontySnapshot if paused, MontyComplete if done, or MontyException if failed
+   */
+  start(options?: StartOptions | undefined | null): MontySnapshot | MontyComplete | MontyException
+  /**
+   * Serializes the Monty instance to a binary format.
+   *
+   * The serialized data can be stored and later restored with `Monty.load()`.
+   * This allows caching parsed code to avoid re-parsing on subsequent runs.
+   *
+   * @returns Buffer containing the serialized Monty instance
+   */
+  dump(): Buffer
+  /**
+   * Deserializes a Monty instance from binary format.
+   *
+   * @param data - The serialized Monty data from `dump()`
+   * @returns A new Monty instance
+   */
+  static load(data: Buffer): Monty
+  /** Returns the script name. */
+  get scriptName(): string
+  /** Returns the input variable names. */
+  get inputs(): Array<string>
+  /** Returns the external function names. */
+  get externalFunctions(): Array<string>
+  /** Returns a string representation of the Monty instance. */
+  repr(): string
+}
+
+/**
+ * Represents completed execution with a final output value.
  *
- * # Arguments
- * * `code` - The Python code to execute
+ * The output value is stored as a `MontyObject` internally and converted to JS on access.
+ */
+export declare class MontyComplete {
+  /** Returns the final output value from the executed code. */
+  get output(): JsMontyObject
+  /** Returns a string representation of the MontyComplete. */
+  repr(): string
+}
+
+/**
+ * Wrapper around core `MontyException` for napi bindings.
  *
- * # Returns
- * A `RunResult` containing the printed output and the result of the last expression.
+ * This is a thin newtype wrapper that exposes the necessary getters for the
+ * JavaScript wrapper to construct appropriate error types (`MontySyntaxError`
+ * or `MontyRuntimeError`) based on the exception type.
+ */
+export declare class MontyException {
+  /**
+   * Returns information about the inner Python exception.
+   *
+   * The `typeName` field can be used to distinguish syntax errors (`"SyntaxError"`)
+   * from runtime errors (e.g., `"ValueError"`, `"TypeError"`).
+   */
+  get exception(): ExceptionInfo
+  /** Returns the error message. */
+  get message(): string
+  /**
+   * Returns the Monty traceback as an array of Frame objects.
+   *
+   * For syntax errors, this will be an empty array.
+   * For runtime errors, this contains the stack frames where the error occurred.
+   */
+  traceback(): Array<Frame>
+  /**
+   * Returns formatted exception string.
+   *
+   * @param format - Output format:
+   *   - 'traceback' - Full traceback (default)
+   *   - 'type-msg' - 'ExceptionType: message' format
+   *   - 'msg' - just the message
+   */
+  display(format?: string | undefined | null): string
+  /** Returns a string representation of the error. */
+  toString(): string
+}
+export type JsMontyException = MontyException
+
+/**
+ * Represents paused execution waiting for an external function call return value.
+ *
+ * Contains information about the pending external function call and allows
+ * resuming execution with the return value or an exception.
+ */
+export declare class MontySnapshot {
+  /** Returns the name of the script being executed. */
+  get scriptName(): string
+  /** Returns the name of the external function being called. */
+  get functionName(): string
+  /** Returns the positional arguments passed to the external function. */
+  get args(): Array<JsMontyObject>
+  /** Returns the keyword arguments passed to the external function as an object. */
+  get kwargs(): object
+  /**
+   * Resumes execution with either a return value or an exception.
+   *
+   * Exactly one of `returnValue` or `exception` must be provided.
+   *
+   * @param options - Object with either `returnValue` or `exception`
+   * @returns MontySnapshot if paused, MontyComplete if done, or MontyException if failed
+   */
+  resume(options: ResumeOptions): Self | MontyComplete | MontyException
+  /**
+   * Serializes the MontySnapshot to a binary format.
+   *
+   * The serialized data can be stored and later restored with `MontySnapshot.load()`.
+   * This allows suspending execution and resuming later, potentially in a different process.
+   *
+   * @returns Buffer containing the serialized snapshot
+   */
+  dump(): Buffer
+  /**
+   * Deserializes a MontySnapshot from binary format.
+   *
+   * @param data - The serialized snapshot data from `dump()`
+   * @param options - Optional load options (reserved for future use)
+   * @returns A new MontySnapshot instance
+   */
+  static load(data: Buffer, options?: SnapshotLoadOptions | undefined | null): MontySnapshot
+  /** Returns a string representation of the MontySnapshot. */
+  repr(): string
+}
+
+/**
+ * Raised when type checking finds errors in the code.
+ *
+ * This exception is raised when static type analysis detects type errors.
+ * Use `display()` to render diagnostics in various formats.
+ */
+export declare class MontyTypingError {
+  /** Returns information about the inner exception. */
+  get exception(): ExceptionInfo
+  /** Returns the error message. */
+  get message(): string
+  /**
+   * Renders the type error diagnostics with the specified format and color.
+   *
+   * @param format - Output format. One of:
+   *   - 'full' - Full diagnostic output (default)
+   *   - 'concise' - Concise output
+   *   - 'azure' - Azure DevOps format
+   *   - 'json' - JSON format
+   *   - 'jsonlines' - JSON Lines format
+   *   - 'rdjson' - RDJson format
+   *   - 'pylint' - Pylint format
+   *   - 'gitlab' - GitLab CI format
+   *   - 'github' - GitHub Actions format
+   * @param color - Whether to include ANSI color codes. Default: false
+   */
+  display(format?: string | undefined | null, color?: boolean | undefined | null): string
+  /** Returns a string representation of the error. */
+  toString(): string
+}
+
+/**
+ * Information about the inner Python exception.
  *
- * # Errors
- * Returns an error if the code fails to parse or encounters a runtime error.
+ * This provides structured access to the exception type and message
+ * for programmatic error handling.
  */
-export declare function run(code: string): RunResult
+export interface ExceptionInfo {
+  /** The exception type name (e.g., "ValueError", "TypeError", "SyntaxError"). */
+  typeName: string
+  /** The exception message. */
+  message: string
+}
+
+/** Input for raising an exception during resume. */
+export interface ExceptionInput {
+  /** The exception type name (e.g., "ValueError"). */
+  type: string
+  /** The exception message. */
+  message: string
+}
+
+/**
+ * A single frame in a Monty traceback.
+ *
+ * Contains all the information needed to display a traceback line:
+ * the file location, function name, and optional source code preview.
+ */
+export interface Frame {
+  /** The filename where the code is located. */
+  filename: string
+  /** Line number (1-based). */
+  line: number
+  /** Column number (1-based). */
+  column: number
+  /** End line number (1-based). */
+  endLine: number
+  /** End column number (1-based). */
+  endColumn: number
+  /** The name of the function, or null for module-level code. */
+  functionName?: string
+  /** The source code line for preview in the traceback. */
+  sourceLine?: string
+}
+
+/** Options for creating a new Monty instance. */
+export interface MontyOptions {
+  /** Name used in tracebacks and error messages. Default: 'main.py' */
+  scriptName?: string
+  /** List of input variable names available in the code. */
+  inputs?: Array<string>
+  /** List of external function names the code can call. */
+  externalFunctions?: Array<string>
+  /** Whether to perform type checking on the code. Default: false */
+  typeCheck?: boolean
+  /** Optional code to prepend before type checking. */
+  typeCheckPrefixCode?: string
+}
+
+/**
+ * Resource limits configuration from JavaScript.
+ *
+ * All limits are optional. Omit a key to disable that limit.
+ */
+export interface ResourceLimits {
+  /** Maximum number of heap allocations allowed. */
+  maxAllocations?: number
+  /** Maximum execution time in seconds. */
+  maxDurationSecs?: number
+  /** Maximum heap memory in bytes. */
+  maxMemory?: number
+  /** Run garbage collection every N allocations. */
+  gcInterval?: number
+  /** Maximum function call stack depth (default: 1000). */
+  maxRecursionDepth?: number
+}
+
+/** Options for resuming execution. */
+export interface ResumeOptions {
+  /** The value to return from the external function call. */
+  returnValue?: unknown
+  /**
+   * An exception to raise in the interpreter.
+   * Format: { type: string, message: string }
+   */
+  exception?: ExceptionInput
+}
+
+/** Options for running code. */
+export interface RunOptions {
+  inputs?: object
+  /** Resource limits configuration. */
+  limits?: ResourceLimits
+  /**
+   * Dict of external function callbacks.
+   * Keys are function names, values are callable functions.
+   */
+  externalFunctions?: object
+}
+
+/** Options for loading a serialized snapshot. */
+export interface SnapshotLoadOptions {
+
+}
 
-/** Result of running Python code. */
-export interface RunResult {
-  /** Any output from print statements during execution. */
-  output: string
-  /** The debug representation of the final result. */
-  result: string
+/** Options for starting execution. */
+export interface StartOptions {
+  /** Dict of input variable values. */
+  inputs?: object
+  /** Resource limits configuration. */
+  limits?: ResourceLimits
 }