@pydantic/monty 0.0.1

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@pydantic/monty",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Sandboxed Python interpreter for JavaScript/TypeScript",
+  "main": "wrapper.js",
+  "types": "wrapper.d.ts",
+  "exports": {
+    ".": {
+      "types": "./wrapper.d.ts",
+      "default": "./wrapper.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "github.com/pydantic/monty"
+  },
+  "license": "MIT",
+  "browser": "browser.js",
+  "files": [
+    "index.d.ts",
+    "index.js",
+    "wrapper.js",
+    "wrapper.d.ts",
+    "browser.js"
+  ],
+  "napi": {
+    "binaryName": "monty",
+    "targets": [
+      "x86_64-pc-windows-msvc",
+      "x86_64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-apple-darwin",
+      "wasm32-wasip1-threads"
+    ],
+    "dtsHeaderFile": "./index-header.d.ts"
+  },
+  "engines": {
+    "node": ">= 6.14.2 < 7 || >= 8.11.2 < 9 || >= 9.11.0 < 10 || >= 10.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "bench": "node --import @oxc-node/core/register benchmark/bench.ts",
+    "build": "run-s build:napi build:ts",
+    "build:debug": "run-s build:napi:debug build:ts",
+    "build:napi": "napi build --platform --release --esm",
+    "build:napi:debug": "napi build --platform --esm",
+    "build:ts": "tsc",
+    "create-npm-dirs": "napi create-npm-dirs",
+    "format": "run-p format:prettier format:rs format:toml",
+    "format:prettier": "prettier . -w",
+    "format:toml": "taplo format",
+    "format:rs": "cargo fmt",
+    "lint": "oxlint .",
+    "prepublishOnly": "napi prepublish -t npm",
+    "test": "ava",
+    "smoke-test": "bash scripts/smoke-test.sh",
+    "preversion": "napi build --platform && git add .",
+    "version": "napi version"
+  },
+  "devDependencies": {
+    "@emnapi/core": "^1.5.0",
+    "@emnapi/runtime": "^1.5.0",
+    "@napi-rs/cli": "^3.2.0",
+    "@oxc-node/core": "^0.0.35",
+    "@taplo/cli": "^0.7.0",
+    "@tybys/wasm-util": "^0.10.0",
+    "@types/node": "^25.0.9",
+    "ava": "^6.4.1",
+    "chalk": "^5.6.2",
+    "npm-run-all2": "^8.0.4",
+    "oxlint": "^1.14.0",
+    "prettier": "^3.6.2",
+    "tinybench": "^6.0.0",
+    "typescript": "^5.9.2"
+  },
+  "ava": {
+    "extensions": {
+      "ts": "module"
+    },
+    "timeout": "2m",
+    "workerThreads": false,
+    "nodeArguments": [
+      "--import",
+      "@oxc-node/core/register"
+    ]
+  },
+  "prettier": {
+    "printWidth": 120,
+    "semi": false,
+    "trailingComma": "all",
+    "singleQuote": true,
+    "arrowParens": "always"
+  }
+}

package/wrapper.d.ts

