logisheets-runtime 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import type { Value, Client } from 'logisheets-web';
+import { WorkbookOps } from 'logisheets-core';
+export * from 'logisheets-core';
+export * from './rpc.js';
+/**
+ * A single live workbook in the Node WASM engine, with logisheets-core's logic
+ * available as methods. You don't construct one directly — obtain it from
+ * {@link SpreadsheetRuntime.createWorkbook} or
+ * {@link SpreadsheetRuntime.loadWorkbook}, then run every operation against
+ * this handle so the target workbook is always explicit.
+ */
+export declare class Workbook {
+    /** The workbook's engine id (unique across the whole process). */
+    readonly id: number;
+    /** The shared, engine-neutral operation layer, bound to this workbook. */
+    readonly ops: WorkbookOps;
+    /**
+     * The raw async {@link Client} bound to this workbook — every
+     * `WorkbookMethods` call mapped onto the Node engine. This is the
+     * last-resort escape hatch: prefer {@link ops}, but when an operation has
+     * no `WorkbookOps` method yet, you can drive the engine directly here.
+     */
+    readonly client: Client;
+    /** Absolute path this workbook was loaded from, if any. */
+    readonly path?: string;
+    private released;
+    /** @internal Construct via {@link SpreadsheetRuntime}. */
+    constructor(bookId: number, path?: string);
+    /** Read a single cell's evaluated value. */
+    getValue(sheetIdx: number, row: number, col: number): Value;
+    /** Undo the most recent transaction. Returns whether anything was undone. */
+    undo(): Promise<boolean>;
+    /** Redo the most recently undone transaction. Returns whether anything was redone. */
+    redo(): Promise<boolean>;
+    /**
+     * Drop the undo/redo history, keeping the current state as the baseline.
+     * Nothing is reverted — only the history is cleared (bounds memory and
+     * makes prior changes permanent).
+     */
+    cleanHistory(): Promise<void>;
+    /**
+     * Revert every change still on the undo stack, returning the workbook to
+     * its current baseline. Assumes the history was clean at the baseline (the
+     * mutation lifecycle in {@link RpcServer.registerMutation} guarantees this),
+     * so it undoes exactly the changes made since.
+     */
+    discardChanges(): Promise<void>;
+    /** @internal Release engine resources. Use {@link SpreadsheetRuntime.close}. */
+    release(): void;
+}
+/**
+ * The headless runtime: a container for many open {@link Workbook}s. Create one
+ * per Node process, then load or create as many workbooks as you need — each
+ * operation is issued against the specific workbook handle you hold.
+ *
+ * ```ts
+ * const rt = new SpreadsheetRuntime()
+ * const wb1 = await rt.loadWorkbook('a.xlsx')
+ * const wb2 = await rt.loadWorkbook('b.xlsx')
+ * const wb3 = rt.createWorkbook()
+ * await wb1.ops.inputCell(0, 0, 0, 'hi')
+ * ```
+ */
+export declare class SpreadsheetRuntime {
+    /** Loaded-from-disk workbooks, keyed by absolute path, for dedup. */
+    private readonly byPath;
+    /** Every open workbook this runtime owns. */
+    private readonly open;
+    /** Create a new empty workbook. */
+    createWorkbook(): Workbook;
+    /**
+     * Load a workbook from a .xlsx file on disk. Calling this twice with the
+     * same path returns the already-loaded {@link Workbook} rather than
+     * reloading — {@link close} it to release the engine and clear the entry.
+     */
+    loadWorkbook(path: string): Promise<Workbook>;
+    /**
+     * Load a workbook from raw .xlsx bytes already in memory.
+     *
+     * @param name file name used by the engine (e.g. for the workbook title)
+     */
+    loadWorkbookFromBytes(content: Uint8Array, name: string, path?: string): Workbook;
+    /** All workbooks currently open in this runtime. */
+    get workbooks(): readonly Workbook[];
+    /** Close one workbook, releasing its engine resources. */
+    close(wb: Workbook): void;
+    /** Close every open workbook. */
+    closeAll(): void;
+}

