logisheets-runtime 1.8.0 → 1.10.0

package/README.md

@@ -0,0 +1,88 @@
+# logisheets-runtime
+
+A **headless LogiSheets spreadsheet runtime for Node** — the Node counterpart of
+the browser app. It wires the engine-neutral logic in
+[`logisheets-core`](https://www.npmjs.com/package/logisheets-core) to the Node
+WASM engine, so you can read, manipulate, and write real `.xlsx` files on the
+server with no browser and no UI.
+
+A single `SpreadsheetRuntime` owns many open workbooks at once; every operation
+runs against a specific `Workbook` handle. All workbook logic comes from
+`logisheets-core`'s `WorkbookOps` — the runtime only adapts the synchronous Node
+`handle()` entry point into the async `Client` that layer expects.
+
+## Installation
+
+```bash
+npm install logisheets-runtime
+```
+
+It pulls in `logisheets` (the Node WASM engine) and `logisheets-core`. ESM-only;
+requires a recent Node with WASM support.
+
+## Quick start
+
+```ts
+import {SpreadsheetRuntime} from 'logisheets-runtime'
+
+const rt = new SpreadsheetRuntime()
+
+// Open workbooks from disk, from bytes, or create empty ones.
+const wb1 = await rt.loadWorkbook('a.xlsx')
+const wb2 = rt.createWorkbook()
+
+// Drive edits through the shared core operation layer.
+await wb1.ops.inputCell(0, 0, 0, 'Hello')   // sheet 0, cell A1
+await wb1.ops.createSheet(1, 'Summary')
+
+// Read evaluated values straight off the handle.
+const v = wb1.getValue(0, 0, 0)
+
+// Undo / redo history is per workbook.
+await wb1.undo()
+await wb1.redo()
+
+// Release engine resources when done.
+rt.close(wb1)
+rt.closeAll()
+```
+
+## `SpreadsheetRuntime`
+
+| Member | Description |
+|--------|-------------|
+| `createWorkbook()` | Create a new empty workbook |
+| `loadWorkbook(path)` | Load a `.xlsx` from disk (dedups by absolute path) |
+| `loadWorkbookFromBytes(bytes, name, path?)` | Load a `.xlsx` from raw bytes in memory |
+| `workbooks` | All currently open workbooks |
+| `close(wb)` / `closeAll()` | Release engine resources |
+
+## `Workbook`
+
+Obtain one from the runtime, then run every operation against it so the target
+workbook is always explicit.
+
+| Member | Description |
+|--------|-------------|
+| `id` | The workbook's engine id |
+| `ops` | The shared `WorkbookOps` (cell input, sheets, blocks, styles, …) bound to this workbook |
+| `client` | Raw async `Client` — escape hatch for engine calls not yet on `ops` |
+| `getValue(sheetIdx, row, col)` | Read a single evaluated cell value |
+| `undo()` / `redo()` | Step the history; returns whether anything changed |
+| `cleanHistory()` | Drop history, keeping current state as baseline |
+| `discardChanges()` | Revert every change back to the current baseline |
+
+## Beyond a single process
+
+Everything below is exported from the top-level `logisheets-runtime` entry
+(alongside the full re-exported `logisheets-core` surface), so you import it all
+from one place:
+
+- **RPC** — a JSON-RPC server for issuing operations against the runtime.
+- **Crafts** — headlessly reconstruct the crafts a workbook depends on.
+- **Watcher** — hot-(re)load workbooks from `wb_*.json` descriptors.
+- **Enterprise** — register with the control panel and pull crafts from the enterprise registry.
+
+## License
+
+MIT — part of the [LogiSheets](https://github.com/logisky/LogiSheets) project.

package/dist/enterprise.d.ts

@@ -70,6 +70,26 @@ export interface EnterpriseServerOptions {
     /** rpcCall → handler (e.g. extractIndicators, compute). */
     taskHandlers?: Record<string, TaskHandler>;
 }
+/**
+ * A framework-neutral view of an incoming HTTP request. Lets a non-Node host
+ * (e.g. a Cloudflare Worker `fetch` handler) drive {@link
+ * EnterpriseRuntimeServer.handleRequest} without Node's `IncomingMessage`.
+ * `body` is the ALREADY-PARSED JSON body (POST only; the host owns parsing).
+ */
+export interface RuntimeHttpRequest {
+    method: string;
+    /** URL pathname, e.g. `/task`. */
+    path: string;
+    /** The `Authorization` header value, for the shared-secret gate. */
+    authorization?: string;
+    body?: unknown;
+}
+/** The framework-neutral result of {@link EnterpriseRuntimeServer.handleRequest};
+ *  a `body` of `undefined` means "no content" (write just the status). */
+export interface RuntimeHttpResponse {
+    status: number;
+    body?: unknown;
+}
 export declare class EnterpriseRuntimeServer {
     private readonly runtime;
     private registry?;
@@ -83,6 +103,33 @@ export declare class EnterpriseRuntimeServer {
     listen(port: number, host?: string): Promise<AddressInfo>;
     close(): Promise<void>;
     private authOk;
+    /**
+     * Transport-agnostic request handler: the `/pin` · `/unpin` · `/task` ·
+     * `/status` routing with NO dependency on Node's http types. The Node
+     * server ({@link onRequest}) routes through this, and so can any other host
+     * — e.g. a Cloudflare Worker, which cannot use {@link listen} (Workers have
+     * no listening socket; they're `fetch`-driven):
+     *
+     * ```ts
+     * export default {
+     *   async fetch(request: Request) {
+     *     const url = new URL(request.url)
+     *     const body =
+     *       request.method === 'POST' ? await request.json() : undefined
+     *     const {status, body: out} = await server.handleRequest({
+     *       method: request.method,
+     *       path: url.pathname,
+     *       authorization: request.headers.get('authorization') ?? undefined,
+     *       body,
+     *     })
+     *     return out === undefined
+     *       ? new Response(null, {status})
+     *       : Response.json(out, {status})
+     *   },
+     * }
+     * ```
+     */
+    handleRequest(req: RuntimeHttpRequest): Promise<RuntimeHttpResponse>;
     private loadFromUrl;
     private onRequest;
     private pin;

package/dist/enterprise.js

@@ -161,10 +161,75 @@ export class EnterpriseRuntimeServer {
         this.server = undefined;
         return new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
     }
-    authOk(req) {
+    authOk(authorization) {
         if (!this.secret)
             return true;
-        return req.headers.authorization === `Bearer ${this.secret}`;
+        return authorization === `Bearer ${this.secret}`;
+    }
+    /**
+     * Transport-agnostic request handler: the `/pin` · `/unpin` · `/task` ·
+     * `/status` routing with NO dependency on Node's http types. The Node
+     * server ({@link onRequest}) routes through this, and so can any other host
+     * — e.g. a Cloudflare Worker, which cannot use {@link listen} (Workers have
+     * no listening socket; they're `fetch`-driven):
+     *
+     * ```ts
+     * export default {
+     *   async fetch(request: Request) {
+     *     const url = new URL(request.url)
+     *     const body =
+     *       request.method === 'POST' ? await request.json() : undefined
+     *     const {status, body: out} = await server.handleRequest({
+     *       method: request.method,
+     *       path: url.pathname,
+     *       authorization: request.headers.get('authorization') ?? undefined,
+     *       body,
+     *     })
+     *     return out === undefined
+     *       ? new Response(null, {status})
+     *       : Response.json(out, {status})
+     *   },
+     * }
+     * ```
+     */
+    async handleRequest(req) {
+        if (req.method === 'GET' && req.path === '/status') {
+            if (!this.authOk(req.authorization))
+                return { status: 403, body: { error: 'forbidden' } };
+            return {
+                status: 200,
+                body: {
+                    pins: [...this.pins.keys()],
+                    open: this.runtime.workbooks.length,
+                },
+            };
+        }
+        if (req.method !== 'POST')
+            return { status: 405 };
+        if (!this.authOk(req.authorization))
+            return { status: 403, body: { error: 'forbidden' } };
+        const body = req.body ?? {};
+        try {
+            if (req.path === '/pin')
+                return {
+                    status: 200,
+                    body: await this.pin(body),
+                };
+            if (req.path === '/unpin')
+                return { status: 200, body: this.unpin(body) };
+            if (req.path === '/task')
+                return {
+                    status: 200,
+                    body: await this.task(body),
+                };
+            return { status: 404, body: { error: 'not found' } };
+        }
+        catch (e) {
+            return {
+                status: 500,
+                body: { error: e instanceof Error ? e.message : String(e) },
+            };
+        }
     }
     async loadFromUrl(url) {
         const res = await fetch(url);
@@ -176,29 +241,23 @@ export class EnterpriseRuntimeServer {
             await loadCrafts(wb, this.registry);
         return wb;
     }
+    // Node http transport: parse the request into a framework-neutral shape,
+    // route it through {@link handleRequest}, and write the result back. All
+    // routing/auth lives in handleRequest so non-Node hosts share it verbatim.
     async onRequest(req, res) {
         try {
-            const url = req.url ?? '/';
-            if (req.method === 'GET' && url === '/status') {
-                if (!this.authOk(req))
-                    return json(res, 403, { error: 'forbidden' });
-                return json(res, 200, {
-                    pins: [...this.pins.keys()],
-                    open: this.runtime.workbooks.length,
-                });
-            }
-            if (req.method !== 'POST')
-                return void res.writeHead(405).end();
-            if (!this.authOk(req))
-                return json(res, 403, { error: 'forbidden' });
-            const body = JSON.parse((await readBody(req)) || '{}');
-            if (url === '/pin')
-                return json(res, 200, await this.pin(body));
-            if (url === '/unpin')
-                return json(res, 200, this.unpin(body));
-            if (url === '/task')
-                return json(res, 200, await this.task(body));
-            return json(res, 404, { error: 'not found' });
+            const body = req.method === 'POST'
+                ? JSON.parse((await readBody(req)) || '{}')
+                : undefined;
+            const out = await this.handleRequest({
+                method: req.method ?? 'GET',
+                path: req.url ?? '/',
+                authorization: req.headers.authorization,
+                body,
+            });
+            if (out.body === undefined)
+                return void res.writeHead(out.status).end();
+            json(res, out.status, out.body);
         }
         catch (e) {
             json(res, 500, { error: e instanceof Error ? e.message : String(e) });

package/dist/index.d.ts

@@ -1,6 +1,24 @@
 import type { Value, Client } from 'logisheets-web';
 import { WorkbookOps } from 'logisheets-core';
 export * from 'logisheets-core';
+/** The wasm-bindgen `handle(msg, bookId?)` entry — the single call the whole
+ *  runtime issues against the engine. */
+export type WasmHandle = (msg: unknown, bookId?: number | null) => unknown;
+/**
+ * Inject the wasm `handle` entry. Required on non-Node hosts (Cloudflare
+ * Worker, Deno, browser): initialize the web-target glue with an imported
+ * module and pass its `handle` here BEFORE creating/loading any workbook, e.g.
+ *
+ * ```ts
+ * import wasmModule from 'logisheets-web/wasm/logisheets_wasm_server_bg.wasm'
+ * import {initSync, handle} from 'logisheets-web/wasm/logisheets_wasm_server.js'
+ * initSync({module: wasmModule})
+ * setWasmHandle(handle)
+ * ```
+ *
+ * Optional on Node — the node-target glue is loaded on first use if unset.
+ */
+export declare function setWasmHandle(fn: WasmHandle): void;
 export * from './rpc.js';
 export * from './craft.js';
 export * from './watcher.js';

package/dist/index.js

@@ -12,10 +12,42 @@
 // 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 { createRequire } from 'node:module';
 import { WorkbookOps } from 'logisheets-core';
 // Re-export the core surface so consumers import everything from one place.
 export * from 'logisheets-core';
+let handleImpl;
+/**
+ * Inject the wasm `handle` entry. Required on non-Node hosts (Cloudflare
+ * Worker, Deno, browser): initialize the web-target glue with an imported
+ * module and pass its `handle` here BEFORE creating/loading any workbook, e.g.
+ *
+ * ```ts
+ * import wasmModule from 'logisheets-web/wasm/logisheets_wasm_server_bg.wasm'
+ * import {initSync, handle} from 'logisheets-web/wasm/logisheets_wasm_server.js'
+ * initSync({module: wasmModule})
+ * setWasmHandle(handle)
+ * ```
+ *
+ * Optional on Node — the node-target glue is loaded on first use if unset.
+ */
+export function setWasmHandle(fn) {
+    handleImpl = fn;
+}
+// Node fallback: synchronously require the node-target glue (it auto-initializes
+// the wasm from disk on load). Only reached when no handle was injected; a
+// non-Node host injects first, so `createRequire` never runs there.
+function loadNodeHandle() {
+    const require = createRequire(import.meta.url);
+    return require('logisheets/wasm/logisheets_wasm_server.js').handle;
+}
+/** The engine entry the runtime calls; resolves the injected handle (or the
+ *  Node default) on first use. */
+function handle(msg, bookId) {
+    if (handleImpl === undefined)
+        handleImpl = loadNodeHandle();
+    return handleImpl(msg, bookId);
+}
 // The developer-defined JSON-RPC server (operations run against this runtime).
 export * from './rpc.js';
 // Craft loading: reconstruct the crafts a workbook depends on, headlessly.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-runtime",
-    "version": "1.8.0",
+    "version": "1.10.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",
@@ -18,11 +18,12 @@
     "author": "Jeremy He",
     "license": "MIT",
     "dependencies": {
-        "logisheets": "^1.8.0",
-        "logisheets-core": "^1.8.0"
+        "logisheets": "^1.10.0",
+        "logisheets-core": "^1.10.0"
     },
     "devDependencies": {
-        "typescript": "^5.5.0",
-        "vitest": "^2.0.0"
+        "@types/node": "^18",
+        "typescript": "^6.0.0",
+        "vitest": "3.2.6"
     }
 }