@gjsify/web-worker 0.0.0-stage → 0.64.14

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @gjsify/web-worker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+WHATWG `Worker` for GJS (and Node) over `worker_threads`. `new Worker(url)`, `postMessage`, `terminate`, `onmessage` / `onerror` / `onmessageerror`, and a `DedicatedWorkerGlobalScope`-shaped `self` inside the worker. [Comlink](https://github.com/GoogleChromeLabs/comlink) works unmodified.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+## Installation
+
+```bash
+gjsify install @gjsify/web-worker
+
+# npm or yarn also work (e.g. adding it to an existing project):
+npm install @gjsify/web-worker
+yarn add @gjsify/web-worker
+```
+
+## Usage
+
+```typescript
+import { Worker } from '@gjsify/web-worker';
+
+const worker = new Worker(new URL('./echo.worker.mjs', import.meta.url), { type: 'module', name: 'echo' });
+worker.onmessage = (event) => console.log(event.data);
+worker.postMessage({ hello: 'world' });
+```
+
+```javascript
+// echo.worker.mjs
+self.onmessage = (event) => self.postMessage({ echo: event.data, name: self.name });
+```
+
+With `gjsify build --globals auto`, a bare `Worker` reference is routed here on GJS and Node; browsers keep their own.
+
+### Comlink
+
+```typescript
+import * as Comlink from 'comlink';
+
+const api = Comlink.wrap<Api>(new Worker(new URL('./api.worker.mjs', import.meta.url)));
+console.log(await api.add(2, 3));
+```
+
+## Behaviour
+
+- Host: `postMessage(value, transfer | { transfer })`, `terminate()` (idempotent, silences further events), `addEventListener`, and the three `on…` attributes.
+- An uncaught error in the worker is a cancellable `ErrorEvent`; if nothing handles it, it goes to `console.error`.
+- Worker scope: `self`, `name`, `postMessage`, `addEventListener` / `removeEventListener` (`message`, `messageerror`; function or `handleEvent` listeners), `onmessage`, `onmessageerror`, `close()`.
+- Relative script strings resolve against the working directory.
+- Scripts load as ES modules; `type` is accepted but not distinguished.
+
+## Limits
+
+- On GJS the child is a bare `gjs` with no module resolution: the worker file must be self-contained. Bundle it with `gjsify build --app gjs`.
+- Parent-side globals do not exist in the child; its global surface is the child's own.
+- Detecting `new Worker(new URL(…, import.meta.url))` at build time and bundling the worker file is not part of this package yet (#2338).
+
+## License
+
+MIT

package/globals.mjs

@@ -0,0 +1,9 @@
+/**
+ * Re-exports the host's `Worker` global for browser and NativeScript builds.
+ *
+ * Node has no WHATWG `Worker`, so unlike its sibling `message-channel` this
+ * package is NOT native there: a Node build keeps the adapter, which runs over
+ * the native `node:worker_threads`. Only runtimes whose slot is `native` are
+ * routed here.
+ */
+export const Worker = globalThis.Worker;

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{Worker as e}from"./worker.js";export{e as Worker};

package/lib/esm/register.js

@@ -0,0 +1 @@
+import{Worker as e}from"./worker.js";import"./index.js";globalThis.Worker===void 0&&(globalThis.Worker=e);

package/lib/esm/worker-scope.js

@@ -0,0 +1,47 @@
+import"./_virtual/_rolldown/runtime.js";function buildWorkerSource(e,t,n){let r=`
+${n?``:`const { parentPort } = require('node:worker_threads');`}
+${`
+const scope = globalThis;
+const wrapped = { message: new Map(), messageerror: new Map() };
+const event = (type, data) => ({ type, data, target: scope, currentTarget: scope, ports: [], origin: '', lastEventId: '', source: null });
+
+scope.self = scope;
+scope.name = %NAME%;
+scope.postMessage = (value, options) => {
+  const transfer = Array.isArray(options) ? options : options && options.transfer ? options.transfer : undefined;
+  parentPort.postMessage(value, transfer);
+};
+scope.addEventListener = (type, listener) => {
+  const registry = wrapped[type];
+  if (!registry || registry.has(listener)) return;
+  const fn = typeof listener === 'function' ? listener : listener && listener.handleEvent ? (e) => listener.handleEvent(e) : null;
+  if (!fn) return;
+  const forward = type === 'message' ? (data) => fn(event(type, data)) : () => fn(event(type, null));
+  registry.set(listener, forward);
+  parentPort.on(type, forward);
+};
+scope.removeEventListener = (type, listener) => {
+  const registry = wrapped[type];
+  const forward = registry && registry.get(listener);
+  if (forward) { registry.delete(listener); parentPort.off(type, forward); }
+};
+scope.close = () => parentPort.close();
+for (const type of ['message', 'messageerror']) {
+  let holder = null;
+  Object.defineProperty(scope, 'on' + type, {
+    configurable: true,
+    get: () => (holder ? holder.fn : null),
+    set: (fn) => {
+      if (holder) scope.removeEventListener(type, holder);
+      holder = typeof fn === 'function' ? { fn, handleEvent: (e) => fn.call(scope, e) } : null;
+      if (holder) scope.addEventListener(type, holder);
+    },
+  });
+}
+`.replace(`%NAME%`,JSON.stringify(t))}
+const boot = async () => { await import(${JSON.stringify(e)}); };
+`;return n?`${r}\nreturn boot();`:`${r}\nboot().catch((error) => {
+  const context = globalThis.__gjsify_worker_context;
+  if (context && context.crash) context.crash(error);
+  else queueMicrotask(() => { throw error; });
+});`}export{buildWorkerSource};

package/lib/esm/worker.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{buildWorkerSource as e}from"./worker-scope.js";import{ErrorEvent as t,EventTarget as n,MessageEvent as r}from"@gjsify/dom-events";import{cwd as i,versions as a}from"node:process";import{pathToFileURL as o}from"node:url";import{Worker as s}from"node:worker_threads";const c=typeof a.gjs==`string`;function resolveScript(e){if(e instanceof URL)return e.href;let t=String(e);return/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(t)?new URL(t).href:new URL(t,o(`${i()}/`)).href}var Worker=class extends n{#e;#t=!1;#n={message:null,messageerror:null,error:null};constructor(n,i={}){super();let a=new s(e(resolveScript(n),i.name??``,c),{eval:!0});this.#e=a,a.on(`message`,e=>{this.#t||this.dispatchEvent(new r(`message`,{data:e}))}),a.on(`messageerror`,()=>{this.#t||this.dispatchEvent(new r(`messageerror`,{data:null}))}),a.on(`error`,e=>{if(this.#t)return;let n=new t(`error`,{cancelable:!0,message:e?.message??String(e),error:e});this.dispatchEvent(n),!n.defaultPrevented&&this.#n.error===null&&console.error(e)})}postMessage(e,t){if(this.#t)return;let n=Array.isArray(t)?t:t?.transfer;this.#e.postMessage(e,n)}terminate(){this.#t||(this.#t=!0,this.#e.terminate().catch(()=>{}))}#r(e,t){let n=this.#n[e];n&&this.removeEventListener(e,n),this.#n[e]=typeof t==`function`?t:null,this.#n[e]&&this.addEventListener(e,this.#n[e])}get onmessage(){return this.#n.message}set onmessage(e){this.#r(`message`,e)}get onmessageerror(){return this.#n.messageerror}set onmessageerror(e){this.#r(`messageerror`,e)}get onerror(){return this.#n.error}set onerror(e){this.#r(`error`,e)}get[Symbol.toStringTag](){return`Worker`}};export{Worker};

package/lib/types/comlink.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -0,0 +1,2 @@
+export { Worker } from './worker.js';
+export type { WorkerOptions } from './worker.js';

package/lib/types/register.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/register.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/worker-scope.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Eval-mode source for a worker: install the scope, then load `href`.
+ * `gjs` selects the tail that RETURNS the import so the bootstrap awaits it.
+ */
+export declare function buildWorkerSource(href: string, name: string, gjs: boolean): string;

package/lib/types/worker.d.ts

@@ -0,0 +1,25 @@
+import { EventTarget } from '@gjsify/dom-events';
+export interface WorkerOptions {
+    /** Only `'module'` is meaningful: the script is always loaded as an ES module. */
+    type?: 'classic' | 'module';
+    /** Becomes `self.name` inside the worker. */
+    name?: string;
+    credentials?: 'omit' | 'same-origin' | 'include';
+}
+type Handler = ((event: any) => unknown) | null;
+export declare class Worker extends EventTarget {
+    #private;
+    constructor(scriptURL: string | URL, options?: WorkerOptions);
+    postMessage(message: unknown, transfer?: readonly unknown[] | {
+        transfer?: readonly unknown[];
+    }): void;
+    terminate(): void;
+    get onmessage(): Handler;
+    set onmessage(fn: Handler);
+    get onmessageerror(): Handler;
+    set onmessageerror(fn: Handler);
+    get onerror(): Handler;
+    set onerror(fn: Handler);
+    get [Symbol.toStringTag](): string;
+}
+export {};

package/lib/types/worker.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,81 @@
 {
-  "name": "@gjsify/web-worker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/web-worker",
+    "version": "0.64.14",
+    "description": "WHATWG Worker for GJS (and Node) over worker_threads — new Worker(url), postMessage, terminate, onmessage/onerror, with a DedicatedWorkerGlobalScope-shaped scope inside the worker. Works with Comlink unmodified.",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        },
+        "./register": {
+            "types": "./lib/types/register.d.ts",
+            "default": "./lib/esm/register.js"
+        },
+        "./globals": "./globals.mjs"
+    },
+    "files": [
+        "lib",
+        "globals.mjs"
+    ],
+    "sideEffects": [
+        "./lib/esm/register.js",
+        "./globals.mjs"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo fixtures test.gjs.mjs test.node.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
+        "prebuild:test:fixtures": "gjsify copy src/fixtures/*.mjs fixtures/",
+        "build:test:gjs": "gjsify run prebuild:test:fixtures && gjsify build src/bundled-fixtures/comlink.worker.mjs --app gjs --outfile fixtures/comlink.worker.bundle.mjs && gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "build:test:browser": "gjsify build src/test.browser.mts --app browser --outfile dist/test.browser.mjs",
+        "build:test:node": "gjsify run prebuild:test:fixtures && gjsify build src/bundled-fixtures/comlink.worker.mjs --app node --outfile fixtures/comlink.worker.bundle.mjs && gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "test": "gjsify run build:gjsify && gjsify run test:node && gjsify run test:gjs",
+        "test:gjs": "gjsify run build:test:gjs && gjsify run test.gjs.mjs",
+        "test:node": "gjsify run build:test:node && node test.node.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "web",
+        "worker",
+        "web-worker",
+        "comlink"
+    ],
+    "devDependencies": {
+        "@gjsify/cli": "^0.64.14",
+        "@gjsify/node-globals": "^0.64.14",
+        "@gjsify/unit": "^0.64.14",
+        "@types/node": "^25.9.2",
+        "comlink": "^4.4.2",
+        "typescript": "^6.0.3"
+    },
+    "dependencies": {
+        "@gjsify/dom-events": "^0.64.14",
+        "@gjsify/worker_threads": "^0.64.14"
+    },
+    "license": "MIT",
+    "author": "Pascal Garber <pascal@artandcode.studio>",
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "polyfill",
+            "browser": "native",
+            "nativescript": "native"
+        },
+        "tier": 1
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/web/web-worker"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/web-worker#readme"
+}