@sema-lang/sema 1.9.0

package/dist/index.d.ts

@@ -0,0 +1,299 @@
+/**
+ * @sema-lang/sema — Sema Lisp interpreter for JavaScript
+ *
+ * A client-side scripting engine powered by WebAssembly.
+ * Embed Sema as a scripting language in your web applications.
+ *
+ * @example
+ * ```js
+ * import { SemaInterpreter } from "@sema-lang/sema";
+ *
+ * const sema = await SemaInterpreter.create();
+ * const result = sema.evalStr("(+ 1 2 3)");
+ * console.log(result.value); // "6"
+ * ```
+ */
+import type { VFSBackend } from "./vfs.js";
+/** Result of evaluating Sema code. */
+export interface EvalResult {
+    /** The string representation of the result value, or null if the expression returned nil. */
+    value: string | null;
+    /** Lines printed to stdout during evaluation (via `print`, `println`, `display`). */
+    output: string[];
+    /** Error message if evaluation failed, or null on success. */
+    error: string | null;
+}
+/** Options for creating a SemaInterpreter. */
+export interface InterpreterOptions {
+    /**
+     * URL to the `.wasm` binary. Required when loading from a CDN or
+     * when the default resolution doesn't work.
+     *
+     * @example
+     * ```js
+     * const sema = await SemaInterpreter.create({
+     *   wasmUrl: "https://cdn.jsdelivr.net/npm/@sema-lang/sema-wasm@1.9.0/sema_wasm_bg.wasm"
+     * });
+     * ```
+     */
+    wasmUrl?: string | URL;
+    /**
+     * Whether to include the standard library. Default: `true`.
+     * Set to `false` for a minimal interpreter with only special forms.
+     */
+    stdlib?: boolean;
+    /**
+     * Array of capabilities to deny. Available capabilities:
+     * - `"network"` — deny HTTP functions (http/get, http/post, etc.)
+     * - `"fs-read"` — deny VFS read operations
+     * - `"fs-write"` — deny VFS write operations
+     *
+     * @example
+     * ```js
+     * const sema = await SemaInterpreter.create({ deny: ["network"] });
+     * ```
+     */
+    deny?: Array<"network" | "fs-read" | "fs-write">;
+    /**
+     * Optional VFS backend for persisting files across page reloads.
+     *
+     * Built-in backends:
+     * - {@link MemoryBackend} — ephemeral, no persistence (default behavior)
+     * - {@link LocalStorageBackend} — persist to localStorage (~5 MB limit)
+     * - {@link SessionStorageBackend} — persist within the tab session
+     * - {@link IndexedDBBackend} — persist to IndexedDB (recommended for production)
+     *
+     * @example
+     * ```js
+     * import { SemaInterpreter, IndexedDBBackend } from "@sema-lang/sema";
+     * const sema = await SemaInterpreter.create({
+     *   vfs: new IndexedDBBackend({ namespace: "my-project" }),
+     * });
+     * ```
+     */
+    vfs?: VFSBackend;
+}
+/** Virtual filesystem usage statistics. */
+export interface VFSStats {
+    /** Number of files currently in the VFS. */
+    files: number;
+    /** Total bytes used. */
+    bytes: number;
+    /** Maximum number of files allowed. */
+    maxFiles: number;
+    /** Maximum total bytes allowed. */
+    maxBytes: number;
+    /** Maximum bytes per individual file. */
+    maxFileBytes: number;
+}
+/**
+ * A Sema Lisp interpreter instance.
+ *
+ * Each interpreter has its own isolated environment — variables defined in one
+ * interpreter are not visible in another.
+ *
+ * @example
+ * ```js
+ * const sema = await SemaInterpreter.create();
+ *
+ * // Evaluate expressions
+ * sema.evalStr("(define x 42)");
+ * const r = sema.evalStr("(* x x)");
+ * console.log(r.value); // "1764"
+ *
+ * // Register JS functions
+ * sema.registerFunction("greet", (name) => `Hello, ${name}!`);
+ * sema.evalStr('(greet "world")'); // => "Hello, world!"
+ *
+ * // Preload modules
+ * sema.preloadModule("utils", "(define (double x) (* x 2))");
+ * sema.evalStr('(import "utils")');
+ * sema.evalStr("(double 21)"); // => "42"
+ * ```
+ */
+export declare class SemaInterpreter {
+    private _inner;
+    private _vfsBackend;
+    private constructor();
+    /**
+     * Create a new SemaInterpreter instance.
+     *
+     * This initializes the WASM module (once, globally) and creates an interpreter.
+     * The WASM module is cached — subsequent calls are fast.
+     *
+     * @param opts - Configuration options
+     * @returns A ready-to-use SemaInterpreter
+     *
+     * @example
+     * ```js
+     * // Default: full standard library
+     * const sema = await SemaInterpreter.create();
+     *
+     * // Minimal: only special forms
+     * const minimal = await SemaInterpreter.create({ stdlib: false });
+     *
+     * // From CDN
+     * const cdn = await SemaInterpreter.create({
+     *   wasmUrl: "https://cdn.jsdelivr.net/npm/@sema-lang/sema-wasm@1.9.0/sema_wasm_bg.wasm"
+     * });
+     * ```
+     */
+    static create(opts?: InterpreterOptions): Promise<SemaInterpreter>;
+    private _vfsHost;
+    /**
+     * Evaluate a string of Sema code.
+     *
+     * Definitions persist across calls — you can `define` a function in one call
+     * and use it in the next.
+     *
+     * @param code - Sema source code to evaluate
+     * @returns The evaluation result
+     *
+     * @example
+     * ```js
+     * const r = sema.evalStr("(map (lambda (x) (* x x)) '(1 2 3 4 5))");
+     * console.log(r.value);  // "(1 4 9 16 25)"
+     * console.log(r.output); // [] (no print statements)
+     * console.log(r.error);  // null (no error)
+     * ```
+     */
+    evalStr(code: string): EvalResult;
+    /**
+     * Evaluate code with async HTTP support.
+     *
+     * Use this when your Sema code uses `http/get` or other network functions.
+     * The interpreter will automatically handle the async fetch operations.
+     *
+     * @param code - Sema source code to evaluate
+     * @returns The evaluation result
+     *
+     * @example
+     * ```js
+     * const r = await sema.evalStrAsync('(http/get "https://api.example.com/data")');
+     * ```
+     */
+    evalStrAsync(code: string): Promise<EvalResult>;
+    /**
+     * Register a JavaScript function that can be called from Sema code.
+     *
+     * Arguments are passed as native JavaScript values (numbers, strings,
+     * booleans, null, arrays, objects). The return value is converted back
+     * to a Sema value.
+     *
+     * @param name - The function name in Sema (e.g., "my-fn")
+     * @param fn - The JavaScript function to call
+     *
+     * @example
+     * ```js
+     * // Simple function — args are native JS values
+     * sema.registerFunction("add1", (n) => n + 1);
+     *
+     * // Multiple args
+     * sema.registerFunction("greet", (greeting, name) => `${greeting}, ${name}!`);
+     *
+     * // Returning structured data (objects become Sema maps)
+     * sema.registerFunction("get-user", (id) => ({ name: "Alice", age: 30 }));
+     * ```
+     */
+    registerFunction(name: string, fn: (...args: any[]) => any): void;
+    /**
+     * Preload a virtual module so that `(import "name")` works without a file.
+     *
+     * @param name - The module name (used in `(import "name")`)
+     * @param source - Sema source code defining the module's exports
+     * @throws If the module source has syntax or evaluation errors
+     *
+     * @example
+     * ```js
+     * sema.preloadModule("utils", `
+     *   (define (double x) (* x 2))
+     *   (define pi 3.14159)
+     * `);
+     *
+     * sema.evalStr('(import "utils")');
+     * sema.evalStr("(double pi)"); // => "6.28318"
+     * ```
+     */
+    preloadModule(name: string, source: string): void;
+    /**
+     * Read a file from the virtual filesystem.
+     * @returns The file contents, or null if the file doesn't exist.
+     */
+    readFile(path: string): string | null;
+    /**
+     * Write a file to the virtual filesystem.
+     * Quotas: 1 MB per file, 16 MB total, 256 files max.
+     * @throws If a VFS quota is exceeded.
+     */
+    writeFile(path: string, content: string): void;
+    /**
+     * Delete a file from the virtual filesystem.
+     * @returns true if the file existed and was deleted.
+     */
+    deleteFile(path: string): boolean;
+    /**
+     * List entries in a VFS directory.
+     * @returns Array of file and directory names (not full paths).
+     */
+    listFiles(dir?: string): string[];
+    /**
+     * Check if a path exists in the VFS (file or directory).
+     */
+    fileExists(path: string): boolean;
+    /**
+     * Create a directory (and parent directories) in the VFS.
+     */
+    mkdir(path: string): void;
+    /**
+     * Check if a path is a directory in the VFS.
+     */
+    isDirectory(path: string): boolean;
+    /**
+     * Get VFS usage statistics (file count, bytes used, quotas).
+     */
+    vfsStats(): VFSStats;
+    /**
+     * Clear all files and directories from the VFS.
+     */
+    resetVFS(): void;
+    /**
+     * Persist VFS changes to the configured backend.
+     *
+     * No-op if no VFS backend was provided during creation.
+     * Call this after eval to save files.
+     *
+     * @example
+     * ```js
+     * await sema.evalStrAsync(code);
+     * await sema.flushVFS(); // persist to localStorage/IndexedDB/etc.
+     * ```
+     */
+    flushVFS(): Promise<void>;
+    /**
+     * Clear the VFS and the persistent backend (if configured).
+     */
+    resetVFSAndBackend(): Promise<void>;
+    /**
+     * Get the Sema interpreter version.
+     *
+     * @returns Version string (e.g., "1.9.0")
+     */
+    version(): string;
+    /**
+     * Free the interpreter's WASM memory.
+     *
+     * Call this when you're done with the interpreter to release resources.
+     * The interpreter cannot be used after calling this method.
+     */
+    dispose(): void;
+}
+export type { VFSBackend, VFSHost } from "./vfs.js";
+export { MemoryBackend } from "./backends/memory.js";
+export { LocalStorageBackend } from "./backends/local-storage.js";
+export type { LocalStorageBackendOptions } from "./backends/local-storage.js";
+export { SessionStorageBackend } from "./backends/session-storage.js";
+export type { SessionStorageBackendOptions } from "./backends/session-storage.js";
+export { IndexedDBBackend } from "./backends/indexed-db.js";
+export type { IndexedDBBackendOptions } from "./backends/indexed-db.js";
+/** @deprecated Use `SemaInterpreter` instead. */
+export { SemaInterpreter as Interpreter };