package/dist/index.js

@@ -0,0 +1,176 @@
+// logisheets-runtime — a headless spreadsheet runtime for Node.
+//
+// This is the Node counterpart of the browser app: it wires logisheets-core's
+// (engine-neutral) logic to the Node WASM engine via the injected-Client model.
+// The browser supplies logisheets-engine's worker client; here we supply a
+// synchronous client built on the Node WASM `handle()` entry point.
+//
+// A single {@link SpreadsheetRuntime} owns many {@link Workbook}s at once
+// (wb1, wb2, wb3, …); every operation runs against one specific workbook. All
+// workbook logic lives in logisheets-core's WorkbookOps; the runtime only
+// adapts the synchronous Node `handle()` entry point into the async Client that
+// WorkbookOps consumes, then exposes that ops layer per workbook.
+import { readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { handle } from 'logisheets/wasm/logisheets_wasm_server.js';
+import { WorkbookOps } from 'logisheets-core';
+// Re-export the core surface so consumers import everything from one place.
+export * from 'logisheets-core';
+// The developer-defined JSON-RPC server (operations run against this runtime).
+export * from './rpc.js';
+/**
+ * Adapt the synchronous Node `handle()` entry point into the async {@link
+ * Client} that logisheets-core's operation layer expects.
+ *
+ * Every WorkbookMethods call has the shape `client.method(params)` and maps
+ * 1:1 onto `handle({method, value: params}, bookId)`, so a single generic
+ * Proxy covers the whole interface — no per-method boilerplate. Results are
+ * wrapped in a resolved Promise so a Node caller can `await` exactly like the
+ * browser. The callback/register* members are not used by the operation layer
+ * and are intentionally absent.
+ */
+function makeNodeClient(bookId) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            const method = String(prop);
+            return (params) => Promise.resolve(handle(params === undefined
+                ? method
+                : { method, value: params }, bookId));
+        },
+    });
+}
+/**
+ * A single live workbook in the Node WASM engine, with logisheets-core's logic
+ * available as methods. You don't construct one directly — obtain it from
+ * {@link SpreadsheetRuntime.createWorkbook} or
+ * {@link SpreadsheetRuntime.loadWorkbook}, then run every operation against
+ * this handle so the target workbook is always explicit.
+ */
+export class Workbook {
+    /** @internal Construct via {@link SpreadsheetRuntime}. */
+    constructor(bookId, path) {
+        this.released = false;
+        this.id = bookId;
+        this.client = makeNodeClient(bookId);
+        this.ops = new WorkbookOps(this.client);
+        this.path = path;
+    }
+    /** Read a single cell's evaluated value. */
+    getValue(sheetIdx, row, col) {
+        return handle({ method: 'getValue', value: { sheetIdx, row, col } }, this.id);
+    }
+    /** Undo the most recent transaction. Returns whether anything was undone. */
+    async undo() {
+        return (await this.client.undo()) === true;
+    }
+    /** Redo the most recently undone transaction. Returns whether anything was redone. */
+    async redo() {
+        return (await this.client.redo()) === true;
+    }
+    /**
+     * Drop the undo/redo history, keeping the current state as the baseline.
+     * Nothing is reverted — only the history is cleared (bounds memory and
+     * makes prior changes permanent).
+     */
+    async cleanHistory() {
+        await this.client.cleanHistory();
+    }
+    /**
+     * Revert every change still on the undo stack, returning the workbook to
+     * its current baseline. Assumes the history was clean at the baseline (the
+     * mutation lifecycle in {@link RpcServer.registerMutation} guarantees this),
+     * so it undoes exactly the changes made since.
+     */
+    async discardChanges() {
+        // eslint-disable-next-line no-await-in-loop
+        while ((await this.client.undo()) === true) {
+            /* keep undoing until the stack is empty */
+        }
+    }
+    /** @internal Release engine resources. Use {@link SpreadsheetRuntime.close}. */
+    release() {
+        if (this.released)
+            return;
+        this.released = true;
+        handle('release', this.id);
+    }
+}
+/**
+ * The headless runtime: a container for many open {@link Workbook}s. Create one
+ * per Node process, then load or create as many workbooks as you need — each
+ * operation is issued against the specific workbook handle you hold.
+ *
+ * ```ts
+ * const rt = new SpreadsheetRuntime()
+ * const wb1 = await rt.loadWorkbook('a.xlsx')
+ * const wb2 = await rt.loadWorkbook('b.xlsx')
+ * const wb3 = rt.createWorkbook()
+ * await wb1.ops.inputCell(0, 0, 0, 'hi')
+ * ```
+ */
+export class SpreadsheetRuntime {
+    constructor() {
+        /** Loaded-from-disk workbooks, keyed by absolute path, for dedup. */
+        this.byPath = new Map();
+        /** Every open workbook this runtime owns. */
+        this.open = new Set();
+    }
+    /** Create a new empty workbook. */
+    createWorkbook() {
+        const wb = new Workbook(handle('newWorkbook'));
+        this.open.add(wb);
+        return wb;
+    }
+    /**
+     * Load a workbook from a .xlsx file on disk. Calling this twice with the
+     * same path returns the already-loaded {@link Workbook} rather than
+     * reloading — {@link close} it to release the engine and clear the entry.
+     */
+    async loadWorkbook(path) {
+        const key = resolve(path);
+        const existing = this.byPath.get(key);
+        if (existing)
+            return existing;
+        const content = await readFile(key);
+        const wb = this.loadWorkbookFromBytes(content, basename(key), key);
+        this.byPath.set(key, wb);
+        return wb;
+    }
+    /**
+     * Load a workbook from raw .xlsx bytes already in memory.
+     *
+     * @param name file name used by the engine (e.g. for the workbook title)
+     */
+    loadWorkbookFromBytes(content, name, path) {
+        const bookId = handle('newWorkbook');
+        // The engine's deserializer expects a plain number array, not a
+        // typed array / Buffer — mirror the browser SDK's `Array.from(buf)`.
+        const code = handle({
+            method: 'loadWorkbook',
+            value: { content: Array.from(content), name },
+        }, bookId);
+        if (code !== 0) {
+            handle('release', bookId);
+            throw new Error(`failed to load workbook "${name}" (code ${code})`);
+        }
+        const wb = new Workbook(bookId, path);
+        this.open.add(wb);
+        return wb;
+    }
+    /** All workbooks currently open in this runtime. */
+    get workbooks() {
+        return [...this.open];
+    }
+    /** Close one workbook, releasing its engine resources. */
+    close(wb) {
+        this.open.delete(wb);
+        if (wb.path !== undefined)
+            this.byPath.delete(wb.path);
+        wb.release();
+    }
+    /** Close every open workbook. */
+    closeAll() {
+        for (const wb of [...this.open])
+            this.close(wb);
+    }
+}

