swls-wasm 0.3.2-alpha.1 → 0.3.2-alpha.3

package/README.md

@@ -1,86 +1,67 @@
-# SWLS-Web
+# swls-wasm
 
-WASM bindings for the semantic web language server.
+The [Semantic Web Language Server](https://github.com/SemanticWebLanguageServer/swls)
+(Turtle, TriG, SPARQL, JSON-LD) compiled to WebAssembly, plus thin helpers for
+running it as a worker. Built with `wasm-pack --target web`, so it loads in
+browsers, bundlers, Web Workers and Node without any bundler plugins.
 
-As SWLS is not yet published, this package expects SWLS to be present in the parent directory.
+Both directions exchange whole JSON-RPC messages over `postMessage` with **no
+`Content-Length` framing**.
 
-## 🚴 Usage
+## Browser / bundler — `createSwlsWorker()`
 
-### 🛠️ Build with `wasm-pack build`
+The easiest path: get a ready-to-use Web Worker. Works with Vite, webpack, etc.
+(the bundler picks up the worker and its `.wasm` automatically).
 
-```
-wasm-pack build
-```
-
-### 🔬 Test in Headless Browsers with `wasm-pack test`
+```js
+import { createSwlsWorker } from "swls-wasm/client";
 
+const worker = createSwlsWorker();
+// hand `worker` to your editor's LSP client (e.g. swls-codemirror, monaco)
 ```
-wasm-pack test --headless --firefox
-```
-
-### 🎁 Publish to NPM with `wasm-pack publish`
-
-```
-wasm-pack publish
-```
-
-
-## Custom LSP Requests
-
-The WASM LSP server sends custom requests **from server to client** that the host must handle. All requests use `params: { url: string }`.
 
-If a handler is not implemented, the server falls back to a sensible default.
+The worker emits `{ jsonrpc: "2.0", method: "swls/ready" }` once the wasm has
+finished initializing.
 
-### `custom/readFile`
+## From a CDN — no build step
 
-Reads the contents of a file.
+`worker.js` and its sibling `swls_wasm_bg.wasm` are both published, so a worker
+can be loaded straight from a CDN:
 
-```ts
-params:  { url: string }
-result:  { content: string } | { error: string }
+```js
+const worker = new Worker(
+  "https://cdn.jsdelivr.net/npm/swls-wasm@0.3/worker.js",
+  { type: "module" },
+);
 ```
 
-### `custom/readDir`
+The worker resolves `swls_wasm_bg.wasm` relative to its own URL, so it is fetched
+from the same CDN path. Cross-origin module workers need permissive CORS (jsDelivr
+and unpkg send it); Safari is stricter about cross-origin worker scripts, so if you
+need to support it, load a small same-origin bootstrap that `import()`s the CDN URL.
 
-Lists the entries of a directory.
+## Custom host — `createSwlsServer()`
 
-```ts
-params:  { url: string }
-result:  Array<{ name: string; path: string; is_dir: boolean }>
-// fallback: returns null/error → treated as empty
-```
-
-### `custom/isFile`
-
-Returns whether the given URL refers to a file.
-
-```ts
-params:  { url: string }
-result:  boolean
-// fallback: true when URL does not end with '/'
-```
+For hosts that aren't a DOM `Worker` (a Node `worker_threads` worker, the VS Code
+web-extension host, …): wire the server to your own transport. `post` receives
+each outgoing message (already parsed); feed incoming messages (object or string)
+into the returned function.
 
-### `custom/isDir`
+```js
+import { createSwlsServer } from "swls-wasm";
 
-Returns whether the given URL refers to a directory.
+const feed = await createSwlsServer((message) => sendToClient(message), {
+  debug: (line) => console.log(line),
+  // Optional: override how the wasm is loaded. Defaults to fetching the sibling
+  // `swls_wasm_bg.wasm`; pass bytes/URL when the host can't fetch that itself
+  // (e.g. Node, which can't `fetch` a `file://` URL).
+  wasm: undefined,
+});
 
-```ts
-params:  { url: string }
-result:  boolean
-// fallback: true when URL ends with '/'
+feed({ jsonrpc: "2.0", id: 1, method: "initialize", params: { /* … */ } });
 ```
 