package/dist/index.js

@@ -0,0 +1,324 @@
+/**
+ * @sema-lang/sema — Sema Lisp interpreter for JavaScript
+ *
+ * A client-side scripting engine powered by WebAssembly.
+ * Embed Sema as a scripting language in your web applications.
+ *
+ * @example
+ * ```js
+ * import { SemaInterpreter } from "@sema-lang/sema";
+ *
+ * const sema = await SemaInterpreter.create();
+ * const result = sema.evalStr("(+ 1 2 3)");
+ * console.log(result.value); // "6"
+ * ```
+ */
+// Internal state
+let _init = null;
+let _SemaInterpreter = null;
+let _initialized = false;
+let _initPromise = null;
+async function ensureInit(wasmUrl) {
+    if (_initialized)
+        return;
+    if (_initPromise) {
+        await _initPromise;
+        return;
+    }
+    _initPromise = (async () => {
+        // Dynamic import so bundlers can tree-shake when not used
+        const mod = await import("@sema-lang/sema-wasm");
+        _init = mod.default;
+        _SemaInterpreter = mod.SemaInterpreter;
+        if (wasmUrl) {
+            await _init(wasmUrl);
+        }
+        else {
+            await _init();
+        }
+        _initialized = true;
+    })();
+    await _initPromise;
+}
+/**
+ * A Sema Lisp interpreter instance.
+ *
+ * Each interpreter has its own isolated environment — variables defined in one
+ * interpreter are not visible in another.
+ *
+ * @example
+ * ```js
+ * const sema = await SemaInterpreter.create();
+ *
+ * // Evaluate expressions
+ * sema.evalStr("(define x 42)");
+ * const r = sema.evalStr("(* x x)");
+ * console.log(r.value); // "1764"
+ *
+ * // Register JS functions
+ * sema.registerFunction("greet", (name) => `Hello, ${name}!`);
+ * sema.evalStr('(greet "world")'); // => "Hello, world!"
+ *
+ * // Preload modules
+ * sema.preloadModule("utils", "(define (double x) (* x 2))");
+ * sema.evalStr('(import "utils")');
+ * sema.evalStr("(double 21)"); // => "42"
+ * ```
+ */
+export class SemaInterpreter {
+    constructor(inner, vfsBackend = null) {
+        this._inner = inner;
+        this._vfsBackend = vfsBackend;
+    }
+    /**
+     * Create a new SemaInterpreter instance.
+     *
+     * This initializes the WASM module (once, globally) and creates an interpreter.
+     * The WASM module is cached — subsequent calls are fast.
+     *
+     * @param opts - Configuration options
+     * @returns A ready-to-use SemaInterpreter
+     *
+     * @example
+     * ```js
+     * // Default: full standard library
+     * const sema = await SemaInterpreter.create();
+     *
+     * // Minimal: only special forms
+     * const minimal = await SemaInterpreter.create({ stdlib: false });
+     *
+     * // From CDN
+     * const cdn = await SemaInterpreter.create({
+     *   wasmUrl: "https://cdn.jsdelivr.net/npm/@sema-lang/sema-wasm@1.9.0/sema_wasm_bg.wasm"
+     * });
+     * ```
+     */
+    static async create(opts) {
+        await ensureInit(opts?.wasmUrl);
+        const needsOptions = opts?.stdlib === false || (opts?.deny && opts.deny.length > 0);
+        let inner;
+        if (needsOptions) {
+            inner = _SemaInterpreter.createWithOptions({
+                stdlib: opts?.stdlib ?? true,
+                deny: opts?.deny,
+            });
+        }
+        else {
+            inner = new _SemaInterpreter();
+        }
+        const interp = new SemaInterpreter(inner, opts?.vfs ?? null);
+        if (interp._vfsBackend) {
+            await interp._vfsBackend.init?.();
+            await interp._vfsBackend.hydrate(interp._vfsHost());
+        }
+        return interp;
+    }
+    _vfsHost() {
+        return {
+            readFile: (p) => this.readFile(p),
+            writeFile: (p, c) => this.writeFile(p, c),
+            deleteFile: (p) => this.deleteFile(p),
+            mkdir: (p) => this.mkdir(p),
+            listFiles: (d) => this.listFiles(d),
+            fileExists: (p) => this.fileExists(p),
+            isDirectory: (p) => this.isDirectory(p),
+            resetVFS: () => this.resetVFS(),
+        };
+    }
+    /**
+     * Evaluate a string of Sema code.
+     *
+     * Definitions persist across calls — you can `define` a function in one call
+     * and use it in the next.
+     *
+     * @param code - Sema source code to evaluate
+     * @returns The evaluation result
+     *
+     * @example
+     * ```js
+     * const r = sema.evalStr("(map (lambda (x) (* x x)) '(1 2 3 4 5))");
+     * console.log(r.value);  // "(1 4 9 16 25)"
+     * console.log(r.output); // [] (no print statements)
+     * console.log(r.error);  // null (no error)
+     * ```
+     */
+    evalStr(code) {
+        return this._inner.evalGlobal(code);
+    }
+    /**
+     * Evaluate code with async HTTP support.
+     *
+     * Use this when your Sema code uses `http/get` or other network functions.
+     * The interpreter will automatically handle the async fetch operations.
+     *
+     * @param code - Sema source code to evaluate
+     * @returns The evaluation result
+     *
+     * @example
+     * ```js
+     * const r = await sema.evalStrAsync('(http/get "https://api.example.com/data")');
+     * ```
+     */
+    async evalStrAsync(code) {
+        return (await this._inner.evalAsync(code));
+    }
+    /**
+     * Register a JavaScript function that can be called from Sema code.
+     *
+     * Arguments are passed as native JavaScript values (numbers, strings,
+     * booleans, null, arrays, objects). The return value is converted back
+     * to a Sema value.
+     *
+     * @param name - The function name in Sema (e.g., "my-fn")
+     * @param fn - The JavaScript function to call
+     *
+     * @example
+     * ```js
+     * // Simple function — args are native JS values
+     * sema.registerFunction("add1", (n) => n + 1);
+     *
+     * // Multiple args
+     * sema.registerFunction("greet", (greeting, name) => `${greeting}, ${name}!`);
+     *
+     * // Returning structured data (objects become Sema maps)
+     * sema.registerFunction("get-user", (id) => ({ name: "Alice", age: 30 }));
+     * ```
+     */
+    registerFunction(name, fn) {
+        this._inner.registerFunction(name, fn);
+    }
+    /**
+     * Preload a virtual module so that `(import "name")` works without a file.
+     *
+     * @param name - The module name (used in `(import "name")`)
+     * @param source - Sema source code defining the module's exports
+     * @throws If the module source has syntax or evaluation errors
+     *
+     * @example
+     * ```js
+     * sema.preloadModule("utils", `
+     *   (define (double x) (* x 2))
+     *   (define pi 3.14159)
+     * `);
+     *
+     * sema.evalStr('(import "utils")');
+     * sema.evalStr("(double pi)"); // => "6.28318"
+     * ```
+     */
+    preloadModule(name, source) {
+        const result = this._inner.preloadModule(name, source);
+        if (!result.ok) {
+            throw new Error(`Failed to preload module "${name}": ${result.error}`);
+        }
+    }
+    /**
+     * Read a file from the virtual filesystem.
+     * @returns The file contents, or null if the file doesn't exist.
+     */
+    readFile(path) {
+        const result = this._inner.readFile(path);
+        return result === null || result === undefined ? null : result;
+    }
+    /**
+     * Write a file to the virtual filesystem.
+     * Quotas: 1 MB per file, 16 MB total, 256 files max.
+     * @throws If a VFS quota is exceeded.
+     */
+    writeFile(path, content) {
+        const error = this._inner.writeFile(path, content);
+        if (typeof error === "string") {
+            throw new Error(error);
+        }
+    }
+    /**
+     * Delete a file from the virtual filesystem.
+     * @returns true if the file existed and was deleted.
+     */
+    deleteFile(path) {
+        return this._inner.deleteFile(path);
+    }
+    /**
+     * List entries in a VFS directory.
+     * @returns Array of file and directory names (not full paths).
+     */
+    listFiles(dir) {
+        return Array.from(this._inner.listFiles(dir ?? "/"));
+    }
+    /**
+     * Check if a path exists in the VFS (file or directory).
+     */
+    fileExists(path) {
+        return this._inner.fileExists(path);
+    }
+    /**
+     * Create a directory (and parent directories) in the VFS.
+     */
+    mkdir(path) {
+        this._inner.mkdir(path);
+    }
+    /**
+     * Check if a path is a directory in the VFS.
+     */
+    isDirectory(path) {
+        return this._inner.isDirectory(path);
+    }
+    /**
+     * Get VFS usage statistics (file count, bytes used, quotas).
+     */
+    vfsStats() {
+        return this._inner.vfsStats();
+    }
+    /**
+     * Clear all files and directories from the VFS.
+     */
+    resetVFS() {
+        this._inner.resetVFS();
+    }
+    /**
+     * Persist VFS changes to the configured backend.
+     *
+     * No-op if no VFS backend was provided during creation.
+     * Call this after eval to save files.
+     *
+     * @example
+     * ```js
+     * await sema.evalStrAsync(code);
+     * await sema.flushVFS(); // persist to localStorage/IndexedDB/etc.
+     * ```
+     */
+    async flushVFS() {
+        if (this._vfsBackend) {
+            await this._vfsBackend.flush(this._vfsHost());
+        }
+    }
+    /**
+     * Clear the VFS and the persistent backend (if configured).
+     */
+    async resetVFSAndBackend() {
+        this._inner.resetVFS();
+        await this._vfsBackend?.reset?.();
+    }
+    /**
+     * Get the Sema interpreter version.
+     *
+     * @returns Version string (e.g., "1.9.0")
+     */
+    version() {
+        return this._inner.version();
+    }
+    /**
+     * Free the interpreter's WASM memory.
+     *
+     * Call this when you're done with the interpreter to release resources.
+     * The interpreter cannot be used after calling this method.
+     */
+    dispose() {
+        this._inner.free();
+    }
+}
+export { MemoryBackend } from "./backends/memory.js";
+export { LocalStorageBackend } from "./backends/local-storage.js";
+export { SessionStorageBackend } from "./backends/session-storage.js";
+export { IndexedDBBackend } from "./backends/indexed-db.js";
+/** @deprecated Use `SemaInterpreter` instead. */
+export { SemaInterpreter as Interpreter };

