osra 0.6.6 → 0.6.8

package/build/revivables/identity.d.ts

@@ -9,24 +9,26 @@ export type Messages = {
 };
 export declare const Messages: Messages;
 declare const IDENTITY_MARKER: unique symbol;
-type IdentityWrapper<T = unknown> = {
+/** Phantom shape. A tracked value carries no marker of its own, the mark lives in a WeakMap, so
+ *  this is what `isType` declares instead: matching it at the type level would widen `Capable` to
+ *  every object, and nothing a user writes structurally matches this. */
+type IdentityMarked = {
     readonly [IDENTITY_MARKER]: true;
-    readonly value: T;
 };
 export type BoxedIdentity<T extends Capable = Capable> = BoxBaseType<typeof type> & {
     id: string;
     inner?: Capable;
     [UnderlyingType]: T;
 };
-/** Wrap a value so osra preserves reference identity across the RPC
- *  boundary. Idempotent; primitives pass through unchanged. Lies at the
- *  type level - runtime value is an IdentityWrapper<T> typed as T. */
+/** Mark a value so osra preserves its reference identity across the boundary. The peer's revived
+ *  value stands for this one, and handing it back - to you, or onward to a further context and back
+ *  again - resolves to this very reference. The mark sticks to the value, so only the side that
+ *  owns it has to opt in. Idempotent, and primitives pass through unchanged. */
 export declare const identity: <T>(value: T) => T;
-export declare const isType: (value: unknown) => value is IdentityWrapper;
-export declare const box: <T extends Capable, TContext extends RevivableContext>(wrapper: IdentityWrapper<T>, context: TContext) => BoxedIdentity<T>;
-/** Identity-box a referenceable value with a caller-supplied inner box,
- *  bypassing the recursive-box step. Used by revivables (symbol with
- *  description=undefined) where recursing back through their own box
+export declare const isType: (value: unknown) => value is IdentityMarked;
+export declare const box: <T extends Capable, TContext extends RevivableContext>(value: T, context: TContext) => BoxedIdentity<T>;
+/** Identity-box a referenceable value with a caller-supplied inner box, bypassing the walker. Used
+ *  by revivables (symbol with description=undefined) where recursing back through their own box
  *  would loop into this module again. */
 export declare const boxByReference: <T extends WeakKey, TContext extends RevivableContext>(value: T, innerBox: Capable, context: TContext) => BoxedIdentity;
 export declare const revive: <T extends BoxedIdentity, TContext extends RevivableContext>(value: T, context: TContext) => T[UnderlyingType];

package/build/revivables/index.d.ts

@@ -70,5 +70,18 @@ export declare const defaultRevivableModules: readonly [typeof transfer, typeof
 }];
 export type DefaultRevivableModules = typeof defaultRevivableModules;
 export type DefaultRevivableModule = DefaultRevivableModules[number];
+/** Hold a side effect until the whole box walk this value belongs to has finished, and undo it if the
+ *  walk throws. A module that records state the PEER will be told about ("it knows this id now") must
+ *  not keep that record when a later sibling breaks the message it was recorded for: nothing ships,
+ *  and every later send would then reference something the peer never received. Outside a walk the
+ *  effect is already settled, so `commit` runs immediately. */
+export declare const onBoxWalkSettled: (commit: () => void, rollback: () => void) => void;
 export declare const recursiveBox: <T extends Capable, TModules extends readonly RevivableModule[]>(value: T, context: RevivableContext<TModules>) => DeepReplaceWithBox<T, TModules[number]>;
+/** Box a value your own module claimed in place: every other module gets its turn and children are
+ *  walked as usual, but `claimedBy` is skipped, and the cycle guard the caller's `recursiveBox`
+ *  frame already holds for this value is not re-entered.
+ *  A module needs this when its `isType` matches a bare value rather than a wrapper around one, the
+ *  way `identity()` marks a reference in place: `recursiveBox` on that same value would come
+ *  straight back to the module, and the guard would report it as a cycle. */
+export declare const boxClaimedValue: <T extends Capable, TModules extends readonly RevivableModule[]>(value: T, context: RevivableContext<TModules>, claimedBy: string) => DeepReplaceWithBox<T, TModules[number]>;
 export declare const recursiveRevive: <T extends Capable, TModules extends readonly RevivableModule[]>(value: T, context: RevivableContext<TModules>) => DeepReplaceWithRevive<T, TModules[number]>;

