@sema-lang/sema 1.9.0

package/README.md

@@ -0,0 +1,210 @@
+# @sema-lang/sema
+
+Sema Lisp interpreter for JavaScript — a client-side scripting engine powered by WebAssembly.
+
+## Install
+
+```bash
+npm install @sema-lang/sema
+```
+
+Or use directly from a CDN:
+
+```html
+<script type="module">
+  import { SemaInterpreter } from "https://cdn.jsdelivr.net/npm/@sema-lang/sema/+esm";
+
+  const sema = await SemaInterpreter.create();
+  console.log(sema.evalStr("(+ 1 2 3)").value); // "6"
+</script>
+```
+
+## Quick Start
+
+```js
+import { SemaInterpreter } from "@sema-lang/sema";
+
+const sema = await SemaInterpreter.create();
+
+// Evaluate expressions
+const r = sema.evalStr("(+ 1 2 3)");
+console.log(r.value);  // "6"
+
+// Definitions persist
+sema.evalStr("(define (square x) (* x x))");
+sema.evalStr("(square 7)"); // => "49"
+
+// Register JS functions — args are native JS values
+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"
+```
+
+## API
+
+### `SemaInterpreter.create(opts?)`
+
+Create a new interpreter. Options:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `wasmUrl` | auto | URL to the `.wasm` binary |
+| `stdlib` | `true` | Include the standard library |
+| `deny` | `[]` | Capabilities to deny: `"network"`, `"fs-read"`, `"fs-write"` |
+| `vfs` | none | VFS backend for persistence: `MemoryBackend`, `LocalStorageBackend`, `SessionStorageBackend`, `IndexedDBBackend` |
+
+### `evalStr(code)` → `EvalResult`
+
+Evaluate Sema code synchronously. Returns `{ value, output, error }`.
+
+### `evalStrAsync(code)` → `Promise<EvalResult>`
+
+Evaluate code that may use `http/get` or other async operations.
+
+### `registerFunction(name, fn)`
+
+Register a JS function callable from Sema. Args are passed as native JS values.
+
+### `preloadModule(name, source)`
+
+Inject a virtual module for use with `(import "name")`.
+
+### `version()` → `string`
+
+Returns the interpreter version.
+
+### `readFile(path)` → `string | null`
+
+Read a file from the virtual filesystem. Returns `null` if the file doesn't exist.
+
+### `writeFile(path, content)`
+
+Write a file to the virtual filesystem (1 MB per file, 16 MB total, 256 files max).
+
+### `deleteFile(path)` → `boolean`
+
+Delete a file from the VFS. Returns `true` if the file existed.
+
+### `listFiles(dir?)` → `string[]`
+
+List entries in a VFS directory.
+
+### `fileExists(path)` → `boolean`
+
+Check if a path exists in the VFS.
+
+### `mkdir(path)`
+
+Create a directory (and parent directories) in the VFS.
+
+### `isDirectory(path)` → `boolean`
+
+Check if a path is a directory in the VFS.
+
+### `vfsStats()` → `VFSStats`
+
+Get VFS usage statistics: `{ files, bytes, maxFiles, maxBytes, maxFileBytes }`.
+
+### `resetVFS()`
+
+Clear all files and directories from the VFS.
+
+### `flushVFS()` → `Promise<void>`
+
+Persist VFS changes to the configured backend. No-op if no backend was provided.
+
+### `resetVFSAndBackend()` → `Promise<void>`
+
+Clear the VFS and the persistent backend storage.
+
+### `dispose()`
+
+Free WASM memory. Interpreter cannot be used after this.
+
+## Virtual Filesystem
+
+```js
+// Seed files from JS
+sema.writeFile("/lib/utils.sema", "(define (double x) (* x 2))");
+
+// Build a file browser
+const files = sema.listFiles("/");       // ["lib"]
+const libFiles = sema.listFiles("/lib"); // ["utils.sema"]
+
+// Read back
+const source = sema.readFile("/lib/utils.sema");
+
+// Check quota usage
+const stats = sema.vfsStats();
+// { files: 1, bytes: 28, maxFiles: 256, maxBytes: 16777216, maxFileBytes: 1048576 }
+
+// Clean up
+sema.resetVFS();
+```
+
+## VFS Persistence
+
+By default, VFS files are lost on page reload. Use a backend to persist them:
+
+```js
+import { SemaInterpreter, IndexedDBBackend } from "@sema-lang/sema";
+
+const sema = await SemaInterpreter.create({
+  vfs: new IndexedDBBackend({ namespace: "my-project" }),
+});
+
+// Files written by Sema code are persisted after flush
+await sema.evalStrAsync('(file/write "/hello.txt" "Hello!")');
+await sema.flushVFS();
+
+// On next page load, files are automatically restored
+```
+
+### Built-in Backends
+
+| Backend | Persistence | Size Limit | Best For |
+|---------|-------------|------------|----------|
+| `MemoryBackend` | None (lost on reload) | WASM quota only | Testing, ephemeral sandboxes |
+| `LocalStorageBackend` | Across page loads | ~5–10 MB per origin | Small projects |
+| `SessionStorageBackend` | Within tab session | ~5–10 MB per origin | Scratch work, drafts |
+| `IndexedDBBackend` | Across page loads | Hundreds of MB | **Production use** |
+
+All backends accept a `{ namespace }` option (default: `"sema-vfs"`) to isolate storage between different apps or interpreter instances.
+
+### Custom Backends
+
+Implement the `VFSBackend` interface to use any storage mechanism:
+
+```ts
+import type { VFSBackend, VFSHost } from "@sema-lang/sema";
+
+class MyBackend implements VFSBackend {
+  async init() { /* open connections */ }
+  async hydrate(host: VFSHost) { /* restore files into host */ }
+  async flush(host: VFSHost) { /* save files from host */ }
+  async reset() { /* clear storage */ }
+}
+```
+
+## Sandbox
+
+```js
+const sema = await SemaInterpreter.create({
+  deny: ["network"],  // deny HTTP access
+});
+
+sema.evalStr('(http/get "https://example.com")'); // => PermissionDenied error
+sema.evalStr("(+ 1 2)");                          // => works fine
+```
+
+## Documentation
+
+Full documentation: [sema-lang.com/docs/embedding-js](https://sema-lang.com/docs/embedding-js.html)
+
+## License
+
+MIT

package/dist/backends/indexed-db.d.ts

@@ -0,0 +1,62 @@
+import type { VFSBackend, VFSHost } from "../vfs.js";
+/** Options for {@link IndexedDBBackend}. */
+export interface IndexedDBBackendOptions {
+    /**
+     * IndexedDB database name.
+     * @default "sema-vfs"
+     */
+    namespace?: string;
+}
+/**
+ * VFS backend that persists files to IndexedDB.
+ *
+ * Unlike the localStorage-based backends, IndexedDB supports large blobs and
+ * doesn't share its quota with other synchronous storage.  All reads and writes
+ * are async, which avoids blocking the main thread.
+ *
+ * Uses a single object store (`"files"`) keyed by `path`.
+ *
+ * @example
+ * ```ts
+ * import { SemaInterpreter, IndexedDBBackend } from "@sema-lang/sema";
+ *
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new IndexedDBBackend({ namespace: "my-project" }),
+ * });
+ * await sema.evalStrAsync(code);
+ * await sema.flushVFS();
+ * ```
+ */
+export declare class IndexedDBBackend implements VFSBackend {
+    private dbName;
+    private db;
+    constructor(opts?: IndexedDBBackendOptions);
+    /** Open (or create) the IndexedDB database and cache the connection. */
+    init(): Promise<void>;
+    /**
+     * Populate the in-memory WASM VFS from IndexedDB.
+     *
+     * Directories are restored first (sorted by depth so parents are created
+     * before children), then files.
+     */
+    hydrate(host: VFSHost): Promise<void>;
+    /**
+     * Persist the current in-memory VFS state to IndexedDB.
+     *
+     * Clears the object store and writes all files and directories in a single
+     * readwrite transaction.
+     */
+    flush(host: VFSHost): Promise<void>;
+    /** Clear all persisted data from the object store. */
+    reset(): Promise<void>;
+    /** Open the IndexedDB database, creating the object store if needed. */
+    private openDB;
+    /** Read all records from the `"files"` object store. */
+    private getAll;
+    /** Wait for a transaction to complete. */
+    private txComplete;
+    /** Recursively collect all file paths. */
+    private collectFiles;
+    /** Recursively collect all directory paths. */
+    private collectDirs;
+}

package/dist/backends/indexed-db.js

@@ -0,0 +1,151 @@
+/**
+ * VFS backend that persists files to IndexedDB.
+ *
+ * Unlike the localStorage-based backends, IndexedDB supports large blobs and
+ * doesn't share its quota with other synchronous storage.  All reads and writes
+ * are async, which avoids blocking the main thread.
+ *
+ * Uses a single object store (`"files"`) keyed by `path`.
+ *
+ * @example
+ * ```ts
+ * import { SemaInterpreter, IndexedDBBackend } from "@sema-lang/sema";
+ *
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new IndexedDBBackend({ namespace: "my-project" }),
+ * });
+ * await sema.evalStrAsync(code);
+ * await sema.flushVFS();
+ * ```
+ */
+export class IndexedDBBackend {
+    constructor(opts) {
+        this.db = null;
+        this.dbName = opts?.namespace ?? "sema-vfs";
+    }
+    /** Open (or create) the IndexedDB database and cache the connection. */
+    async init() {
+        this.db = await this.openDB();
+    }
+    /**
+     * Populate the in-memory WASM VFS from IndexedDB.
+     *
+     * Directories are restored first (sorted by depth so parents are created
+     * before children), then files.
+     */
+    async hydrate(host) {
+        const db = this.db ?? await this.openDB();
+        const records = await this.getAll(db);
+        // Restore directories first, shallowest to deepest
+        const dirs = records
+            .filter((r) => r.isDir)
+            .sort((a, b) => a.path.split("/").length - b.path.split("/").length);
+        for (const rec of dirs) {
+            host.mkdir(rec.path);
+        }
+        // Restore files
+        for (const rec of records) {
+            if (!rec.isDir && rec.content !== undefined) {
+                host.writeFile(rec.path, rec.content);
+            }
+        }
+    }
+    /**
+     * Persist the current in-memory VFS state to IndexedDB.
+     *
+     * Clears the object store and writes all files and directories in a single
+     * readwrite transaction.
+     */
+    async flush(host) {
+        const db = this.db ?? await this.openDB();
+        const tx = db.transaction("files", "readwrite");
+        const store = tx.objectStore("files");
+        store.clear();
+        // Write directories
+        const dirs = this.collectDirs(host, "/");
+        for (const dir of dirs) {
+            store.put({ path: dir, isDir: true });
+        }
+        // Write files
+        const files = this.collectFiles(host, "/");
+        for (const filePath of files) {
+            const content = host.readFile(filePath);
+            if (content !== null) {
+                store.put({
+                    path: filePath,
+                    content,
+                    isDir: false,
+                });
+            }
+        }
+        await this.txComplete(tx);
+    }
+    /** Clear all persisted data from the object store. */
+    async reset() {
+        const db = this.db ?? await this.openDB();
+        const tx = db.transaction("files", "readwrite");
+        tx.objectStore("files").clear();
+        await this.txComplete(tx);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /** Open the IndexedDB database, creating the object store if needed. */
+    openDB() {
+        return new Promise((resolve, reject) => {
+            const req = indexedDB.open(this.dbName, 1);
+            req.onupgradeneeded = () => {
+                const db = req.result;
+                if (!db.objectStoreNames.contains("files")) {
+                    db.createObjectStore("files", { keyPath: "path" });
+                }
+            };
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    /** Read all records from the `"files"` object store. */
+    getAll(db) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction("files", "readonly");
+            const req = tx.objectStore("files").getAll();
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    /** Wait for a transaction to complete. */
+    txComplete(tx) {
+        return new Promise((resolve, reject) => {
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    /** Recursively collect all file paths. */
+    collectFiles(host, dir) {
+        const result = [];
+        const entries = host.listFiles(dir);
+        for (const name of entries) {
+            const full = dir === "/" ? "/" + name : dir + "/" + name;
+            if (host.isDirectory(full)) {
+                result.push(...this.collectFiles(host, full));
+            }
+            else {
+                result.push(full);
+            }
+        }
+        return result;
+    }
+    /** Recursively collect all directory paths. */
+    collectDirs(host, dir) {
+        const result = [];
+        const entries = host.listFiles(dir);
+        for (const name of entries) {
+            const full = dir === "/" ? "/" + name : dir + "/" + name;
+            if (host.isDirectory(full)) {
+                result.push(full);
+                result.push(...this.collectDirs(host, full));
+            }
+        }
+        return result;
+    }
+}

package/dist/backends/local-storage.d.ts

@@ -0,0 +1,20 @@
+import { WebStorageBackend } from "./web-storage.js";
+import type { WebStorageBackendOptions } from "./web-storage.js";
+/** Options for LocalStorageBackend. */
+export type LocalStorageBackendOptions = WebStorageBackendOptions;
+/**
+ * VFS backend that persists files to localStorage.
+ *
+ * Simple and synchronous — good for small projects (< 5 MB).
+ * localStorage has a ~5–10 MB limit per origin in most browsers.
+ *
+ * @example
+ * ```ts
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new LocalStorageBackend({ namespace: "my-project" }),
+ * });
+ * ```
+ */
+export declare class LocalStorageBackend extends WebStorageBackend {
+    constructor(opts?: LocalStorageBackendOptions);
+}

package/dist/backends/local-storage.js

@@ -0,0 +1,19 @@
+import { WebStorageBackend } from "./web-storage.js";
+/**
+ * VFS backend that persists files to localStorage.
+ *
+ * Simple and synchronous — good for small projects (< 5 MB).
+ * localStorage has a ~5–10 MB limit per origin in most browsers.
+ *
+ * @example
+ * ```ts
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new LocalStorageBackend({ namespace: "my-project" }),
+ * });
+ * ```
+ */
+export class LocalStorageBackend extends WebStorageBackend {
+    constructor(opts) {
+        super(localStorage, opts);
+    }
+}

package/dist/backends/memory.d.ts

@@ -0,0 +1,21 @@
+import type { VFSBackend, VFSHost } from "../vfs.js";
+/**
+ * Ephemeral VFS backend — no persistence.
+ *
+ * Files exist only in the WASM memory and are lost on page reload.
+ * Use this when you don't need persistence, or for testing.
+ *
+ * @example
+ * ```ts
+ * import { SemaInterpreter, MemoryBackend } from "@sema-lang/sema";
+ *
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new MemoryBackend(),
+ * });
+ * ```
+ */
+export declare class MemoryBackend implements VFSBackend {
+    hydrate(_host: VFSHost): Promise<void>;
+    flush(_host: VFSHost): Promise<void>;
+    reset(): Promise<void>;
+}

package/dist/backends/memory.js

@@ -0,0 +1,20 @@
+/**
+ * Ephemeral VFS backend — no persistence.
+ *
+ * Files exist only in the WASM memory and are lost on page reload.
+ * Use this when you don't need persistence, or for testing.
+ *
+ * @example
+ * ```ts
+ * import { SemaInterpreter, MemoryBackend } from "@sema-lang/sema";
+ *
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new MemoryBackend(),
+ * });
+ * ```
+ */
+export class MemoryBackend {
+    async hydrate(_host) { }
+    async flush(_host) { }
+    async reset() { }
+}

package/dist/backends/session-storage.d.ts

@@ -0,0 +1,24 @@
+import { WebStorageBackend } from "./web-storage.js";
+import type { WebStorageBackendOptions } from "./web-storage.js";
+/** Options for SessionStorageBackend. */
+export type SessionStorageBackendOptions = WebStorageBackendOptions;
+/**
+ * VFS backend that persists files to sessionStorage.
+ *
+ * Data persists within the current browser tab/window session only —
+ * it is cleared when the tab is closed.  Works well for scratch pads,
+ * playground-style editors, or any context where cross-session
+ * persistence is unnecessary.
+ *
+ * Like {@link LocalStorageBackend}, the ~5–10 MB per-origin limit applies.
+ *
+ * @example
+ * ```ts
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new SessionStorageBackend({ namespace: "playground" }),
+ * });
+ * ```
+ */
+export declare class SessionStorageBackend extends WebStorageBackend {
+    constructor(opts?: SessionStorageBackendOptions);
+}

package/dist/backends/session-storage.js

@@ -0,0 +1,23 @@
+import { WebStorageBackend } from "./web-storage.js";
+/**
+ * VFS backend that persists files to sessionStorage.
+ *
+ * Data persists within the current browser tab/window session only —
+ * it is cleared when the tab is closed.  Works well for scratch pads,
+ * playground-style editors, or any context where cross-session
+ * persistence is unnecessary.
+ *
+ * Like {@link LocalStorageBackend}, the ~5–10 MB per-origin limit applies.
+ *
+ * @example
+ * ```ts
+ * const sema = await SemaInterpreter.create({
+ *   vfs: new SessionStorageBackend({ namespace: "playground" }),
+ * });
+ * ```
+ */
+export class SessionStorageBackend extends WebStorageBackend {
+    constructor(opts) {
+        super(sessionStorage, opts);
+    }
+}

package/dist/backends/web-storage.d.ts

@@ -0,0 +1,32 @@
+import type { VFSBackend, VFSHost } from "../vfs.js";
+/** Options for WebStorageBackend and its subclasses. */
+export interface WebStorageBackendOptions {
+    /**
+     * Namespace prefix for storage keys.
+     * Each file is stored as `${namespace}:f:${path}`.
+     * Directories are stored in a manifest key `${namespace}:__dirs__`.
+     * @default "sema-vfs"
+     */
+    namespace?: string;
+}
+/**
+ * Base class for VFS backends backed by a Web Storage API (`Storage`) object.
+ *
+ * Handles hydrate/flush/reset using namespace-prefixed keys and a directory
+ * manifest.  Subclasses only need to pass the concrete `Storage` instance
+ * (e.g. `localStorage` or `sessionStorage`).
+ */
+export declare class WebStorageBackend implements VFSBackend {
+    private storage;
+    private ns;
+    private filePrefix;
+    private dirsKey;
+    constructor(storage: Storage, opts?: WebStorageBackendOptions);
+    hydrate(host: VFSHost): Promise<void>;
+    flush(host: VFSHost): Promise<void>;
+    reset(): Promise<void>;
+    /** Recursively collect all file paths. */
+    private collectFiles;
+    /** Recursively collect all directory paths. */
+    private collectDirs;
+}

package/dist/backends/web-storage.js

@@ -0,0 +1,103 @@
+/**
+ * Base class for VFS backends backed by a Web Storage API (`Storage`) object.
+ *
+ * Handles hydrate/flush/reset using namespace-prefixed keys and a directory
+ * manifest.  Subclasses only need to pass the concrete `Storage` instance
+ * (e.g. `localStorage` or `sessionStorage`).
+ */
+export class WebStorageBackend {
+    constructor(storage, opts) {
+        this.storage = storage;
+        this.ns = opts?.namespace ?? "sema-vfs";
+        this.filePrefix = this.ns + ":f:";
+        this.dirsKey = this.ns + ":__dirs__";
+    }
+    async hydrate(host) {
+        // Restore directories first (so file writes into them work)
+        const dirsJson = this.storage.getItem(this.dirsKey);
+        if (dirsJson) {
+            try {
+                const dirs = JSON.parse(dirsJson);
+                for (const dir of dirs) {
+                    host.mkdir(dir);
+                }
+            }
+            catch { /* ignore corrupt data */ }
+        }
+        // Restore files
+        for (let i = 0; i < this.storage.length; i++) {
+            const key = this.storage.key(i);
+            if (key && key.startsWith(this.filePrefix)) {
+                const path = key.slice(this.filePrefix.length);
+                const content = this.storage.getItem(key);
+                if (content !== null) {
+                    host.writeFile(path, content);
+                }
+            }
+        }
+    }
+    async flush(host) {
+        // Clear old entries for this namespace
+        const toRemove = [];
+        for (let i = 0; i < this.storage.length; i++) {
+            const key = this.storage.key(i);
+            if (key && (key.startsWith(this.filePrefix) || key === this.dirsKey)) {
+                toRemove.push(key);
+            }
+        }
+        for (const key of toRemove) {
+            this.storage.removeItem(key);
+        }
+        // Write current files
+        const allFiles = this.collectFiles(host, "/");
+        for (const path of allFiles) {
+            const content = host.readFile(path);
+            if (content !== null) {
+                this.storage.setItem(this.filePrefix + path, content);
+            }
+        }
+        // Write directory manifest
+        const dirs = this.collectDirs(host, "/");
+        this.storage.setItem(this.dirsKey, JSON.stringify(dirs));
+    }
+    async reset() {
+        const toRemove = [];
+        for (let i = 0; i < this.storage.length; i++) {
+            const key = this.storage.key(i);
+            if (key && (key.startsWith(this.filePrefix) || key === this.dirsKey)) {
+                toRemove.push(key);
+            }
+        }
+        for (const key of toRemove) {
+            this.storage.removeItem(key);
+        }
+    }
+    /** Recursively collect all file paths. */
+    collectFiles(host, dir) {
+        const result = [];
+        const entries = host.listFiles(dir);
+        for (const name of entries) {
+            const full = dir === "/" ? "/" + name : dir + "/" + name;
+            if (host.isDirectory(full)) {
+                result.push(...this.collectFiles(host, full));
+            }
+            else {
+                result.push(full);
+            }
+        }
+        return result;
+    }
+    /** Recursively collect all directory paths. */
+    collectDirs(host, dir) {
+        const result = [];
+        const entries = host.listFiles(dir);
+        for (const name of entries) {
+            const full = dir === "/" ? "/" + name : dir + "/" + name;
+            if (host.isDirectory(full)) {
+                result.push(full);
+                result.push(...this.collectDirs(host, full));
+            }
+        }
+        return result;
+    }
+}