-### `custom/canonicalize`
-
-Resolves a URL to its canonical form.
-
-```ts
-params:  { url: string }
-result:  { url: string }
-// fallback: returns the input URL unchanged
-```
-
-## License
-
-* MIT license ([LICENSE](LICENSE) or http://opensource.org/licenses/MIT)
+## Low-level — `WasmLsp`
 
+`WasmLsp` (and the wasm `init` default export) are also re-exported for full
+control. `createSwlsServer` is just a thin wrapper around them.

package/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a Web Worker running the swls language server (browser/web hosts).
+ *
+ * The returned worker speaks whole JSON-RPC messages over `postMessage` (no
+ * `Content-Length` framing) and emits a `{ method: "swls/ready" }` notification
+ * once the wasm has finished initializing.
+ *
+ * @param options Extra worker options; `type` is always `"module"`.
+ */
+export function createSwlsWorker(options?: Omit<WorkerOptions, "type">): Worker;

package/client.js

@@ -0,0 +1,21 @@
+/**
+ * Creates a Web Worker running the swls language server (browser/web hosts).
+ *
+ * The returned worker speaks whole JSON-RPC messages over `postMessage` (no
+ * `Content-Length` framing) and emits a `{ method: "swls/ready" }` notification
+ * once the wasm has finished initializing.
+ *
+ * Kept in its own entry (`swls-wasm/client`) rather than the package root so
+ * that Node/bundler consumers importing `swls-wasm` never pull in a nested
+ * `Worker`/wasm chunk they don't use.
+ *
+ * @param {WorkerOptions} [options] Extra worker options; `type` is always
+ *   `"module"`. (Kept after the spread so bundlers can statically read `type`.)
+ * @returns {Worker}
+ */
+export function createSwlsWorker(options) {
+  return new Worker(new URL("./worker.js", import.meta.url), {
+    ...options,
+    type: "module",
+  });
+}

package/index.d.ts

@@ -0,0 +1,2 @@
+export { default, initSync, WasmLsp, start_wasm_lsp } from "./swls_wasm.js";
+export { createSwlsServer } from "./pump.js";

package/index.js

@@ -0,0 +1,2 @@
+export { default, initSync, WasmLsp, start_wasm_lsp } from "./swls_wasm.js";
+export { createSwlsServer } from "./pump.js";

package/package.json

@@ -4,17 +4,40 @@
   "collaborators": [
     "ajuvercr <arthur.vercruysse@outlook.com>"
   ],
-  "version": "0.3.2-alpha.1",
+  "version": "0.3.2-alpha.3",
   "files": [
     "swls_wasm_bg.wasm",
     "swls_wasm.js",
-    "swls_wasm_bg.js",
-    "swls_wasm.d.ts"
+    "swls_wasm.d.ts",
+    "index.js",
+    "index.d.ts",
+    "pump.js",
+    "pump.d.ts",
+    "worker.js",
+    "client.js",
+    "client.d.ts"
   ],
-  "main": "swls_wasm.js",
-  "types": "swls_wasm.d.ts",
+  "main": "index.js",
+  "types": "index.d.ts",
   "sideEffects": [
-    "./swls_wasm.js",
-    "./snippets/*"
-  ]
+    "./worker.js"
+  ],
+  "module": "index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./client": {
+      "types": "./client.d.ts",
+      "default": "./client.js"
+    },
+    "./worker": "./worker.js",
+    "./swls_wasm.js": {
+      "types": "./swls_wasm.d.ts",
+      "default": "./swls_wasm.js"
+    },
+    "./swls_wasm_bg.wasm": "./swls_wasm_bg.wasm",
+    "./package.json": "./package.json"
+  }
 }

package/pump.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Boots the swls wasm LSP and wires it to a host transport.
+ *
+ * Host-agnostic: the caller decides how outgoing messages are delivered
+ * (`post`) and feeds incoming messages into the returned function. Both
+ * directions exchange whole JSON-RPC messages with no `Content-Length`
+ * framing — `post` receives already-parsed objects, and the returned feed
+ * accepts either a parsed object or a raw JSON string.
+ *
+ * @param post Called with each outgoing JSON-RPC message (already parsed).
+ * @param options.debug The server's debug-log sink.
+ * @param options.wasm Overrides the module/URL forwarded to the wasm `init()`
+ *   (defaults to the sibling `swls_wasm_bg.wasm`); pass it when the host cannot
+ *   fetch that sibling itself (e.g. Node, which can't `fetch` a `file://` URL).
+ * @returns Resolves once wasm is initialized to a function that feeds one
+ *   incoming message (object or string) to the server.
+ */
+export function createSwlsServer(
+  post: (message: unknown) => void,
+  options?: {
+    debug?: (message: string) => void;
+    wasm?: string | URL | Request | BufferSource | WebAssembly.Module;
+  },
+): Promise<(data: unknown) => void>;

package/pump.js

@@ -0,0 +1,36 @@
+import init, { WasmLsp } from "./swls_wasm.js";
+
+/**
+ * Boots the swls wasm LSP and wires it to a host transport.
+ *
+ * Host-agnostic: the caller decides how outgoing messages are delivered
+ * (`post`) and feeds incoming messages into the returned function. Both
+ * directions exchange whole JSON-RPC messages with no `Content-Length`
+ * framing — `post` receives already-parsed objects, and the returned feed
+ * accepts either a parsed object or a raw JSON string.
+ *
+ * Used directly by non-DOM hosts (e.g. a VS Code `worker_threads` server or
+ * the web-extension host); browser consumers get this wrapped in a Worker via
+ * {@link createSwlsWorker} (see `swls-wasm/client`).
+ *
+ * @param {(message: unknown) => void} post
+ *   Called with each outgoing JSON-RPC message (already parsed).
+ * @param {{
+ *   debug?: (message: string) => void,
+ *   wasm?: string | URL | Request | BufferSource | WebAssembly.Module,
+ * }} [options]
+ *   `debug` is the server's debug-log sink. `wasm` overrides the module/URL
+ *   forwarded to the wasm `init()` (defaults to the sibling
+ *   `swls_wasm_bg.wasm`); pass it when the host cannot fetch that sibling
+ *   itself (e.g. Node, which can't `fetch` a `file://` URL).
+ * @returns {Promise<(data: unknown) => void>}
+ *   Resolves once wasm is initialized to a function that feeds one incoming
+ *   message (object or string) to the server.
+ */
+export async function createSwlsServer(post, options = {}) {
+  const { debug, wasm } = options;
+  await init(wasm === undefined ? undefined : { module_or_path: wasm });
+  const lsp = new WasmLsp((message) => post(JSON.parse(message)), debug);
+  return (data) =>
+    lsp.send(typeof data === "string" ? data : JSON.stringify(data));
+}

package/swls_wasm.d.ts

@@ -24,3 +24,46 @@ export class WasmLsp {
 }
 
 export function start_wasm_lsp(): Promise<void>;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_wasmlsp_free: (a: number, b: number) => void;
+    readonly start_wasm_lsp: () => void;
+    readonly wasmlsp_new: (a: any, b: number) => number;
+    readonly wasmlsp_send: (a: number, b: number, c: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h5d8169a9c6a0716a: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h0a08a9b6706aa208: (a: number, b: number, c: any, d: any) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;