package/build/utils/transport.d.ts

@@ -1,6 +1,5 @@
-import type { Browser } from 'webextension-polyfill';
 import type { Message } from '../types.js';
-import type { WebExtOnConnect, WebExtOnMessage, WebExtPort, WebExtRuntime, WebExtSender } from './type-guards.js';
+import type { WebExtGlobal, WebExtOnConnect, WebExtOnMessage, WebExtPort, WebExtRuntime, WebExtSender } from './webext-types.js';
 /** What the local side knows about the realm on the other end of a connection.
  *
  *  `origin` and `source` are only OBSERVABLE on window transports. A MessagePort message carries
@@ -61,8 +60,8 @@ export type PlatformTransport = EmitPlatformTransport | ReceivePlatformTransport
 export type EmitTransport = EmitPlatformTransport | CustomEmitTransport;
 export type ReceiveTransport = ReceivePlatformTransport | CustomReceiveTransport;
 export type Transport = PlatformTransport | CustomTransport;
-export declare const getWebExtensionGlobal: () => Browser | undefined;
-export declare const getWebExtensionRuntime: () => import("webextension-polyfill").Runtime.Static | undefined;
+export declare const getWebExtensionGlobal: () => WebExtGlobal | undefined;
+export declare const getWebExtensionRuntime: () => WebExtRuntime | undefined;
 export declare const checkOsraMessageKey: (message: any, key: string) => message is Message;
 export declare const registerOsraMessageListener: ({ listener, transport, remoteName, key, origin, unregisterSignal }: {
     listener: (message: Message, messageContext: MessageContext) => void;

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

@@ -1,6 +1,6 @@
-import type { Runtime } from 'webextension-polyfill';
 import type { Message } from '../types.js';
 import type { CustomEmitTransport, CustomReceiveTransport, CustomTransport, EmitJsonPlatformTransport, EmitTransport, JsonPlatformTransport, ReceiveJsonPlatformTransport, ReceiveTransport, Transport } from './transport.js';
+import type { WebExtOnConnect, WebExtOnMessage, WebExtPort, WebExtRuntime } from './webext-types.js';
 declare const typedArrayConstructorsByName: {
     readonly Int8Array: Int8ArrayConstructor;
     readonly Uint8Array: Uint8ArrayConstructor;
@@ -41,14 +41,10 @@ export declare const isSharedArrayBuffer: (value: unknown) => boolean;
  *  the unrelated clonable fallback module. Use isSharedArrayBuffer. */
 export declare const isClonable: typeof isSharedArrayBuffer;
 export declare const isTransferable: (value: unknown) => value is Transferable;
-export type WebExtRuntime = Runtime.Static;
+export type { WebExtRuntime, WebExtPort, WebExtSender, WebExtOnConnect, WebExtOnMessage, WebExtEvent, WebExtGlobal } from './webext-types.js';
 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;
@@ -63,4 +59,3 @@ export declare const isCustomEmitTransport: (value: unknown) => value is CustomE
 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/webext-types.d.ts