package/dist/rpc.d.ts

@@ -0,0 +1,87 @@
+import { type IncomingMessage } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { SpreadsheetRuntime, Workbook } from './index.js';
+export declare const RPC_PARSE_ERROR = -32700;
+export declare const RPC_INVALID_REQUEST = -32600;
+export declare const RPC_METHOD_NOT_FOUND = -32601;
+export declare const RPC_INVALID_PARAMS = -32602;
+export declare const RPC_INTERNAL_ERROR = -32603;
+/** Context handed to every RPC method: the runtime that owns the workbooks. */
+export interface RpcContext {
+    readonly runtime: SpreadsheetRuntime;
+    /** The raw HTTP request, for headers/auth if a method needs it. */
+    readonly request: IncomingMessage;
+}
+/**
+ * A developer-defined RPC method. Receives the request's `params` and a
+ * {@link RpcContext}, and returns (sync or async) the result to serialize back.
+ * Throw {@link RpcError} to return a structured JSON-RPC error.
+ */
+export type RpcMethod<P = any, R = unknown> = (params: P, ctx: RpcContext) => R | Promise<R>;
+/** Picks (or creates/loads) the workbook a mutation method operates on. */
+export type WorkbookResolver<P = any> = (params: P, ctx: RpcContext) => Workbook | Promise<Workbook>;
+/** The body of a mutation method, run against the resolved workbook. */
+export type MutationRun<P = any, R = unknown> = (workbook: Workbook, params: P, ctx: RpcContext) => R | Promise<R>;
+export interface MutationOptions {
+    /**
+     * Whether changes are persisted when the caller omits the `save` flag from
+     * the request params. Defaults to `true`.
+     */
+    saveByDefault?: boolean;
+}
+/**
+ * Reserved request param read by {@link RpcServer.registerMutation}: a boolean
+ * deciding whether the call's changes are kept (`true`) or rolled back
+ * (`false`). Either way the workbook's history is cleaned afterwards.
+ */
+export declare const SAVE_PARAM = "save";
+/** Throw this from a method to return a specific JSON-RPC error to the caller. */
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/**
+ * JSON-RPC 2.0 server over HTTP. Construct with a {@link SpreadsheetRuntime},
+ * {@link register} methods, then {@link listen}. All registered methods run
+ * against that one runtime, so they share its open workbooks.
+ */
+export declare class RpcServer {
+    readonly runtime: SpreadsheetRuntime;
+    private readonly methods;
+    private server?;
+    constructor(runtime: SpreadsheetRuntime);
+    /**
+     * Register an RPC method. The name must be unique. Returns `this` so
+     * registrations can be chained.
+     */
+    register<P = any, R = unknown>(method: string, handler: RpcMethod<P, R>): this;
+    /**
+     * Register a *mutating* RPC method that reads/writes a workbook. The
+     * framework wraps the body with a save lifecycle:
+     *
+     *  1. resolve the target workbook from the params (`target`),
+     *  2. clear its history so the baseline is clean,
+     *  3. run the body (`run`),
+     *  4. read the boolean `{@link SAVE_PARAM}` from the params — if it is
+     *     `false`, roll back every change the body made,
+     *  5. clear the workbook's history again.
+     *
+     * So callers control persistence per call via a `save` param (default
+     * {@link MutationOptions.saveByDefault}, itself defaulting to `true`), and
+     * the workbook never accumulates history across requests either way.
+     */
+    registerMutation<P = any, R = unknown>(method: string, target: WorkbookResolver<P>, run: MutationRun<P, R>, options?: MutationOptions): this;
+    /** Whether a method name is registered. */
+    has(method: string): boolean;
+    /**
+     * Start listening. Resolves with the bound address once the socket is open.
+     * Defaults to loopback (`127.0.0.1`); pass `'0.0.0.0'` to accept external
+     * connections. Use port `0` for an OS-assigned ephemeral port.
+     */
+    listen(port: number, host?: string): Promise<AddressInfo>;
+    /** Stop listening. Does not close the runtime's workbooks. */
+    close(): Promise<void>;
+    private onRequest;
+    private dispatch;
+}