package/dist/vfs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Host bridge — methods the backend calls to read/write the in-memory WASM VFS.
+ * Provided by SemaInterpreter, not implemented by users.
+ */
+export interface VFSHost {
+    readFile(path: string): string | null;
+    writeFile(path: string, content: string): void;
+    deleteFile(path: string): boolean;
+    mkdir(path: string): void;
+    listFiles(dir: string): string[];
+    fileExists(path: string): boolean;
+    isDirectory(path: string): boolean;
+    resetVFS(): void;
+}
+/**
+ * Pluggable VFS storage backend.
+ *
+ * Implement this interface to persist VFS state across page reloads.
+ * The backend runs outside the eval loop, so async is allowed.
+ *
+ * Built-in implementations:
+ * - {@link MemoryBackend} — ephemeral, no persistence
+ * - {@link LocalStorageBackend} — persist to localStorage (~5 MB limit)
+ * - {@link SessionStorageBackend} — persist within the tab session
+ * - {@link IndexedDBBackend} — persist to IndexedDB (recommended for production)
+ *
+ * @example
+ * ```ts
+ * import { SemaInterpreter, IndexedDBBackend } from "@sema-lang/sema";
+ *
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new IndexedDBBackend({ namespace: "my-app" }),
+ * });
+ * await sema.evalStrAsync(code);
+ * await sema.flushVFS(); // persist changes
+ * ```
+ */
+export interface VFSBackend {
+    /** Optional: open DB connections, request permissions, etc. */
+    init?(): Promise<void>;
+    /**
+     * Populate the in-memory WASM VFS from persistent storage.
+     * Called once during `SemaInterpreter.create()`.
+     */
+    hydrate(host: VFSHost): Promise<void>;
+    /**
+     * Persist current in-memory VFS state to storage.
+     * Called explicitly via `sema.flushVFS()`.
+     */
+    flush(host: VFSHost): Promise<void>;
+    /** Optional: clear all persistent data. */
+    reset?(): Promise<void>;
+}

package/dist/vfs.js

@@ -0,0 +1 @@
+export {};