@@ -0,0 +1,65 @@
+/** Structural stand-ins for the handful of WebExtension shapes osra touches.
+ *
+ *  Vendored rather than imported from `webextension-polyfill`, because a bare `import type` inside a
+ *  SHIPPED .d.ts makes osra's own declarations depend on a package the consumer may not have, and
+ *  osra ships no dependencies. 0.6.6 and 0.6.7 did exactly that: `build/utils/transport.d.ts` and
+ *  `build/utils/type-guards.d.ts` both imported `webextension-polyfill`, so a consumer without
+ *  `@types/webextension-polyfill` got TS2307 under `skipLibCheck: false` and, far worse, a silent
+ *  collapse with it on - `WebExtRuntime` became `any`, which made `Transport` `any`, which made
+ *  `IsJsonOnlyTransport` true for every transport and degraded the whole `Capable` check.
+ *  `npm run check-declaration-imports` is the guard that keeps it from coming back.
+ *
+ *  Deliberately loose: only the members osra actually calls, typed permissively enough that both
+ *  `webextension-polyfill`'s `Runtime.Static` and `@types/chrome`'s `typeof chrome.runtime` stay
+ *  assignable, since either can be handed to `expose()` as a transport. No index signatures here,
+ *  for the same reason: an interface has no implicit index signature, so adding one to these would
+ *  make every real sender and port stop being assignable. `tests/extension` compiles against
+ *  @types/chrome and the docs examples compile against webextension-polyfill, which is what keeps
+ *  both ends honest. */
+/** The three members osra uses on an extension event (`runtime.onMessage`, `port.onDisconnect`, ...). */
+export type WebExtEvent<TListener extends (...args: any[]) => any = (...args: any[]) => any> = {
+    addListener(listener: TListener, ...rest: any[]): void;
+    removeListener(listener: TListener): void;
+    hasListener(listener: TListener): boolean;
+};
+/** Who a message came from, as the browser reported it. osra never builds one, it only hands the
+ *  browser's own object through to your code, so the fields are all optional and the engine may
+ *  carry more than these. */
+export type WebExtSender = {
+    id?: string;
+    url?: string;
+    origin?: string;
+    frameId?: number;
+    documentId?: string;
+    tlsChannelId?: string;
+    tab?: {
+        id?: number;
+        url?: string;
+        title?: string;
+        windowId?: number;
+        index?: number;
+        active?: boolean;
+    };
+};
+export type WebExtPort = {
+    name: string;
+    sender?: WebExtSender;
+    disconnect(): void;
+    postMessage(message: any): void;
+    onMessage: WebExtEvent;
+    onDisconnect: WebExtEvent;
+};
+export type WebExtRuntime = {
+    id?: string;
+    connect(...args: any[]): WebExtPort;
+    sendMessage(...args: any[]): any;
+    onMessage: WebExtEvent;
+    onConnect: WebExtEvent;
+    onConnectExternal?: WebExtEvent;
+};
+export type WebExtOnConnect = WebExtRuntime['onConnect'];
+export type WebExtOnMessage = WebExtRuntime['onMessage'];
+/** The `browser` / `chrome` global, as much of it as osra looks at. */
+export type WebExtGlobal = {
+    runtime?: WebExtRuntime;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osra",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Easy communication between workers",
   "homepage": "https://github.com/Banou26/osra#readme",
   "bugs": {
@@ -36,7 +36,7 @@
   "scripts": {
     "build": "vp build && node ./node_modules/typescript7/bin/tsc --declaration --emitDeclarationOnly",
     "build-watch": "vp build --watch",
-    "clean": "rimraf build",
+    "clean": "node -e \"require('node:fs').rmSync('build', { recursive: true, force: true })\"",
     "prepublishOnly": "npm run clean && npm run build",
     "build-test": "vp build --config vite.test.config.ts",
     "build-test-watch": "vp build --config vite.test.config.ts --watch",
@@ -46,20 +46,22 @@
     "test": "npm run build && npm run build-test && npx playwright test",
     "test-watch": "set PWTEST_WATCH=1 & npx playwright test",
     "test-watch-headful": "nodemon --watch build-test --exec \"npx playwright test --headed\"",
-    "test-with-coverage": "npm run build-test && npx playwright test && npm run print-coverage && npm run clean-coverage",
+    "test-with-coverage": "VITE_COVERAGE=true npm run build-test && VITE_COVERAGE=true npx playwright test && npm run print-coverage && npm run clean-coverage",
     "print-coverage": "npx nyc report",
-    "clean-coverage": "rimraf .nyc_output coverage",
+    "clean-coverage": "node -e \"for (const dir of ['.nyc_output', 'coverage']) require('node:fs').rmSync(dir, { recursive: true, force: true })\"",
     "type-check": "node ./node_modules/typescript7/bin/tsc --noEmit && node ./node_modules/typescript7/bin/tsc --noEmit -p tsconfig.tests.json",
     "start-server": "http-server -p 3000",
     "build-extension-test": "node build-extension-test.mjs",
     "test-extension": "npm run build-extension-test && npx playwright test -c playwright.extension.config.ts",
     "check-consumer-types": "npm run build && node ./node_modules/typescript7/bin/tsc --noEmit -p tsconfig.consumer.json",
+    "check-declaration-imports": "node scripts/check-declaration-imports.mjs",
     "docs-dev": "npm run dev -w docs",
     "docs-build": "npm run build -w docs",
     "docs-preview": "npm run preview -w docs",
     "docs-gen-reference": "npm run gen:reference -w docs",
     "docs-check-links": "npm run check-links -w docs",
-    "docs-check-twoslash": "npm run check-twoslash -w docs"
+    "docs-check-twoslash": "npm run check-twoslash -w docs",
+    "docs-check-html": "npm run check-html -w docs"
   },
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.2",