package/dist/rpc.js

@@ -0,0 +1,235 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// A tiny, dependency-free JSON-RPC 2.0 server for the runtime.
+//
+// The framework here is generic: it owns the wire protocol (HTTP + JSON-RPC
+// 2.0 envelope, dispatch, error mapping) but knows nothing about which methods
+// exist. Developers define their own RPC methods — the params and the body are
+// theirs — where the body reads/writes workbooks through the injected
+// {@link SpreadsheetRuntime}. They `register()` each method, then `listen()`.
+//
+//   const rt = new SpreadsheetRuntime()
+//   const server = new RpcServer(rt)
+//   server.register('openSheet', async ({path}, {runtime}) => {
+//       const wb = await runtime.loadWorkbook(path)
+//       return {sheets: await wb.client.getAllSheetInfo()}
+//   })
+//   server.register('readCell', (p, {runtime}) => {
+//       const wb = runtime.workbooks.find((w) => w.path === p.path)
+//       if (!wb) throw new RpcError(RPC_INVALID_PARAMS, 'workbook not loaded')
+//       return wb.getValue(p.sheet, p.row, p.col)
+//   })
+//   const addr = await server.listen(3000)
+import { createServer, } from 'node:http';
+// Standard JSON-RPC 2.0 error codes. Developers can also throw {@link RpcError}
+// with their own (positive) application codes.
+export const RPC_PARSE_ERROR = -32700;
+export const RPC_INVALID_REQUEST = -32600;
+export const RPC_METHOD_NOT_FOUND = -32601;
+export const RPC_INVALID_PARAMS = -32602;
+export const RPC_INTERNAL_ERROR = -32603;
+/**
+ * Reserved request param read by {@link RpcServer.registerMutation}: a boolean
+ * deciding whether the call's changes are kept (`true`) or rolled back
+ * (`false`). Either way the workbook's history is cleaned afterwards.
+ */
+export const SAVE_PARAM = 'save';
+/** Throw this from a method to return a specific JSON-RPC error to the caller. */
+export class RpcError extends Error {
+    constructor(code, message, data) {
+        super(message);
+        this.name = 'RpcError';
+        this.code = code;
+        this.data = data;
+    }
+}
+/**
+ * JSON-RPC 2.0 server over HTTP. Construct with a {@link SpreadsheetRuntime},
+ * {@link register} methods, then {@link listen}. All registered methods run
+ * against that one runtime, so they share its open workbooks.
+ */
+export class RpcServer {
+    constructor(runtime) {
+        this.methods = new Map();
+        this.runtime = runtime;
+    }
+    /**
+     * Register an RPC method. The name must be unique. Returns `this` so
+     * registrations can be chained.
+     */
+    register(method, handler) {
+        if (this.methods.has(method))
+            throw new Error(`duplicate RPC method "${method}"`);
+        this.methods.set(method, handler);
+        return this;
+    }
+    /**
+     * Register a *mutating* RPC method that reads/writes a workbook. The
+     * framework wraps the body with a save lifecycle:
+     *
+     *  1. resolve the target workbook from the params (`target`),
+     *  2. clear its history so the baseline is clean,
+     *  3. run the body (`run`),
+     *  4. read the boolean `{@link SAVE_PARAM}` from the params — if it is
+     *     `false`, roll back every change the body made,
+     *  5. clear the workbook's history again.
+     *
+     * So callers control persistence per call via a `save` param (default
+     * {@link MutationOptions.saveByDefault}, itself defaulting to `true`), and
+     * the workbook never accumulates history across requests either way.
+     */
+    registerMutation(method, target, run, options = {}) {
+        const saveByDefault = options.saveByDefault ?? true;
+        return this.register(method, async (params, ctx) => {
+            const wb = await target(params, ctx);
+            await wb.cleanHistory();
+            const result = await run(wb, params, ctx);
+            if (!readSaveFlag(params, saveByDefault))
+                await wb.discardChanges();
+            await wb.cleanHistory();
+            return result ?? null;
+        });
+    }
+    /** Whether a method name is registered. */
+    has(method) {
+        return this.methods.has(method);
+    }
+    /**
+     * Start listening. Resolves with the bound address once the socket is open.
+     * Defaults to loopback (`127.0.0.1`); pass `'0.0.0.0'` to accept external
+     * connections. Use port `0` for an OS-assigned ephemeral port.
+     */
+    listen(port, host = '127.0.0.1') {
+        if (this.server)
+            throw new Error('server already listening');
+        const server = createServer((req, res) => this.onRequest(req, res));
+        this.server = server;
+        return new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(port, host, () => {
+                server.removeListener('error', reject);
+                resolve(server.address());
+            });
+        });
+    }
+    /** Stop listening. Does not close the runtime's workbooks. */
+    close() {
+        const server = this.server;
+        if (!server)
+            return Promise.resolve();
+        this.server = undefined;
+        return new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
+    }
+    async onRequest(req, res) {
+        if (req.method !== 'POST') {
+            res.writeHead(405, { Allow: 'POST' }).end();
+            return;
+        }
+        let body;
+        try {
+            body = JSON.parse(await readBody(req));
+        }
+        catch {
+            return send(res, 200, {
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: RPC_PARSE_ERROR, message: 'parse error' },
+            });
+        }
+        // A JSON-RPC batch is an array; a single call is an object.
+        if (Array.isArray(body)) {
+            if (body.length === 0)
+                return send(res, 200, invalidRequest(null));
+            const responses = (await Promise.all(body.map((m) => this.dispatch(m, req)))).filter((r) => r !== null);
+            // All-notification batch -> no content per spec.
+            if (responses.length === 0)
+                return void res.writeHead(204).end();
+            return send(res, 200, responses);
+        }
+        const response = await this.dispatch(body, req);
+        if (response === null)
+            return void res.writeHead(204).end();
+        send(res, 200, response);
+    }
+    // Returns null for notifications (no `id`), which get no response.
+    async dispatch(msg, req) {
+        if (!isObject(msg) ||
+            msg.jsonrpc !== '2.0' ||
+            typeof msg.method !== 'string') {
+            const id = isObject(msg) ? toId(msg.id) : null;
+            return invalidRequest(id);
+        }
+        const request = msg;
+        const isNotification = !('id' in msg) || msg.id === undefined;
+        const id = toId(request.id);
+        const handler = this.methods.get(request.method);
+        if (!handler) {
+            return isNotification
+                ? null
+                : {
+                    jsonrpc: '2.0',
+                    id,
+                    error: {
+                        code: RPC_METHOD_NOT_FOUND,
+                        message: `method not found: ${request.method}`,
+                    },
+                };
+        }
+        try {
+            const result = await handler(request.params, {
+                runtime: this.runtime,
+                request: req,
+            });
+            // JSON-RPC success responses must carry a `result` member;
+            // `void` handlers return undefined, so normalize it to null.
+            return isNotification
+                ? null
+                : { jsonrpc: '2.0', id, result: result ?? null };
+        }
+        catch (e) {
+            if (isNotification)
+                return null;
+            const error = e instanceof RpcError
+                ? { code: e.code, message: e.message, data: e.data }
+                : {
+                    code: RPC_INTERNAL_ERROR,
+                    message: e instanceof Error ? e.message : String(e),
+                };
+            return { jsonrpc: '2.0', id, error };
+        }
+    }
+}
+function invalidRequest(id) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: RPC_INVALID_REQUEST, message: 'invalid request' },
+    };
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// Read the reserved `save` boolean from a mutation's params, falling back to
+// the method's default when absent or not a boolean.
+function readSaveFlag(params, dflt) {
+    if (isObject(params) && typeof params[SAVE_PARAM] === 'boolean')
+        return params[SAVE_PARAM];
+    return dflt;
+}
+function toId(id) {
+    return typeof id === 'string' || typeof id === 'number' ? id : null;
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function send(res, status, payload) {
+    const body = JSON.stringify(payload);
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+    }).end(body);
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "logisheets-runtime",
+    "version": "1.1.0",
+    "description": "Headless LogiSheets spreadsheet runtime for Node — logisheets-core wired to the Node WASM engine. The Node counterpart of the browser app.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run"
+    },
+    "files": [
+        "dist"
+    ],
+    "author": "Jeremy He",
+    "license": "MIT",
+    "dependencies": {
+        "logisheets": "workspace:*",
+        "logisheets-core": "workspace:*"
+    },
+    "devDependencies": {
+        "typescript": "^5.5.0",
+        "vitest": "^2.0.0"
+    }
+}