@wordpress/worker-threads 1.0.1-next.v.202602200903.0

package/build-types/worker-thread.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Exposes an object's methods to be called from the main thread.
+ *
+ * This function should be called in the worker script to make methods
+ * available for RPC calls. Only methods (functions) on the object will
+ * be exposed; other properties are ignored.
+ *
+ * @example
+ * ```typescript
+ * // worker.ts
+ * import { expose } from '@wordpress/worker-threads/worker';
+ *
+ * const api = {
+ *   async processImage(buffer: ArrayBuffer): Promise<ArrayBuffer> {
+ *     // ... processing logic
+ *     return resultBuffer;
+ *   },
+ *
+ *   async calculateSum(a: number, b: number): Promise<number> {
+ *     return a + b;
+ *   }
+ * };
+ *
+ * expose(api);
+ *
+ * // Export the type for use with wrap() on main thread
+ * export type WorkerAPI = typeof api;
+ * ```
+ *
+ * @param target - Object containing methods to expose to the main thread.
+ */
+export declare function expose<T extends object>(target: T): void;
+//# sourceMappingURL=worker-thread.d.ts.map

package/build-types/worker-thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-thread.d.ts","sourceRoot":"","sources":["../src/worker-thread.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,MAAM,CAAE,CAAC,SAAS,MAAM,EAAI,MAAM,EAAE,CAAC,GAAI,IAAI,CAU5D"}

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@wordpress/worker-threads",
+	"version": "1.0.1-next.v.202602200903.0+06edfb869",
+	"description": "Utilities for type-safe Web Worker communication with RPC.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"worker",
+		"web-worker",
+		"rpc",
+		"threads"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/worker-threads/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/worker-threads"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=18.12.0",
+		"npm": ">=8.19.2"
+	},
+	"files": [
+		"src",
+		"build",
+		"build-module",
+		"build-types",
+		"*.md"
+	],
+	"main": "build/index.cjs",
+	"module": "build-module/index.mjs",
+	"exports": {
+		".": {
+			"types": "./build-types/index.d.ts",
+			"import": "./build-module/index.mjs",
+			"default": "./build/index.cjs"
+		},
+		"./worker": {
+			"types": "./build-types/worker-thread.d.ts",
+			"import": "./build-module/worker-thread.mjs",
+			"default": "./build/worker-thread.cjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"types": "build-types",
+	"sideEffects": false,
+	"dependencies": {
+		"comctx": "^1.4.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "6e225a6505fdc8e407305851c7a68b781dee8118"
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Main entry point for @wordpress/worker-threads.
+ *
+ * This module provides utilities for type-safe Web Worker communication
+ * using an RPC (Remote Procedure Call) pattern. It allows you to call
+ * methods on a worker as if they were local async functions.
+ *
+ * @example
+ * Main thread usage:
+ * ```typescript
+ * import { wrap, terminate } from '@wordpress/worker-threads';
+ * import type { WorkerAPI } from './worker';
+ *
+ * const worker = new Worker(new URL('./worker.js', import.meta.url));
+ * const api = wrap<WorkerAPI>(worker);
+ *
+ * const result = await api.processData(data);
+ *
+ * terminate(api);
+ * ```
+ *
+ * Worker thread usage:
+ * ```typescript
+ * import { expose } from '@wordpress/worker-threads';
+ *
+ * const api = {
+ *   async processData(data: ArrayBuffer): Promise<ArrayBuffer> {
+ *     // ... processing
+ *     return result;
+ *   }
+ * };
+ *
+ * expose(api);
+ * export type WorkerAPI = typeof api;
+ * ```
+ */
+
+/**
+ * Wraps a Worker to provide a type-safe RPC interface.
+ */
+export { wrap } from './main-thread';
+
+/**
+ * Terminates a wrapped worker and cleans up resources.
+ */
+export { terminate } from './main-thread';
+
+/**
+ * Exposes an object's methods to be called from the main thread.
+ * This should be called in the worker script.
+ */
+export { expose } from './worker-thread';
+
+/**
+ * Type that converts all methods to async versions.
+ */
+export type { Remote } from './types';

package/src/main-thread.ts

@@ -0,0 +1,123 @@
+/**
+ * External dependencies
+ */
+import {
+	defineProxy,
+	type Adapter,
+	type SendMessage,
+	type OnMessage,
+} from 'comctx';
+
+/**
+ * Internal dependencies
+ */
+import { WORKER_SYMBOL, type Remote, type WithWorker } from './types';
+
+/**
+ * Adapter for injecting (main thread calling worker).
+ */
+class WorkerInjectAdapter implements Adapter {
+	private worker: Worker;
+
+	constructor( worker: Worker ) {
+		this.worker = worker;
+	}
+
+	sendMessage: SendMessage = ( message, transfer ) => {
+		this.worker.postMessage( message, transfer );
+	};
+
+	onMessage: OnMessage = ( callback ) => {
+		const handler = ( event: MessageEvent ) => callback( event.data );
+		this.worker.addEventListener( 'message', handler );
+		return () => this.worker.removeEventListener( 'message', handler );
+	};
+}
+
+/**
+ * WeakMap to store workers for each remote proxy.
+ */
+const remoteWorkers = new WeakMap< object, Worker >();
+
+/**
+ * Wraps a Worker to provide a type-safe RPC interface.
+ *
+ * The returned proxy object allows calling methods on the worker as if they
+ * were local async functions. Each method call is automatically serialized,
+ * sent to the worker, and the result is returned as a Promise.
+ *
+ * @example
+ * ```typescript
+ * const worker = new Worker(new URL('./worker.js', import.meta.url));
+ * const api = wrap<MyWorkerAPI>(worker);
+ *
+ * // Call worker methods as async functions
+ * const result = await api.processData(data);
+ * ```
+ *
+ * @param worker - The Worker instance to wrap.
+ * @return A proxy object with all exposed methods as async functions.
+ */
+export function wrap< T extends object >( worker: Worker ): Remote< T > {
+	// Create the inject function using defineProxy with an empty object
+	// (the actual implementation is on the worker side).
+	const [ , inject ] = defineProxy( () => ( {} ) as T, {
+		namespace: '__wordpress_worker__',
+		heartbeatCheck: false,
+		transfer: true,
+	} );
+
+	// Create the proxy using the injector.
+	const comctxRemote = inject( new WorkerInjectAdapter( worker ) );
+
+	// Store the worker reference.
+	remoteWorkers.set( comctxRemote as object, worker );
+
+	// Create a wrapper proxy that adds WORKER_SYMBOL support.
+	const proxy = new Proxy( comctxRemote as Remote< T > & WithWorker, {
+		get( target, prop: string | symbol ) {
+			// Return the worker for the WORKER_SYMBOL.
+			if ( prop === WORKER_SYMBOL ) {
+				return worker;
+			}
+
+			// Delegate all other property access to the comctx remote.
+			return Reflect.get( target, prop );
+		},
+	} );
+
+	// Store the worker for the proxy as well.
+	remoteWorkers.set( proxy, worker );
+
+	return proxy;
+}
+
+/**
+ * Terminates a wrapped worker and cleans up resources.
+ *
+ * After calling terminate, any pending calls will be rejected and the
+ * worker will be stopped.
+ *
+ * @example
+ * ```typescript
+ * const api = wrap<MyWorkerAPI>(worker);
+ * // ... use the API ...
+ * terminate(api); // Clean up when done
+ * ```
+ *
+ * @param remote - The wrapped worker proxy returned by wrap().
+ */
+export function terminate( remote: Remote< unknown > ): void {
+	// Get the worker from the proxy.
+	const worker = ( remote as unknown as WithWorker )[ WORKER_SYMBOL ];
+
+	if ( ! worker ) {
+		return;
+	}
+
+	// Clean up the worker reference.
+	remoteWorkers.delete( remote as object );
+
+	// Terminate the worker.
+	worker.terminate();
+}

package/src/test/main-thread.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Internal dependencies
+ */
+import { wrap, terminate } from '../main-thread';
+import { WORKER_SYMBOL } from '../types';
+
+/**
+ * Mock Worker class for testing.
+ * Implements addEventListener pattern used by comctx.
+ */
+class MockWorker {
+	postMessage = jest.fn();
+	terminate = jest.fn();
+
+	private messageListeners: Array< ( event: MessageEvent ) => void > = [];
+
+	addEventListener( type: string, handler: ( event: MessageEvent ) => void ) {
+		if ( type === 'message' ) {
+			this.messageListeners.push( handler );
+		}
+	}
+
+	removeEventListener(
+		type: string,
+		handler: ( event: MessageEvent ) => void
+	) {
+		if ( type === 'message' ) {
+			this.messageListeners = this.messageListeners.filter(
+				( h ) => h !== handler
+			);
+		}
+	}
+
+	/**
+	 * Simulate receiving a message from the worker.
+	 *
+	 * @param data
+	 */
+	simulateMessage( data: unknown ) {
+		for ( const handler of this.messageListeners ) {
+			handler( { data } as MessageEvent );
+		}
+	}
+}
+
+describe( 'main-thread', () => {
+	describe( 'wrap', () => {
+		it( 'should return a proxy object', () => {
+			const worker = new MockWorker();
+			const remote = wrap( worker as unknown as Worker );
+
+			expect( remote ).toBeDefined();
+			expect( typeof remote ).toBe( 'object' );
+		} );
+
+		it( 'should return WORKER_SYMBOL reference', () => {
+			const worker = new MockWorker();
+			const remote = wrap( worker as unknown as Worker );
+
+			expect(
+				( remote as unknown as Record< symbol, unknown > )[
+					WORKER_SYMBOL
+				]
+			).toBe( worker );
+		} );
+
+		it( 'should return functions for property access', () => {
+			const worker = new MockWorker();
+			const remote = wrap< { testMethod: () => void } >(
+				worker as unknown as Worker
+			);
+
+			expect( typeof remote.testMethod ).toBe( 'function' );
+		} );
+
+		it( 'should return a Promise from method calls', () => {
+			const worker = new MockWorker();
+			const remote = wrap< { testMethod: () => string } >(
+				worker as unknown as Worker
+			);
+
+			const result = remote.testMethod();
+
+			expect( result ).toBeInstanceOf( Promise );
+		} );
+
+		it( 'should handle multiple concurrent calls returning promises', async () => {
+			const worker = new MockWorker();
+			const remote = wrap< { method: ( n: number ) => number } >(
+				worker as unknown as Worker
+			);
+
+			// Make concurrent calls.
+			const promise1 = remote.method( 1 );
+			const promise2 = remote.method( 2 );
+
+			// Both should be pending promises.
+			expect( promise1 ).toBeInstanceOf( Promise );
+			expect( promise2 ).toBeInstanceOf( Promise );
+		} );
+	} );
+
+	describe( 'terminate', () => {
+		it( 'should call worker.terminate()', () => {
+			const worker = new MockWorker();
+			const remote = wrap( worker as unknown as Worker );
+
+			terminate( remote );
+
+			expect( worker.terminate ).toHaveBeenCalled();
+		} );
+
+		it( 'should handle terminate called multiple times', () => {
+			const worker = new MockWorker();
+			const remote = wrap( worker as unknown as Worker );
+
+			terminate( remote );
+			terminate( remote );
+
+			// Should not throw - worker.terminate() is idempotent.
+			expect( worker.terminate ).toHaveBeenCalled();
+		} );
+
+		it( 'should handle terminate on non-wrapped object', () => {
+			const notWrapped = {} as ReturnType< typeof wrap >;
+
+			// Should not throw.
+			expect( () => terminate( notWrapped ) ).not.toThrow();
+		} );
+	} );
+} );

package/src/test/worker-thread.test.ts

@@ -0,0 +1,118 @@
+// Store the original self.
+const originalSelf = globalThis.self;
+
+// Mock self for worker context.
+let mockPostMessage: jest.Mock;
+let messageListeners: Array< ( event: MessageEvent ) => void > = [];
+
+function setupMockSelf() {
+	mockPostMessage = jest.fn();
+	messageListeners = [];
+
+	// Override self with addEventListener pattern (matching comctx usage).
+	const mockSelf = {
+		postMessage: mockPostMessage,
+		addEventListener: (
+			type: string,
+			handler: ( event: MessageEvent ) => void
+		) => {
+			if ( type === 'message' ) {
+				messageListeners.push( handler );
+			}
+		},
+		removeEventListener: (
+			type: string,
+			handler: ( event: MessageEvent ) => void
+		) => {
+			if ( type === 'message' ) {
+				messageListeners = messageListeners.filter(
+					( h ) => h !== handler
+				);
+			}
+		},
+	};
+
+	Object.defineProperty( globalThis, 'self', {
+		value: mockSelf,
+		writable: true,
+		configurable: true,
+	} );
+}
+
+function restoreSelf() {
+	Object.defineProperty( globalThis, 'self', {
+		value: originalSelf,
+		writable: true,
+		configurable: true,
+	} );
+	messageListeners = [];
+}
+
+describe( 'worker-thread', () => {
+	beforeEach( () => {
+		setupMockSelf();
+		jest.resetModules();
+	} );
+
+	afterEach( () => {
+		restoreSelf();
+	} );
+
+	describe( 'expose', () => {
+		it( 'should set up message handler', async () => {
+			const { expose } = await import( '../worker-thread' );
+			const api = { method: jest.fn() };
+
+			expose( api );
+
+			expect( messageListeners.length ).toBeGreaterThan( 0 );
+		} );
+
+		it( 'should register handlers for all methods on target', async () => {
+			const { expose } = await import( '../worker-thread' );
+			const method1 = jest.fn();
+			const method2 = jest.fn();
+			const api = {
+				method1,
+				method2,
+				notAFunction: 'string value',
+			};
+
+			// expose() should complete without error.
+			expect( () => expose( api ) ).not.toThrow();
+		} );
+
+		it( 'should only expose functions, not other properties', async () => {
+			const { expose } = await import( '../worker-thread' );
+			const api = {
+				validMethod: jest.fn(),
+				stringProp: 'not a function',
+				numberProp: 42,
+				objectProp: { nested: true },
+			};
+
+			// Should not throw.
+			expect( () => expose( api ) ).not.toThrow();
+		} );
+
+		it( 'should handle empty object', async () => {
+			const { expose } = await import( '../worker-thread' );
+			const api = {};
+
+			// Should not throw.
+			expect( () => expose( api ) ).not.toThrow();
+		} );
+
+		it( 'should handle object with async methods', async () => {
+			const { expose } = await import( '../worker-thread' );
+			const api = {
+				asyncMethod: async () => {
+					return 'async result';
+				},
+				syncMethod: () => 'sync result',
+			};
+
+			expect( () => expose( api ) ).not.toThrow();
+		} );
+	} );
+} );

package/src/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Converts a type to its "remote" version where all methods become async.
+ *
+ * This type transformation ensures that when calling methods on a wrapped
+ * worker, the return types are properly wrapped in Promises.
+ */
+export type Remote< T > = {
+	[ K in keyof T ]: T[ K ] extends ( ...args: infer A ) => infer R
+		? ( ...args: A ) => Promise< Awaited< R > >
+		: never;
+};
+
+/**
+ * Internal symbol used to store the worker reference on the proxy.
+ */
+export const WORKER_SYMBOL = Symbol( 'worker' );
+
+/**
+ * Interface for objects that have an associated worker.
+ */
+export interface WithWorker {
+	[ WORKER_SYMBOL ]: Worker;
+}

package/src/worker-thread.ts

@@ -0,0 +1,67 @@
+/**
+ * External dependencies
+ */
+import {
+	defineProxy,
+	type Adapter,
+	type SendMessage,
+	type OnMessage,
+} from 'comctx';
+
+/**
+ * Adapter for providing (worker exposing methods to main thread).
+ */
+class WorkerProvideAdapter implements Adapter {
+	sendMessage: SendMessage = ( message, transfer ) => {
+		self.postMessage( message, { transfer } );
+	};
+
+	onMessage: OnMessage = ( callback ) => {
+		const handler = ( event: MessageEvent ) => callback( event.data );
+		self.addEventListener( 'message', handler );
+		return () => self.removeEventListener( 'message', handler );
+	};
+}
+
+/**
+ * Exposes an object's methods to be called from the main thread.
+ *
+ * This function should be called in the worker script to make methods
+ * available for RPC calls. Only methods (functions) on the object will
+ * be exposed; other properties are ignored.
+ *
+ * @example
+ * ```typescript
+ * // worker.ts
+ * import { expose } from '@wordpress/worker-threads/worker';
+ *
+ * const api = {
+ *   async processImage(buffer: ArrayBuffer): Promise<ArrayBuffer> {
+ *     // ... processing logic
+ *     return resultBuffer;
+ *   },
+ *
+ *   async calculateSum(a: number, b: number): Promise<number> {
+ *     return a + b;
+ *   }
+ * };
+ *
+ * expose(api);
+ *
+ * // Export the type for use with wrap() on main thread
+ * export type WorkerAPI = typeof api;
+ * ```
+ *
+ * @param target - Object containing methods to expose to the main thread.
+ */
+export function expose< T extends object >( target: T ): void {
+	// Create the provide function using defineProxy with the target.
+	const [ provide ] = defineProxy( () => target, {
+		namespace: '__wordpress_worker__',
+		heartbeatCheck: false,
+		transfer: true,
+	} );
+
+	// Start providing the target through the adapter.
+	provide( new WorkerProvideAdapter() );
+}