osra 0.2.13 → 0.3.0

package/build/utils/event-channel.d.ts

@@ -0,0 +1,27 @@
+import type { TypedMessagePort, TypedMessagePortEventMap } from './typed-message-channel';
+export declare class EventPort<T> extends EventTarget {
+    addEventListener<K extends keyof TypedMessagePortEventMap<T> & string>(type: K, listener: ((event: TypedMessagePortEventMap<T>[K]) => void) | null, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof TypedMessagePortEventMap<T> & string>(type: K, listener: ((event: TypedMessagePortEventMap<T>[K]) => void) | null, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
+    _peer: EventPort<any> | undefined;
+    _queue: MessageEvent<T>[];
+    _started: boolean;
+    _closed: boolean;
+    _onClose: (() => void) | undefined;
+    private _onmessage;
+    get onmessage(): ((this: MessagePort, ev: MessageEvent<T>) => unknown) | null;
+    set onmessage(value: ((this: MessagePort, ev: MessageEvent<T>) => unknown) | null);
+    onmessageerror: ((this: MessagePort, ev: MessageEvent) => unknown) | null;
+    dispatchEvent(event: Event): boolean;
+    postMessage(message: T, _options?: Transferable[] | StructuredSerializeOptions): void;
+    start(): void;
+    close(): void;
+}
+export interface EventPort<T> extends Omit<TypedMessagePort<T>, 'addEventListener' | 'removeEventListener'> {
+}
+export declare class EventChannel<T1 = unknown, T2 = unknown> {
+    readonly port1: EventPort<T1>;
+    readonly port2: EventPort<T2>;
+    constructor();
+}

package/build/utils/index.d.ts

@@ -0,0 +1,11 @@
+export * from './transport';
+export * from '../revivables';
+export * from './replace';
+export * from '../connections';
+export * from './transferable';
+export * from './type-guards';
+export * from './typed-event-target';
+export * from './typed-message-channel';
+export * from './event-channel';
+export * from './type';
+export * from './capable-check';

package/build/utils/replace.d.ts

@@ -0,0 +1,25 @@
+type FindMatchingBox<T, M> = M extends {
+    isType: (value: unknown) => value is infer S;
+    box: (...args: any[]) => infer B;
+} ? T extends S ? B : never : never;
+export type ReplaceWithBox<T, M> = [
+    FindMatchingBox<T, M>
+] extends [never] ? T : FindMatchingBox<T, M>;
+export type DeepReplaceWithBox<T, M> = [
+    FindMatchingBox<T, M>
+] extends [never] ? T extends Array<infer U> ? Array<DeepReplaceWithBox<U, M>> : T extends object ? {
+    [K in keyof T]: DeepReplaceWithBox<T[K], M>;
+} : T : FindMatchingBox<T, M>;
+type FindMatchingRevive<T, M> = M extends {
+    box: (...args: any[]) => infer S;
+    revive: (...args: any[]) => infer R;
+} ? T extends S ? R : never : never;
+export type ReplaceWithRevive<T, M> = [
+    FindMatchingRevive<T, M>
+] extends [never] ? T : FindMatchingRevive<T, M>;
+export type DeepReplaceWithRevive<T, M> = [
+    FindMatchingRevive<T, M>
+] extends [never] ? T extends Array<infer U> ? Array<DeepReplaceWithRevive<U, M>> : T extends object ? {
+    [K in keyof T]: DeepReplaceWithRevive<T[K], M>;
+} : T : FindMatchingRevive<T, M>;
+export {};

package/build/utils/transferable.d.ts

@@ -0,0 +1,20 @@
+import { transfer } from '../revivables/transfer';
+export { transfer };
+/**
+ * Walk a boxed message and collect the list of Transferable references that
+ * should be moved (rather than cloned) when calling postMessage.
+ *
+ * The rules are:
+ *   1. Must-transfer types (MessagePort, streams, OffscreenCanvas) are always
+ *      included — structured clone cannot represent them.
+ *   2. Clonable types (SharedArrayBuffer) are skipped entirely.
+ *   3. Other Transferable types (ArrayBuffer, ImageBitmap) are included only
+ *      when the walker is inside a non-degraded transfer box — i.e. when the
+ *      user explicitly opted into move semantics at the send site via
+ *      transfer() AND the platform supports transferring.
+ *
+ * The transfer intent is carried on the wire by the transfer revivable box;
+ * recognising it structurally here (without importing the module) is all the
+ * coupling this file needs.
+ */
+export declare const getTransferableObjects: (value: unknown) => Transferable[];

package/build/utils/transport.d.ts

@@ -0,0 +1,56 @@
+import type { Message } from '../types';
+import type { WebExtOnConnect, WebExtOnMessage, WebExtPort, WebExtRuntime, WebExtSender } from './type-guards';
+export type MessageContext = {
+    port?: MessagePort | WebExtPort;
+    sender?: WebExtSender;
+    receiveTransport?: ReceivePlatformTransport;
+    source?: MessageEventSource | null;
+};
+export type ReceiveHandler = (listener: (event: Message, messageContext: MessageContext) => void) => void;
+export type EmitHandler = (message: Message, transferables?: Transferable[]) => void;
+type CustomReceive = ReceivePlatformTransport | ReceiveHandler;
+type CustomEmit = EmitPlatformTransport | EmitHandler;
+export type CustomTransport = {
+    isJson?: boolean;
+} & ({
+    receive: CustomReceive;
+    emit: CustomEmit;
+} | {
+    receive: CustomReceive;
+} | {
+    emit: CustomEmit;
+});
+export type CustomEmitTransport = Extract<CustomTransport, {
+    emit: any;
+}>;
+export type CustomReceiveTransport = Extract<CustomTransport, {
+    receive: any;
+}>;
+export type EmitJsonPlatformTransport = WebSocket | WebExtPort | WebExtRuntime;
+export type ReceiveJsonPlatformTransport = WebSocket | WebExtPort | WebExtOnConnect | WebExtOnMessage | WebExtRuntime;
+export type JsonPlatformTransport = {
+    isJson: true;
+} | EmitJsonPlatformTransport | ReceiveJsonPlatformTransport;
+type StructuredClonePlatformTransport = Window | ServiceWorker | Worker | SharedWorker | MessagePort;
+export type EmitPlatformTransport = EmitJsonPlatformTransport | StructuredClonePlatformTransport;
+export type ReceivePlatformTransport = ReceiveJsonPlatformTransport | StructuredClonePlatformTransport;
+export type PlatformTransport = EmitPlatformTransport | ReceivePlatformTransport;
+export type EmitTransport = EmitPlatformTransport & Extract<CustomTransport, {
+    emit: any;
+}>;
+export type ReceiveTransport = ReceivePlatformTransport & Extract<CustomTransport, {
+    receive: any;
+}>;
+export type Transport = PlatformTransport | CustomTransport;
+export declare const getWebExtensionGlobal: () => typeof browser;
+export declare const getWebExtensionRuntime: () => typeof browser.runtime;
+export declare const checkOsraMessageKey: (message: any, key: string) => message is Message;
+export declare const registerOsraMessageListener: ({ listener, transport, remoteName, key, unregisterSignal }: {
+    listener: (message: Message, messageContext: MessageContext) => void;
+    transport: ReceiveTransport;
+    remoteName?: string;
+    key?: string;
+    unregisterSignal?: AbortSignal;
+}) => void;
+export declare const sendOsraMessage: (transport: EmitTransport, message: Message, origin?: string, transferables?: Transferable[]) => void;
+export {};

package/build/utils/type-guards.d.ts

@@ -0,0 +1,58 @@
+import type { Runtime } from 'webextension-polyfill';
+import type { Message } from '../types';
+import type { CustomEmitTransport, CustomReceiveTransport, CustomTransport, EmitJsonPlatformTransport, EmitTransport, JsonPlatformTransport, ReceiveJsonPlatformTransport, ReceiveTransport, Transport } from './transport';
+declare const typedArrayConstructorsByName: {
+    readonly Int8Array: Int8ArrayConstructor;
+    readonly Uint8Array: Uint8ArrayConstructor;
+    readonly Uint8ClampedArray: Uint8ClampedArrayConstructor;
+    readonly Int16Array: Int16ArrayConstructor;
+    readonly Uint16Array: Uint16ArrayConstructor;
+    readonly Int32Array: Int32ArrayConstructor;
+    readonly Uint32Array: Uint32ArrayConstructor;
+    readonly Float16Array: Float16ArrayConstructor;
+    readonly Float32Array: Float32ArrayConstructor;
+    readonly Float64Array: Float64ArrayConstructor;
+    readonly BigInt64Array: BigInt64ArrayConstructor;
+    readonly BigUint64Array: BigUint64ArrayConstructor;
+};
+export type TypedArrayType = keyof typeof typedArrayConstructorsByName;
+export type TypedArrayConstructor = (typeof typedArrayConstructorsByName)[TypedArrayType];
+export type TypedArray = InstanceType<TypedArrayConstructor>;
+export declare const typedArrayToType: (value: TypedArray) => TypedArrayType;
+export declare const typedArrayTypeToTypedArrayConstructor: (value: TypedArrayType) => TypedArrayConstructor;
+export declare const isTypedArray: (value: unknown) => value is TypedArray;
+export declare const isWebSocket: (value: unknown) => value is WebSocket;
+export declare const isServiceWorkerContainer: (value: unknown) => value is ServiceWorkerContainer;
+export declare const isWorker: (value: unknown) => value is Worker;
+export declare const isDedicatedWorker: (value: unknown) => value is DedicatedWorkerGlobalScope;
+export declare const isSharedWorker: (value: unknown) => value is SharedWorker;
+export declare const isOsraMessage: (value: unknown) => value is Message;
+type AnyConstructor = abstract new (...args: any[]) => unknown;
+/** True if `value` is an instance of any of the given (possibly undefined-on-this-platform)
+ *  constructors. Tolerates missing globals so callers don't have to guard each one. */
+export declare const instanceOfAny: (value: unknown, ctors: readonly (AnyConstructor | undefined)[]) => boolean;
+export declare const isClonable: (value: unknown) => boolean;
+export declare const isTransferable: (value: unknown) => value is Transferable;
+export type WebExtRuntime = typeof browser.runtime;
+export declare const isWebExtensionRuntime: (value: unknown) => value is WebExtRuntime;
+export type WebExtPort = ReturnType<WebExtRuntime['connect']> | Runtime.Port;
+export declare const isWebExtensionPort: (value: unknown, connectPort?: boolean) => value is WebExtPort;
+export type WebExtSender = NonNullable<WebExtPort['sender']>;
+export type WebExtOnConnect = WebExtRuntime['onConnect'];
+export declare const isWebExtensionOnConnect: (value: unknown) => value is WebExtOnConnect;
+export type WebExtOnMessage = WebExtRuntime['onMessage'];
+export declare const isWebExtensionOnMessage: (value: unknown) => value is WebExtOnMessage;
+export declare const isWindow: (value: unknown) => value is Window;
+export declare const isEmitJsonOnlyTransport: (value: unknown) => value is EmitJsonPlatformTransport;
+export declare const isReceiveJsonOnlyTransport: (value: unknown) => value is ReceiveJsonPlatformTransport;
+export type IsJsonOnlyTransport<T extends Transport> = T extends JsonPlatformTransport ? true : false;
+export declare const isJsonOnlyTransport: (value: unknown) => value is Extract<Transport, JsonPlatformTransport>;
+export declare const isEmitTransport: (value: unknown) => value is EmitTransport;
+export declare function assertEmitTransport(transport: Transport): asserts transport is EmitTransport;
+export declare const isReceiveTransport: (value: unknown) => value is ReceiveTransport;
+export declare function assertReceiveTransport(transport: Transport): asserts transport is ReceiveTransport;
+export declare const isCustomEmitTransport: (value: unknown) => value is CustomEmitTransport;
+export declare const isCustomReceiveTransport: (value: unknown) => value is CustomReceiveTransport;
+export declare const isCustomTransport: (value: unknown) => value is CustomTransport;
+export declare const isTransport: (value: unknown) => value is Transport;
+export {};

package/build/utils/type.d.ts

@@ -0,0 +1,2 @@
+export declare const UnderlyingType: unique symbol;
+export type UnderlyingType = typeof UnderlyingType;

package/build/utils/typed-event-target.d.ts

@@ -0,0 +1,16 @@
+import type { UnderlyingType } from './type';
+export type EventMap = Record<string, Event>;
+export interface TypedEventTarget<T extends EventMap> extends EventTarget {
+    [UnderlyingType]?: T;
+    addEventListener<K extends keyof T & string>(type: K, listener: ((event: T[K]) => void) | null, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof T & string>(type: K, listener: ((event: T[K]) => void) | null, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
+}
+/**
+ * Create a new `TypedEventTarget<T>` for a given event map. Centralises the
+ * `EventTarget` → `TypedEventTarget<T>` cast so individual call sites don't
+ * each need their own (`EventTarget` lacks the generic event map at the type
+ * level, but the runtime behaviour is identical).
+ */
+export declare const createTypedEventTarget: <T extends EventMap>() => TypedEventTarget<T>;

package/build/utils/typed-message-channel.d.ts

@@ -0,0 +1,19 @@
+import type { UnderlyingType } from './type';
+import type { TypedEventTarget } from './typed-event-target';
+export type TypedMessagePortEventMap<T = unknown> = {
+    'message': MessageEvent<T>;
+    'messageerror': MessageEvent;
+};
+export interface TypedMessagePort<T = unknown> extends Omit<TypedEventTarget<TypedMessagePortEventMap<T>>, typeof UnderlyingType> {
+    [UnderlyingType]?: T;
+    onmessage: ((this: MessagePort, ev: MessageEvent<T>) => unknown) | null;
+    onmessageerror: ((this: MessagePort, ev: MessageEvent) => unknown) | null;
+    postMessage(message: T, transfer: Transferable[]): void;
+    postMessage(message: T, options?: StructuredSerializeOptions): void;
+    start(): void;
+    close(): void;
+}
+export interface TypedMessageChannel<T1 = unknown, T2 = unknown> {
+    readonly port1: TypedMessagePort<T1>;
+    readonly port2: TypedMessagePort<T2>;
+}

package/package.json

@@ -1,67 +1,60 @@
-{
-  "name": "osra",
-  "version": "0.2.13",
-  "description": "Easy communication between workers",
-  "files": [
-    "build"
-  ],
-  "main": "build/index.js",
-  "type": "module",
-  "scripts": {
-    "build": "vite build",
-    "build-watch": "vite build --watch",
-    "build-test": "vite build --config vite.test.config.ts",
-    "build-test-watch": "vite build --config vite.test.config.ts --watch",
-    "dev": "concurrently \"npm run build-test-watch\"",
-    "_dev": "concurrently \"npm run build-watch\" \"npm run build-test-watch\" \"npm run test-watch\"",
-    "dev2": "concurrently \"npm run build-watch\" \"npm run build-test-watch\" \"npm run test-watch-headful\"",
-    "test": "npm run build-test && npx playwright test",
-    "test-watch": "set PWTEST_WATCH=1 & npx playwright test",
-    "test-watch-headful": "nodemon --watch build --exec \"npx playwright test --headed\"",
-    "test-with-coverage": "npm run build-test && npx playwright test && npm run print-coverage && npm run clean-coverage",
-    "print-coverage": "npx nyc report",
-    "clean-coverage": "rimraf .nyc_output coverage",
-    "type-check": "tsgo --noEmit",
-    "start-server": "http-server -p 3000",
-    "linux-run-playwright": "xhost +local:docker && docker run -it --name playwright -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:rw --network=host --ipc=host --shm-size=2gb --rm mcr.microsoft.com/playwright:v1.55.1-noble npx npx -y playwright@1.55.1 run-server --port 8010 --host 0.0.0.0",
-    "linux-test": "PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:8010/ npx playwright test -c playwright.linux.config.ts",
-    "linux-test-watch-headful": "nodemon --watch build --exec \"PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:8010/ npx playwright test -c playwright.linux.config.ts\"",
-    "build-extension-test": "vite build --config vite.extension-test.config.ts",
-    "build-extension-test-watch": "vite build --config vite.extension-test.config.ts --watch",
-    "test-extension": "npm run build-extension-test && npx playwright test -c playwright.extension.config.ts"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Banou26/osra.git"
-  },
-  "author": "Banou26",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/Banou26/osra/issues"
-  },
-  "homepage": "https://github.com/Banou26/osra#readme",
-  "devDependencies": {
-    "@istanbuljs/nyc-config-typescript": "^1.0.2",
-    "@playwright/test": "^1.56.1",
-    "@types/chai": "^5.2.3",
-    "@types/chai-as-promised": "^8.0.2",
-    "@types/chrome": "^0.1.27",
-    "@types/firefox-webext-browser": "^143.0.0",
-    "@types/node": "^25.0.2",
-    "@types/webextension-polyfill": "^0.12.4",
-    "@typescript/native-preview": "^7.0.0-dev.20251223.1",
-    "chai": "^5.3.3",
-    "chai-as-promised": "^8.0.1",
-    "concurrently": "^9.1.0",
-    "http-server": "^14.1.1",
-    "nodemon": "^3.1.10",
-    "nyc": "^17.1.0",
-    "playwright": "^1.56.1",
-    "typescript": "^5.9.3",
-    "typescript-event-target": "^1.1.1",
-    "vite": "^7.2.2",
-    "vite-plugin-dts": "^4.5.4",
-    "vite-plugin-istanbul": "^7.2.0",
-    "vite-plugin-top-level-await": "^1.6.0"
-  }
-}
+{
+  "name": "osra",
+  "version": "0.3.0",
+  "description": "Easy communication between workers",
+  "files": [
+    "build"
+  ],
+  "main": "build/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "vite build && tsgo --declaration --emitDeclarationOnly",
+    "build-watch": "vite build --watch",
+    "build-test": "vite build --config vite.test.config.ts",
+    "build-test-watch": "vite build --config vite.test.config.ts --watch",
+    "dev": "concurrently \"npm run build-test-watch\"",
+    "_dev": "concurrently \"npm run build-watch\" \"npm run build-test-watch\" \"npm run test-watch\"",
+    "dev2": "concurrently \"npm run build-watch\" \"npm run build-test-watch\" \"npm run test-watch-headful\"",
+    "test": "npm run build-test && npx playwright test",
+    "test-watch": "set PWTEST_WATCH=1 & npx playwright test",
+    "test-watch-headful": "nodemon --watch build --exec \"npx playwright test --headed\"",
+    "test-with-coverage": "npm run build-test && npx playwright test && npm run print-coverage && npm run clean-coverage",
+    "print-coverage": "npx nyc report",
+    "clean-coverage": "rimraf .nyc_output coverage",
+    "type-check": "tsgo --noEmit && tsgo --noEmit -p tsconfig.tests.json",
+    "start-server": "http-server -p 3000",
+    "build-extension-test": "vite build --config vite.extension-test.config.ts",
+    "build-extension-test-watch": "vite build --config vite.extension-test.config.ts --watch",
+    "test-extension": "npm run build-extension-test && npx playwright test -c playwright.extension.config.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Banou26/osra.git"
+  },
+  "author": "Banou26",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Banou26/osra/issues"
+  },
+  "homepage": "https://github.com/Banou26/osra#readme",
+  "devDependencies": {
+    "@istanbuljs/nyc-config-typescript": "^1.0.2",
+    "@playwright/test": "^1.58.2",
+    "@types/chai": "^5.2.3",
+    "@types/chai-as-promised": "^8.0.2",
+    "@types/chrome": "^0.1.27",
+    "@types/firefox-webext-browser": "^143.0.0",
+    "@types/node": "^25.0.2",
+    "@types/webextension-polyfill": "^0.12.4",
+    "@typescript/native-preview": "^7.0.0-dev.20260404.1",
+    "chai": "^5.3.3",
+    "chai-as-promised": "^8.0.1",
+    "concurrently": "^9.1.0",
+    "http-server": "^14.1.1",
+    "nodemon": "^3.1.10",
+    "nyc": "^17.1.0",
+    "playwright": "^1.58.2",
+    "vite": "^8.0.3",
+    "vite-plugin-istanbul": "^8.0.0"
+  }
+}