logisheets-runtime 1.9.0 → 1.11.0

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';
@@ -31,6 +49,23 @@ export declare class Workbook {
     constructor(bookId: number, path?: string);
     /** Read a single cell's evaluated value. */
     getValue(sheetIdx: number, row: number, col: number): Value;
+    /**
+     * Serialize the workbook back to .xlsx bytes.
+     *
+     * `saveWorkbook` is deliberately absent from {@link Client}: it is a
+     * whole-file operation rather than one of the per-cell/per-sheet
+     * `WorkbookMethods`, so it goes straight through the engine entry here.
+     *
+     * @param appData opaque per-document JSON the host owns (craft state and
+     *                friends). It round-trips through the file; pass what the
+     *                engine's `getAppData` gave you, or nothing.
+     */
+    save(appData?: string): Uint8Array;
+    /**
+     * Serialize and write the workbook to `path`. Defaults to the path it was
+     * loaded from, so a load -> edit -> `saveAs()` round-trip needs no argument.
+     */
+    saveAs(path?: string, appData?: string): Promise<void>;
     /** Undo the most recent transaction. Returns whether anything was undone. */
     undo(): Promise<boolean>;
     /** Redo the most recently undone transaction. Returns whether anything was redone. */

package/dist/index.js

@@ -10,12 +10,44 @@
 // 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 { readFile, writeFile } 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.
@@ -66,6 +98,38 @@ export class Workbook {
     getValue(sheetIdx, row, col) {
         return handle({ method: 'getValue', value: { sheetIdx, row, col } }, this.id);
     }
+    /**
+     * Serialize the workbook back to .xlsx bytes.
+     *
+     * `saveWorkbook` is deliberately absent from {@link Client}: it is a
+     * whole-file operation rather than one of the per-cell/per-sheet
+     * `WorkbookMethods`, so it goes straight through the engine entry here.
+     *
+     * @param appData opaque per-document JSON the host owns (craft state and
+     *                friends). It round-trips through the file; pass what the
+     *                engine's `getAppData` gave you, or nothing.
+     */
+    save(appData = '') {
+        const r = handle({ method: 'saveWorkbook', value: { appData } }, this.id);
+        if (r.code !== 0) {
+            throw new Error(`failed to save workbook (code ${r.code})`);
+        }
+        // The wasm boundary hands back either a typed array or a plain number
+        // array depending on the serializer path; normalize so callers can
+        // always treat this as bytes.
+        return r.data instanceof Uint8Array ? r.data : Uint8Array.from(r.data);
+    }
+    /**
+     * Serialize and write the workbook to `path`. Defaults to the path it was
+     * loaded from, so a load -> edit -> `saveAs()` round-trip needs no argument.
+     */
+    async saveAs(path, appData = '') {
+        const target = path ?? this.path;
+        if (target === undefined) {
+            throw new Error('saveAs: no path given and this workbook was not loaded from one');
+        }
+        await writeFile(resolve(target), this.save(appData));
+    }
     /** Undo the most recent transaction. Returns whether anything was undone. */
     async undo() {
         return (await this.client.undo()) === true;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-runtime",
-    "version": "1.9.0",
+    "version": "1.11.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",
@@ -17,12 +17,34 @@
     ],
     "author": "Jeremy He",
     "license": "MIT",
+    "keywords": [
+        "spreadsheet",
+        "xlsx",
+        "excel",
+        "headless",
+        "nodejs",
+        "server",
+        "wasm",
+        "rust",
+        "formula",
+        "workbook"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/logisky/LogiSheets.git",
+        "directory": "packages/runtime"
+    },
+    "bugs": {
+        "url": "https://github.com/logisky/LogiSheets/issues"
+    },
+    "homepage": "https://github.com/logisky/LogiSheets",
     "dependencies": {
-        "logisheets": "^1.9.0",
-        "logisheets-core": "^1.9.0"
+        "logisheets": "^1.11.0",
+        "logisheets-core": "^1.11.0"
     },
     "devDependencies": {
-        "typescript": "^5.5.0",
+        "@types/node": "^18",
+        "typescript": "^6.0.0",
         "vitest": "3.2.6"
     }
 }