@@ -0,0 +1,225 @@
+import type { MontyOptions, RunOptions, ResourceLimits, Frame, ExceptionInfo, StartOptions, ResumeOptions, ExceptionInput, SnapshotLoadOptions, JsMontyObject } from './index.js';
+import { MontySnapshot as NativeMontySnapshot, MontyComplete as NativeMontyComplete, MontyException as NativeMontyException, MontyTypingError as NativeMontyTypingError } from './index.js';
+export type { MontyOptions, RunOptions, ResourceLimits, Frame, ExceptionInfo, StartOptions, ResumeOptions, ExceptionInput, SnapshotLoadOptions, JsMontyObject, };
+/**
+ * Alias for ResourceLimits (deprecated name).
+ */
+export type JsResourceLimits = ResourceLimits;
+/**
+ * Base class for all Monty interpreter errors.
+ *
+ * This is the parent class for `MontySyntaxError`, `MontyRuntimeError`, and `MontyTypingError`.
+ * Catching `MontyError` will catch any exception raised by Monty.
+ */
+export declare class MontyError extends Error {
+    protected _typeName: string;
+    protected _message: string;
+    constructor(typeName: string, message: string);
+    /**
+     * Returns information about the inner Python exception.
+     */
+    get exception(): ExceptionInfo;
+    /**
+     * Returns formatted exception string.
+     * @param format - 'type-msg' for 'ExceptionType: message', 'msg' for just the message
+     */
+    display(format?: 'type-msg' | 'msg'): string;
+}
+/**
+ * Raised when Python code has syntax errors or cannot be parsed by Monty.
+ *
+ * The inner exception is always a `SyntaxError`. Use `display()` to get
+ * formatted error output.
+ */
+export declare class MontySyntaxError extends MontyError {
+    private _native;
+    constructor(messageOrNative: string | NativeMontyException);
+    /**
+     * Returns formatted exception string.
+     * @param format - 'type-msg' for 'SyntaxError: message', 'msg' for just the message
+     */
+    display(format?: 'type-msg' | 'msg'): string;
+}
+/**
+ * Raised when Monty code fails during execution.
+ *
+ * Provides access to the traceback frames where the error occurred via `traceback()`,
+ * and formatted output via `display()`.
+ */
+export declare class MontyRuntimeError extends MontyError {
+    private _native;
+    private _tracebackString;
+    private _frames;
+    constructor(nativeOrTypeName: NativeMontyException | string, message?: string, tracebackString?: string, frames?: Frame[]);
+    /**
+     * Returns the Monty traceback as an array of Frame objects.
+     */
+    traceback(): Frame[];
+    /**
+     * Returns formatted exception string.
+     * @param format - 'traceback' for full traceback, 'type-msg' for 'ExceptionType: message', 'msg' for just the message
+     */
+    display(format?: 'traceback' | 'type-msg' | 'msg'): string;
+}
+export type TypingDisplayFormat = 'full' | 'concise' | 'azure' | 'json' | 'jsonlines' | 'rdjson' | 'pylint' | 'gitlab' | 'github';
+/**
+ * Raised when type checking finds errors in the code.
+ *
+ * This exception is raised when static type analysis detects type errors.
+ * Use `displayDiagnostics()` to render rich diagnostics in various formats for tooling integration.
+ * Use `display()` (inherited) for simple 'type-msg' or 'msg' formats.
+ */
+export declare class MontyTypingError extends MontyError {
+    private _native;
+    constructor(messageOrNative: string | NativeMontyTypingError, nativeError?: NativeMontyTypingError | null);
+    /**
+     * Renders rich type error diagnostics for tooling integration.
+     *
+     * @param format - Output format (default: 'full')
+     * @param color - Include ANSI color codes (default: false)
+     */
+    displayDiagnostics(format?: TypingDisplayFormat, color?: boolean): string;
+}
+/**
+ * Wrapped Monty class that throws proper Error subclasses.
+ */
+export declare class Monty {
+    private _native;
+    /**
+     * Creates a new Monty interpreter by parsing the given code.
+     *
+     * @param code - Python code to execute
+     * @param options - Configuration options
+     * @throws {MontySyntaxError} If the code has syntax errors
+     * @throws {MontyTypingError} If type checking is enabled and finds errors
+     */
+    constructor(code: string, options?: MontyOptions);
+    /**
+     * Performs static type checking on the code.
+     *
+     * @param prefixCode - Optional code to prepend before type checking
+     * @throws {MontyTypingError} If type checking finds errors
+     */
+    typeCheck(prefixCode?: string): void;
+    /**
+     * Executes the code and returns the result.
+     *
+     * @param options - Execution options (inputs, limits)
+     * @returns The result of the last expression
+     * @throws {MontyRuntimeError} If the code raises an exception
+     */
+    run(options?: RunOptions): JsMontyObject;
+    /**
+     * Starts execution and returns either a snapshot (paused at external call) or completion.
+     *
+     * @param options - Execution options (inputs, limits)
+     * @returns MontySnapshot if an external function call is pending, MontyComplete if done
+     * @throws {MontyRuntimeError} If the code raises an exception
+     */
+    start(options?: StartOptions): MontySnapshot | MontyComplete;
+    /**
+     * Serializes the Monty instance to a binary format.
+     */
+    dump(): Buffer;
+    /**
+     * Deserializes a Monty instance from binary format.
+     */
+    static load(data: Buffer): Monty;
+    /** Returns the script name. */
+    get scriptName(): string;
+    /** Returns the input variable names. */
+    get inputs(): string[];
+    /** Returns the external function names. */
+    get externalFunctions(): string[];
+    /** Returns a string representation of the Monty instance. */
+    repr(): string;
+}
+/**
+ * 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 {
+    private _native;
+    constructor(nativeSnapshot: NativeMontySnapshot);
+    /** 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(): JsMontyObject[];
+    /** Returns the keyword arguments passed to the external function as an object. */
+    get kwargs(): Record<string, JsMontyObject>;
+    /**
+     * Resumes execution with either a return value or an exception.
+     *
+     * @param options - Object with either `returnValue` or `exception`
+     * @returns MontySnapshot if another external call is pending, MontyComplete if done
+     * @throws {MontyRuntimeError} If the code raises an exception
+     */
+    resume(options: ResumeOptions): MontySnapshot | MontyComplete;
+    /**
+     * Serializes the MontySnapshot to a binary format.
+     */
+    dump(): Buffer;
+    /**
+     * Deserializes a MontySnapshot from binary format.
+     */
+    static load(data: Buffer, options?: SnapshotLoadOptions): MontySnapshot;
+    /** Returns a string representation of the MontySnapshot. */
+    repr(): string;
+}
+/**
+ * Represents completed execution with a final output value.
+ */
+export declare class MontyComplete {
+    private _native;
+    constructor(nativeComplete: NativeMontyComplete);
+    /** Returns the final output value from the executed code. */
+    get output(): JsMontyObject;
+    /** Returns a string representation of the MontyComplete. */
+    repr(): string;
+}
+/**
+ * Options for `runMontyAsync`.
+ */
+export interface RunMontyAsyncOptions {
+    /** Input values for the script. */
+    inputs?: Record<string, JsMontyObject>;
+    /** External function implementations (sync or async). */
+    externalFunctions?: Record<string, (...args: unknown[]) => unknown>;
+    /** Resource limits. */
+    limits?: ResourceLimits;
+}
+/**
+ * Runs a Monty script with async external function support.
+ *
+ * This function handles both synchronous and asynchronous external functions.
+ * When an external function returns a Promise, it will be awaited before
+ * resuming execution.
+ *
+ * @param montyRunner - The Monty runner instance to execute
+ * @param options - Execution options
+ * @returns The output of the Monty script
+ * @throws {MontyRuntimeError} If the code raises an exception
+ * @throws {MontySyntaxError} If the code has syntax errors
+ *
+ * @example
+ * const m = new Monty('result = await fetch_data(url)', {
+ *   inputs: ['url'],
+ *   externalFunctions: ['fetch_data']
+ * });
+ *
+ * const result = await runMontyAsync(m, {
+ *   inputs: { url: 'https://example.com' },
+ *   externalFunctions: {
+ *     fetch_data: async (url) => {
+ *       const response = await fetch(url);
+ *       return response.text();
+ *     }
+ *   }
+ * });
+ */
+export declare function runMontyAsync(montyRunner: Monty, options?: RunMontyAsyncOptions): Promise<JsMontyObject>;
+//# sourceMappingURL=wrapper.d.ts.map