@manifest-configuration-language/browser 0.3.2 → 0.3.6

package/README.md

@@ -19,7 +19,7 @@ try {
 }
 ```
 
-Call `runtime.warmUp()` to load the WebAssembly runtime before the first project operation. Pass `signal` and `timeoutMs` to warm-up or an operation to cancel it or set an upper bound for that call. Warm-up's timeout and `initializationTimeoutMs` bound worker startup; an operation's `timeoutMs` bounds execution after startup. Cancelling or timing out worker startup terminates that worker; the next queued operation can create a fresh worker. Cancelling or timing out an operation terminates its worker. Operations and warm-up are serialized because the current Go runtime uses one in-memory project root.
+Call `runtime.warmUp()` to load the WebAssembly runtime before the first project operation. Pass `signal` and `timeoutMs` to warm-up or an operation to cancel it or set an upper bound for that call. Warm-up's timeout and `initializationTimeoutMs` bound worker startup; an operation's `timeoutMs` bounds execution after startup. Cancelling or timing out worker startup terminates that worker; the next queued operation can create a fresh worker. Cancelling or timing out an operation terminates its worker. Operations and warm-up are serialized because the current Go runtime uses one in-memory project root. Set `priority: "interactive"` for user-triggered work that should move ahead of queued requests, or `priority: "background"` for work that can wait behind default-priority requests. Pending completion, hover, and lint requests supersede older requests of the same project and priority; higher-priority pending requests are retained.
 
 Project files can be UTF-8 strings or `Uint8Array` values. UTF-8 files remain inline in project updates. The Browser SDK copies each changed `Uint8Array` and transfers its buffer to the Worker; the Worker sends only `{ "encoding": "binary" }` metadata in the update JSON and passes a path-to-`Uint8Array` map to the Go/WASM project session. The Go runtime copies those bytes into its bounded project filesystem. The SDK-owned and caller-owned arrays remain reusable after each update.
 

package/dist/mcl.wasm

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/mcl.wasm
-size: 96777505 bytes
-sha256: e072b30da32b5353eb9241c34badb3b3cf941418c99353d189a31a9620f0381e
+size: 96803351 bytes
+sha256: 0be9e04fb79c3f19a60cf9e3bd017d1e544db1329a7a9f4b38bb78cb09d9a17e

package/package.json

@@ -1,33 +1,36 @@
 {
   "name": "@manifest-configuration-language/browser",
-  "version": "0.3.2",
+  "version": "0.3.6",
   "description": "Run MCL projects in a browser Web Worker using the Go WebAssembly runtime.",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/manifest-configuration-language/mcl.git",
     "directory": "packages/browser"
   },
-  "type": "module",
-  "license": "Apache-2.0",
   "files": [
     "dist",
     "src",
     "README.md"
   ],
+  "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
     }
   },
-  "engines": {
-    "node": ">=20.19"
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "p-queue": "9.1.2"
   },
   "devDependencies": {
     "json-schema-to-typescript": "16.0.0"
   },
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=20.19"
   },
   "scripts": {
     "build:wasm": "node ./scripts/build-wasm.mjs",

package/src/index.d.ts

@@ -159,6 +159,8 @@ export interface MclProject {
 export interface RequestOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
+  /** Queue requests ahead of default-priority work or yield to interactive requests. */
+  priority?: "interactive" | "background";
 }
 
 export interface ProjectOperationOptions extends RequestOptions {

package/src/index.js

@@ -1,3 +1,4 @@
+import PQueue from "p-queue";
 import {
   maxProjectBytes,
   maxProjectFileBytes,
@@ -61,6 +62,21 @@ export function isValidProjectFileSet(paths) {
 
 const defaultInitializationTimeoutMs = 30_000;
 const defaultOperationTimeoutMs = 10_000;
+const operationPriorities = {
+  render: 30,
+  evaluate: 30,
+  check: 30,
+  parse: 20,
+  format: 20,
+  rename: 20,
+  references: 20,
+  definition: 20,
+  completion: 20,
+  hover: 20,
+  lint: 10,
+};
+const latestOnlyOperations = new Set(["completion", "hover", "lint"]);
+const requestPriorities = { interactive: 40, background: 0 };
 const wasmURL = new URL("../dist/mcl.wasm", import.meta.url).href;
 const wasmExecURL = new URL("../dist/wasm_exec.js", import.meta.url).href;
 
@@ -86,13 +102,84 @@ export function createMclRuntime(options = {}) {
   let worker;
   let ready;
   let disposed = false;
-  let queue = Promise.resolve();
+  const queue = new PQueue({ concurrency: 1 });
+  queue.on("error", () => {});
+  const queueSignals = new Set();
+  const latestPending = new Map();
   let sequence = 0;
   let workerGeneration = 0;
   let workerProject;
   let stopCurrent;
   let stopInitialization;
 
+  function enqueue(operation, run, signal, scope = "runtime", requestedPriority) {
+    if (signal?.aborted) return Promise.reject(signal.reason ?? abortError());
+    const priority =
+      requestPriorities[requestedPriority] ?? operationPriorities[operation] ?? 0;
+    const key = (name) => JSON.stringify([scope, name]);
+    const pendingKey = key(operation);
+    const pendingGroup = () => {
+      let group = latestPending.get(pendingKey);
+      if (!group) {
+        group = new Map();
+        latestPending.set(pendingKey, group);
+      }
+      return group;
+    };
+    const removePending = (pendingPriority, pending) => {
+      const group = latestPending.get(pendingKey);
+      if (group?.get(pendingPriority) !== pending) return;
+      group.delete(pendingPriority);
+      if (group.size === 0) latestPending.delete(pendingKey);
+    };
+    const supersedePending = (name, maximumPriority, message) => {
+      const groupKey = key(name);
+      const group = latestPending.get(groupKey);
+      if (!group) return;
+      for (const [pendingPriority, pending] of group) {
+        if (pendingPriority > maximumPriority) continue;
+        group.delete(pendingPriority);
+        pending.controller.abort(new DOMException(message, "AbortError"));
+      }
+      if (group.size === 0) latestPending.delete(groupKey);
+    };
+
+    if (["render", "evaluate", "check"].includes(operation))
+      supersedePending("lint", priority, "An explicit run replaced this pending lint");
+
+    const queueController = new AbortController();
+    const pending = { controller: queueController, started: false };
+    if (latestOnlyOperations.has(operation)) {
+      supersedePending(operation, priority, "A newer operation replaced this request");
+      pendingGroup().set(priority, pending);
+    }
+
+    queueSignals.add(queueController);
+    const abortWhileQueued = () => {
+      if (!pending.started) queueController.abort(signal.reason ?? abortError());
+    };
+    signal?.addEventListener("abort", abortWhileQueued, { once: true });
+
+    return queue
+      .add(
+        async () => {
+          pending.started = true;
+          if (latestOnlyOperations.has(operation)) removePending(priority, pending);
+          return run();
+        },
+        { priority, signal: queueController.signal },
+      )
+      .finally(() => {
+        signal?.removeEventListener("abort", abortWhileQueued);
+        queueSignals.delete(queueController);
+        if (latestOnlyOperations.has(operation)) removePending(priority, pending);
+      });
+  }
+
+  function abortError() {
+    return new DOMException("The operation was aborted", "AbortError");
+  }
+
   function startWorker() {
     if (disposed) return Promise.reject(new Error("MCL runtime has been disposed"));
     if (ready) return ready;
@@ -355,19 +442,7 @@ export function createMclRuntime(options = {}) {
         throw error;
       }
     };
-    const result = queue.then(run, run);
-    queue = result.catch(() => {});
-    if (!signal) return result;
-
-    let onAbort;
-    const aborted = new Promise((_, reject) => {
-      onAbort = () => reject(new DOMException("The operation was aborted", "AbortError"));
-      signal.addEventListener("abort", onAbort, { once: true });
-      if (signal.aborted) onAbort();
-    });
-    return Promise.race([result, aborted]).finally(() =>
-      signal.removeEventListener("abort", onAbort),
-    );
+    return enqueue(operation, run, signal, project?.id ?? "runtime", requestOptions.priority);
   }
 
   function warmUp(requestOptions = {}) {
@@ -391,18 +466,7 @@ export function createMclRuntime(options = {}) {
         clearTimeout(timer);
       }
     };
-    const result = queue.then(run, run);
-    queue = result.catch(() => {});
-    if (!signal) return result;
-    let onAbort;
-    const aborted = new Promise((_, reject) => {
-      onAbort = () => reject(new DOMException("The operation was aborted", "AbortError"));
-      signal.addEventListener("abort", onAbort, { once: true });
-      if (signal.aborted) onAbort();
-    });
-    return Promise.race([result, aborted]).finally(() =>
-      signal.removeEventListener("abort", onAbort),
-    );
+    return enqueue("warmUp", run, signal, "runtime", requestOptions.priority);
   }
 
   function openProject(files) {
@@ -595,6 +659,8 @@ export function createMclRuntime(options = {}) {
     dispose() {
       if (disposed) return;
       disposed = true;
+      for (const controller of queueSignals)
+        controller.abort(new Error("MCL runtime has been disposed"));
       stopCurrent?.(new Error("MCL runtime has been disposed"));
       stopInitialization?.(new Error("MCL runtime has been disposed"));
       worker?.terminate();

package/src/protocol.d.ts

@@ -132,6 +132,8 @@ export interface CompletionItem {
   label: string;
   kind: number;
   insertText?: string;
+  detail?: string;
+  documentation?: string;
 }
 export interface DefinitionResult {
   location: DefinitionLocation | null;