@vrowzer/service-worker-server 0.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 kazuya kawaguchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @vrowzer/service-worker-server
+
+A Node.js HTTP Server-like interface for Service Worker environments. Wraps `@vrowzer/service-worker` to provide familiar `listen()` / `close()` / event patterns for handling fetch events and MessageChannel connections inside a Service Worker.
+
+## 💿 Installation
+
+```sh
+# npm
+npm install --save @vrowzer/service-worker-server
+
+# pnpm
+pnpm add @vrowzer/service-worker-server
+
+# yarn
+yarn add @vrowzer/service-worker-server
+
+# bun
+bun add @vrowzer/service-worker-server
+```
+
+## 🚀 Usage
+
+```ts
+import { createSvcWorkerServer } from '@vrowzer/service-worker-server'
+
+const server = createSvcWorkerServer(self, {
+  version: 'v1',
+  claimOnActivate: true
+})
+
+// Set fetch handler (like Node.js HTTP request handler)
+server.setFetchHandler(event => {
+  event.respondWith(new Response('Hello from Service Worker!'))
+})
+
+// Start listening for fetch events
+server.listen()
+
+server.on('listening', () => {
+  console.log('Service Worker server is listening')
+})
+
+server.on('error', err => {
+  console.error('Server error:', err)
+})
+```
+
+### MessageChannel Connections
+
+```ts
+const server = createSvcWorkerServer(self, { version: 'v1' })
+
+server.setFetchHandler(event => {
+  event.respondWith(new Response('OK'))
+})
+
+// Enable listening for MessageChannel port connections
+server.listen({ enableListenConnections: true })
+
+server.on('connection', event => {
+  console.log('Client connected:', event.clientId)
+  console.log('Ports:', event.ports)
+  console.log('Data:', event.data)
+})
+```
+
+## 📖 API Documentation
+
+See [packages/service-worker/docs](../service-worker/docs/) for full API documentation.
+
+## 🤝 Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg">
+    <img alt="sponsor" src='https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg'/>
+  </a>
+</p>
+
+## ©️ License
+
+[MIT](http://opensource.org/licenses/MIT)

package/dist/index.d.ts

@@ -0,0 +1,240 @@
+import { Emittable } from "@kazupon/jts-utils/event/emitter";
+
+//#region ../service-worker/src/worker.d.ts
+
+/**
+* Service Worker options for {@link createSvcWorker}
+*/
+interface SvcWorkerOptions {
+  /**
+  * The version of this service worker
+  * This is used to identify the service worker when communicating with {@link SvcWorkerController}
+  */
+  version: string;
+  /**
+  * Heartbeat interval in milliseconds
+  * @default 30000
+  */
+  heartbeatInterval?: number;
+  /**
+  * Timeout after which a session is considered stale (no PONG received)
+  * @default 60000
+  */
+  sessionTimeout?: number;
+  /**
+  * Debug logger function
+  */
+  debug?: Console["debug"];
+}
+//#endregion
+//#region src/index.d.ts
+/**
+* Service worker server error
+*/
+declare class SvcWorkerServerError extends Error {
+  name: string;
+  constructor(message: string, cause?: Error);
+}
+/**
+* The {@link SvcWorkerServer} constructor options
+*/
+interface SvcWorkerServerOptions extends SvcWorkerOptions {
+  /**
+  * Automatically call `clients.claim()` on `activate` event.
+  */
+  claimOnActivate?: boolean;
+}
+/**
+* Extend {@link ServiceWorkerState} with additional states
+*
+* - 'suspended': State when {@link SvcWorker | service worker} is suspended.
+*/
+type SvcWorkerServerState = ServiceWorkerState | "suspended";
+/**
+* Options for the {@link SvcWorkerServer.listen} method
+*/
+interface ListenOptions {
+  /**
+  * Timeout in milliseconds for waiting for the activate event.
+  * If the timeout is exceeded, an 'error' event is emitted.
+  * @default 30000 (30 seconds)
+  */
+  activateTimeout?: number;
+  /**
+  * Enable listening for MessageChannel port connections.
+  * If set to true, the server will accept connections via `message` events from clients.
+  * @default false
+  */
+  enableListenConnections?: boolean;
+}
+/**
+* Connection event payload for {@link MessageChannel} connections.
+*
+* This interface represents a connection event that is emitted when a client
+* sends a message with {@link MessagePort | MessagePorts} (typically for establishing a MessageChannel connection).
+*
+* @typeParam T - The type of the message data. Defaults to `unknown`.
+*
+* @example
+* ```ts
+* interface MyMessage {
+*   type: 'greeting' | 'farewell'
+*   payload: string
+* }
+*
+* const server = createSvcWorkerServer<MyMessage>(self, options)
+* server.on('connection', (event) => {
+*   // event.data is typed as MyMessage
+*   console.log(event.data.type, event.data.payload)
+*   // Access the MessagePorts
+*   console.log(event.ports)
+* })
+* ```
+*/
+interface ConnectionEvent<T = unknown> {
+  /**
+  * The MessagePorts received from the client.
+  */
+  readonly ports: readonly MessagePort[];
+  /**
+  * The source of the message (Client, ServiceWorker, or MessagePort).
+  */
+  readonly source: Client | ServiceWorker | MessagePort | null;
+  /**
+  * The message data with type safety.
+  */
+  readonly data: T;
+  /**
+  * The client ID if the source is a Client.
+  */
+  readonly clientId?: string;
+}
+/**
+* Event map for {@link SvcWorkerServer}.
+*
+* This type defines the payload types for each event.
+*
+* @typeParam MessageData - The type of the message data for the `connection` event. Defaults to `unknown`.
+*/
+type SvcWorkerServerEventMap<MessageData = unknown> = {
+  /**
+  * Emitted when the server starts listening for fetch events.
+  */
+  listening: void;
+  /**
+  * Emitted when a client connects via MessageChannel.
+  * This event is fired only when the message contains MessagePorts.
+  */
+  connection: ConnectionEvent<MessageData>;
+  /**
+  * Emitted when the server is closed.
+  */
+  close: void;
+  /**
+  * Emitted when an error occurs.
+  */
+  error: Error;
+};
+/**
+* The Server for service worker environment
+*
+* This interface has like Node.js HTTP Server interfaces.
+* This will be used as server that runs within a Service Worker environment.
+*
+* @typeParam MessageData - The type of the message data for the `connection` event. Defaults to `unknown`.
+*/
+interface SvcWorkerServer<MessageData = unknown> extends Emittable<SvcWorkerServerEventMap<MessageData>>, Disposable, AsyncDisposable {
+  /**
+  * The current state of the server
+  */
+  readonly state: SvcWorkerServerState;
+  /**
+  * Set a fetch event handler
+  * @param handler - A function to handle fetch events
+  */
+  setFetchHandler(handler: (event: FetchEvent) => void): void;
+  /**
+  * Start a server listening for service worker fetch events
+  *
+  * When the service worker fetch event handler is bound, the 'listening' event will be emitted.
+  * If `enableListenConnections` option is set to `true`, server will be started to listen MessageChannel connection too via {@link SvcWorkerServer.listenConnections} internally.
+  *
+  * @param options - Options for listening
+  * @returns The server instance
+  * @throws {SvcWorkerServerError} When the server is already listening or fetch handler is not set
+  */
+  listen(options?: ListenOptions): SvcWorkerServer<MessageData>;
+  /**
+  * Start a MessageChannel port connections listening with `message` events from clients.
+  *
+  * @returns The server instance
+  */
+  listenConnections(): SvcWorkerServer<MessageData>;
+  /**
+  * Stops the server from accepting new fetch event and close {@link MessageChannel} port connections
+  *
+  * When it will be finished, the optional callback `fn` will be called, and trigger 'close' event.
+  *
+  * @param cb - An optional callback function which will be called when the server is closed
+  * @param stopConnectionListening - If `true`, also stops listening for MessageChannel port connections too via {@link SvcWorkerServer.closeConnections}. Defaults to `false`.
+  * @returns The server instance
+  */
+  close(cb?: (err?: Error) => void, stopConnectionListening?: boolean): SvcWorkerServer<MessageData>;
+  /**
+  * Closes {@link MessageChannel} port connections connected to this server.
+  *
+  * @param cb - An optional callback function which will be called when MessageChannel port connections are closed
+  * @returns The server instance
+  */
+  closeConnections(cb?: (err?: Error) => void): SvcWorkerServer<MessageData>;
+  /**
+  * Returns the bound service worker address
+  *
+  * the address service worker script URL, or `null` if the server is not listening.
+  *
+  * @returns The service worker script URL or `null`
+  */
+  address(): URL | null;
+  /**
+  * Asynchronously get the number of concurrent {@link MessageChannel} port connections on the server.
+  */
+  getConnections(cb: (error: Error | null, count: number) => void): SvcWorkerServer<MessageData>;
+  /**
+  * `Symbol.dispose` for `using` syntax support (TypeScript 5.2+)
+  */
+  [Symbol.dispose](): void;
+  /**
+  * Calls `close()` and returns a promise that fulfills when the server has closed.
+  */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+* Create a {@link SvcWorkerServer | Service worker server} instance.
+*
+* @typeParam MessageData - The type of the message data for the `connection` event. Defaults to `unknown`.
+* @param self - The {@link ServiceWorkerGlobalScope} instance (typically `self` in a service worker)
+* @param options - {@link SvcWorkerServerOptions | Service worker server options}
+* @returns {@link SvcWorkerServer | Service worker server instance}
+*
+* @example
+* ```ts
+* interface MyMessage {
+*   type: 'greeting' | 'farewell'
+*   payload: string
+* }
+*
+* const server = createSvcWorkerServer<MyMessage>(self, { version: '1.0.0' })
+* server.on('connection', (event) => {
+*   // event.data is typed as MyMessage
+*   console.log(event.data.type, event.data.payload)
+*   // Access the MessagePorts
+*   console.log(event.ports)
+*   // Access client ID if available
+*   console.log(event.clientId)
+* })
+* ```
+*/
+declare function createSvcWorkerServer<MessageData = unknown>(self: ServiceWorkerGlobalScope, options: SvcWorkerServerOptions): SvcWorkerServer<MessageData>;
+//#endregion
+export { ConnectionEvent, ListenOptions, SvcWorkerServer, SvcWorkerServerError, SvcWorkerServerEventMap, SvcWorkerServerOptions, SvcWorkerServerState, createSvcWorkerServer };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../service-worker/src/worker.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;;;ACoBA;AAUA;AAYA;AAKiB,UDiDA,gBAAA,CCjDA;EAuCjB;;;;EAQ4C,OAAA,EAAA,MAAA;EAI3B;;AAcjB;;EASc,iBAAA,CAAA,EAAA,MAAA;EAQL;;AAgBT;;EACoB,cAAA,CAAA,EAAA,MAAA;EAIF;;;EAkBiC,KAAA,CAAA,EDlDzC,OCkDyC,CAAA,OAAA,CAAA;;;;;ADxEnD;;cC5Ea,oBAAA,SAA6B,KAAA;;EAA1C,WAAa,CAAA,OAAA,EAAA,MAAA,EAAA,KAE0B,CAF1B,EAE0B,KAAA;AAQvC;AAYA;AAKA;AAuCA;AAI2B,UA5DV,sBAAA,SAA+B,gBA4DrB,CAAA;EAIR;;;EAIF,eAAA,CAAA,EAAA,OAAA;;AAcjB;;;;;AAiCiB,KAvGL,oBAAA,GAAuB,kBAuGlB,GAAA,WAAA;;;;AAWkB,UA7GlB,aAAA,CA6GkB;EAYhB;;;;;EAkBC,eAAA,CAAA,EAAA,MAAA;EAAoE;;;;;EAiB3E,uBAAA,CAAA,EAAA,OAAA;;;;;;;;;AA4Cb;;;;;;;;;;;;;;;;;UAjKiB;;;;2BAIU;;;;mBAIR,SAAS,gBAAgB;;;;iBAI3B;;;;;;;;;;;;;KAcL;;;;;;;;;cASE,gBAAgB;;;;;;;;SAQrB;;;;;;;;;;UAgBQ,+CACP,UAAU,wBAAwB,eAAe,YAAY;;;;kBAIrD;;;;;mCAMiB;;;;;;;;;;;mBAYhB,gBAAgB,gBAAgB;;;;;;uBAO5B,gBAAgB;;;;;;;;;;oBAWnB,oDAAoD,gBAAgB;;;;;;;+BAQzD,iBAAiB,gBAAgB;;;;;;;;aASnD;;;;6BAKgB,uCAAuC,gBAAgB;;;;;;;;2BAUzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BX,mDACR,mCACG,yBACR,gBAAgB"}

package/dist/index.js

@@ -0,0 +1,225 @@
+import { Emitter } from "@kazupon/jts-utils/event";
+import { createSvcWorker } from "@vrowzer/service-worker/worker";
+
+//#region src/index.ts
+/**
+* This entry file is for service worker server
+*
+* @module service-worker-server
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Service worker server error
+*/
+var SvcWorkerServerError = class extends Error {
+	name = "SvcWorkerServerError";
+	constructor(message, cause) {
+		super(message, { cause });
+	}
+};
+/**
+* Default timeout for waiting for the activate event (30 seconds)
+*/
+const DEFAULT_ACTIVATE_TIMEOUT = 3e4;
+/**
+* Create a {@link SvcWorkerServer | Service worker server} instance.
+*
+* @typeParam MessageData - The type of the message data for the `connection` event. Defaults to `unknown`.
+* @param self - The {@link ServiceWorkerGlobalScope} instance (typically `self` in a service worker)
+* @param options - {@link SvcWorkerServerOptions | Service worker server options}
+* @returns {@link SvcWorkerServer | Service worker server instance}
+*
+* @example
+* ```ts
+* interface MyMessage {
+*   type: 'greeting' | 'farewell'
+*   payload: string
+* }
+*
+* const server = createSvcWorkerServer<MyMessage>(self, { version: '1.0.0' })
+* server.on('connection', (event) => {
+*   // event.data is typed as MyMessage
+*   console.log(event.data.type, event.data.payload)
+*   // Access the MessagePorts
+*   console.log(event.ports)
+*   // Access client ID if available
+*   console.log(event.clientId)
+* })
+* ```
+*/
+function createSvcWorkerServer(self, options) {
+	const _emitter = Emitter();
+	const _svcWorker = createSvcWorker(self, options);
+	const _options = options;
+	const _ports = /* @__PURE__ */ new Set();
+	let _listening = false;
+	let _listeningConnections = false;
+	let _fetchHandler = null;
+	let _boundFetchHandler = null;
+	let _activateHandler = null;
+	let _activateTimeoutId = null;
+	let _messageHandler = null;
+	/**
+	* Cleanup activate waiting state (timeout and handler)
+	*/
+	function cleanupActivateWaiting() {
+		if (_activateTimeoutId !== null) {
+			clearTimeout(_activateTimeoutId);
+			_activateTimeoutId = null;
+		}
+		if (_activateHandler) {
+			_svcWorker.removeEventListener("activate", _activateHandler);
+			_activateHandler = null;
+		}
+	}
+	function listenConnections() {
+		if (_listeningConnections) return instance;
+		_messageHandler = (event) => {
+			if (event.ports && event.ports.length > 0) {
+				for (const port of event.ports) _ports.add(port);
+				const clientId = event.source?.id;
+				const connectionEvent = {
+					ports: event.ports,
+					source: event.source,
+					data: event.data,
+					...clientId !== void 0 && { clientId }
+				};
+				_emitter.emit("connection", connectionEvent);
+			}
+		};
+		self.addEventListener("message", _messageHandler);
+		_listeningConnections = true;
+		return instance;
+	}
+	function setFetchHandler(handler) {
+		if (typeof handler !== "function") throw new SvcWorkerServerError("fetch handler must be a function");
+		if (_boundFetchHandler) _svcWorker.removeEventListener("fetch", _boundFetchHandler);
+		_fetchHandler = handler;
+		_boundFetchHandler = (event) => {
+			if (!_listening || _svcWorker.suspended) return;
+			try {
+				_fetchHandler(event);
+			} catch (err) {
+				_emitter.emit("error", err);
+			}
+		};
+		_svcWorker.addEventListener("fetch", _boundFetchHandler);
+	}
+	function listen(listenOptions) {
+		if (_listening) {
+			queueMicrotask(() => _emitter.emit("error", new SvcWorkerServerError("Server is already listening")));
+			return instance;
+		}
+		if (!_fetchHandler) {
+			queueMicrotask(() => _emitter.emit("error", new SvcWorkerServerError("Fetch handler not set. Call setFetchHandler() first.")));
+			return instance;
+		}
+		const activateTimeout = listenOptions?.activateTimeout ?? DEFAULT_ACTIVATE_TIMEOUT;
+		const enableListenConnections = listenOptions?.enableListenConnections ?? false;
+		_listening = true;
+		if (enableListenConnections) listenConnections();
+		if (_svcWorker.registration.active !== null) queueMicrotask(() => {
+			if (_listening) _emitter.emit("listening");
+		});
+		else {
+			_activateTimeoutId = setTimeout(() => {
+				cleanupActivateWaiting();
+				if (_listening) {
+					_listening = false;
+					_fetchHandler = null;
+					_boundFetchHandler = null;
+					_emitter.emit("error", new SvcWorkerServerError(`Activate timeout: Service Worker did not activate within ${activateTimeout}ms`));
+				}
+			}, activateTimeout);
+			_activateHandler = (event) => {
+				cleanupActivateWaiting();
+				if (_options.claimOnActivate) {
+					const serviceWorkerScope = _svcWorker;
+					event.waitUntil(serviceWorkerScope.clients.claim());
+				}
+				if (_listening) _emitter.emit("listening");
+			};
+			_svcWorker.addEventListener("activate", _activateHandler);
+		}
+		return instance;
+	}
+	function closeConnections(cb) {
+		if (_messageHandler) {
+			self.removeEventListener("message", _messageHandler);
+			_messageHandler = null;
+		}
+		closeAllConnections();
+		_listeningConnections = false;
+		queueMicrotask(() => {
+			cb?.();
+		});
+		return instance;
+	}
+	function close(cb, stopConnectionListening) {
+		if (!_listening) {
+			queueMicrotask(() => {
+				cb?.();
+				_emitter.emit("close");
+			});
+			return instance;
+		}
+		cleanupActivateWaiting();
+		if (_boundFetchHandler) {
+			_svcWorker.removeEventListener("fetch", _boundFetchHandler);
+			_boundFetchHandler = null;
+		}
+		if (stopConnectionListening) closeConnections();
+		_fetchHandler = null;
+		_listening = false;
+		queueMicrotask(() => {
+			cb?.();
+			_emitter.emit("close");
+		});
+		return instance;
+	}
+	function address() {
+		return null;
+	}
+	function getConnections(cb) {
+		queueMicrotask(() => cb(null, _ports.size));
+		return instance;
+	}
+	function closeAllConnections() {
+		for (const port of _ports) port.close();
+		_ports.clear();
+	}
+	function dispose() {
+		close();
+	}
+	async function asyncDispose() {
+		return new Promise((resolve, reject) => {
+			close((err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+	}
+	const instance = {
+		..._emitter,
+		get state() {
+			return "installing";
+		},
+		setFetchHandler,
+		listen,
+		listenConnections,
+		close,
+		closeConnections,
+		address,
+		getConnections,
+		[Symbol.dispose]: dispose,
+		[Symbol.asyncDispose]: asyncDispose
+	};
+	return instance;
+}
+
+//#endregion
+export { SvcWorkerServerError, createSvcWorkerServer };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_svcWorker: SvcWorker","_ports: Set<MessagePort>","_fetchHandler: ((event: FetchEvent) => void) | null","_boundFetchHandler: ((event: FetchEvent) => void) | null","_activateHandler: ((event: ExtendableEvent) => void) | null","_activateTimeoutId: ReturnType<typeof setTimeout> | null","_messageHandler: ((event: ExtendableMessageEvent) => void) | null","connectionEvent: ConnectionEvent<MessageData>","instance: SvcWorkerServer<MessageData>"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * This entry file is for service worker server\n *\n * @module service-worker-server\n */\n\n/**\n * @author kazuya kawaguchi (a.k.a. kazupon)\n * @license MIT\n */\n\nimport { Emitter } from '@kazupon/jts-utils/event'\nimport { createSvcWorker } from '@vrowzer/service-worker/worker'\n\nimport type { Emittable } from '@kazupon/jts-utils/event/emitter'\nimport type { SvcWorker, SvcWorkerOptions } from '@vrowzer/service-worker/worker'\n\n/**\n * Service worker server error\n */\nexport class SvcWorkerServerError extends Error {\n  name = 'SvcWorkerServerError'\n  constructor(message: string, cause?: Error) {\n    super(message, { cause })\n  }\n}\n\n/**\n * The {@link SvcWorkerServer} constructor options\n */\nexport interface SvcWorkerServerOptions extends SvcWorkerOptions {\n  /**\n   * Automatically call `clients.claim()` on `activate` event.\n   */\n  claimOnActivate?: boolean\n}\n\n/**\n * Extend {@link ServiceWorkerState} with additional states\n *\n * - 'suspended': State when {@link SvcWorker | service worker} is suspended.\n */\nexport type SvcWorkerServerState = ServiceWorkerState | 'suspended'\n\n/**\n * Options for the {@link SvcWorkerServer.listen} method\n */\nexport interface ListenOptions {\n  /**\n   * Timeout in milliseconds for waiting for the activate event.\n   * If the timeout is exceeded, an 'error' event is emitted.\n   * @default 30000 (30 seconds)\n   */\n  activateTimeout?: number\n  /**\n   * Enable listening for MessageChannel port connections.\n   * If set to true, the server will accept connections via `message` events from clients.\n   * @default false\n   */\n  enableListenConnections?: boolean\n}\n\n/**\n * Connection event payload for {@link MessageChannel} connections.\n *\n * This interface represents a connection event that is emitted when a client\n * sends a message with {@link MessagePort | MessagePorts} (typically for establishing a MessageChannel connection).\n *\n * @typeParam T - The type of the message data. Defaults to `unknown`.\n *\n * @example\n * ```ts\n * interface MyMessage {\n *   type: 'greeting' | 'farewell'\n *   payload: string\n * }\n *\n * const server = createSvcWorkerServer<MyMessage>(self, options)\n * server.on('connection', (event) => {\n *   // event.data is typed as MyMessage\n *   console.log(event.data.type, event.data.payload)\n *   // Access the MessagePorts\n *   console.log(event.ports)\n * })\n * ```\n */\nexport interface ConnectionEvent<T = unknown> {\n  /**\n   * The MessagePorts received from the client.\n   */\n  readonly ports: readonly MessagePort[]\n  /**\n   * The source of the message (Client, ServiceWorker, or MessagePort).\n   */\n  readonly source: Client | ServiceWorker | MessagePort | null\n  /**\n   * The message data with type safety.\n   */\n  readonly data: T\n  /**\n   * The client ID if the source is a Client.\n   */\n  readonly clientId?: string\n}\n\n/**\n * Event map for {@link SvcWorkerServer}.\n *\n * This type defines the payload types for each event.\n *\n * @typeParam MessageData - The type of the message data for the `connection` event. Defaults to `unknown`.\n */\nexport type SvcWorkerServerEventMap<MessageData = unknown> = {\n  /**\n   * Emitted when the server starts listening for fetch events.\n   */\n  listening: void\n  /**\n   * Emitted when a client connects via MessageChannel.\n   * This event is fired only when the message contains MessagePorts.\n   */\n  connection: ConnectionEvent<MessageData>\n  /**\n   * Emitted when the server is closed.\n   */\n  close: void\n  /**\n   * Emitted when an error occurs.\n   */\n  error: Error\n}\n\n/**\n * Default timeout for waiting for the activate event (30 seconds)\n */\nconst DEFAULT_ACTIVATE_TIMEOUT = 30000\n\n/**\n * The Server for service worker environment\n *\n * This interface has like Node.js HTTP Server interfaces.\n * This will be used as server that runs within a Service Worker environment.\n *\n * @typeParam MessageData - The type of the message data for the `connection` event. Defaults to `unknown`.\n */\nexport interface SvcWorkerServer<MessageData = unknown>\n  extends Emittable<SvcWorkerServerEventMap<MessageData>>, Disposable, AsyncDisposable {\n  /**\n   * The current state of the server\n   */\n  readonly state: SvcWorkerServerState\n\n  /**\n   * Set a fetch event handler\n   * @param handler - A function to handle fetch events\n   */\n  setFetchHandler(handler: (event: FetchEvent) => void): void\n\n  /**\n   * Start a server listening for service worker fetch events\n   *\n   * When the service worker fetch event handler is bound, the 'listening' event will be emitted.\n   * If `enableListenConnections` option is set to `true`, server will be started to listen MessageChannel connection too via {@link SvcWorkerServer.listenConnections} internally.\n   *\n   * @param options - Options for listening\n   * @returns The server instance\n   * @throws {SvcWorkerServerError} When the server is already listening or fetch handler is not set\n   */\n  listen(options?: ListenOptions): SvcWorkerServer<MessageData>\n\n  /**\n   * Start a MessageChannel port connections listening with `message` events from clients.\n   *\n   * @returns The server instance\n   */\n  listenConnections(): SvcWorkerServer<MessageData>\n\n  /**\n   * Stops the server from accepting new fetch event and close {@link MessageChannel} port connections\n   *\n   * When it will be finished, the optional callback `fn` will be called, and trigger 'close' event.\n   *\n   * @param cb - An optional callback function which will be called when the server is closed\n   * @param stopConnectionListening - If `true`, also stops listening for MessageChannel port connections too via {@link SvcWorkerServer.closeConnections}. Defaults to `false`.\n   * @returns The server instance\n   */\n  close(cb?: (err?: Error) => void, stopConnectionListening?: boolean): SvcWorkerServer<MessageData>\n\n  /**\n   * Closes {@link MessageChannel} port connections connected to this server.\n   *\n   * @param cb - An optional callback function which will be called when MessageChannel port connections are closed\n   * @returns The server instance\n   */\n  closeConnections(cb?: (err?: Error) => void): SvcWorkerServer<MessageData>\n\n  /**\n   * Returns the bound service worker address\n   *\n   * the address service worker script URL, or `null` if the server is not listening.\n   *\n   * @returns The service worker script URL or `null`\n   */\n  address(): URL | null\n\n  /**\n   * Asynchronously get the number of concurrent {@link MessageChannel} port connections on the server.\n   */\n  getConnections(cb: (error: Error | null, count: number) => void): SvcWorkerServer<MessageData>\n\n  /**\n   * `Symbol.dispose` for `using` syntax support (TypeScript 5.2+)\n   */\n  [Symbol.dispose](): void\n\n  /**\n   * Calls `close()` and returns a promise that fulfills when the server has closed.\n   */\n  [Symbol.asyncDispose](): Promise<void>\n}\n\n/**\n * Create a {@link SvcWorkerServer | Service worker server} instance.\n *\n * @typeParam MessageData - The type of the message data for the `connection` event. Defaults to `unknown`.\n * @param self - The {@link ServiceWorkerGlobalScope} instance (typically `self` in a service worker)\n * @param options - {@link SvcWorkerServerOptions | Service worker server options}\n * @returns {@link SvcWorkerServer | Service worker server instance}\n *\n * @example\n * ```ts\n * interface MyMessage {\n *   type: 'greeting' | 'farewell'\n *   payload: string\n * }\n *\n * const server = createSvcWorkerServer<MyMessage>(self, { version: '1.0.0' })\n * server.on('connection', (event) => {\n *   // event.data is typed as MyMessage\n *   console.log(event.data.type, event.data.payload)\n *   // Access the MessagePorts\n *   console.log(event.ports)\n *   // Access client ID if available\n *   console.log(event.clientId)\n * })\n * ```\n */\nexport function createSvcWorkerServer<MessageData = unknown>(\n  self: ServiceWorkerGlobalScope,\n  options: SvcWorkerServerOptions\n): SvcWorkerServer<MessageData> {\n  const _emitter = Emitter<SvcWorkerServerEventMap<MessageData>>()\n  const _svcWorker: SvcWorker = createSvcWorker(self, options)\n  const _options = options\n\n  const _ports: Set<MessagePort> = new Set()\n\n  let _listening = false\n  let _listeningConnections = false\n  let _fetchHandler: ((event: FetchEvent) => void) | null = null\n  let _boundFetchHandler: ((event: FetchEvent) => void) | null = null\n  let _activateHandler: ((event: ExtendableEvent) => void) | null = null\n  let _activateTimeoutId: ReturnType<typeof setTimeout> | null = null\n  let _messageHandler: ((event: ExtendableMessageEvent) => void) | null = null\n\n  /**\n   * Cleanup activate waiting state (timeout and handler)\n   */\n  function cleanupActivateWaiting(): void {\n    if (_activateTimeoutId !== null) {\n      clearTimeout(_activateTimeoutId)\n      _activateTimeoutId = null\n    }\n    if (_activateHandler) {\n      _svcWorker.removeEventListener('activate', _activateHandler)\n      _activateHandler = null\n    }\n  }\n\n  function listenConnections(): SvcWorkerServer<MessageData> {\n    // Already listening for connections -> do nothing\n    if (_listeningConnections) {\n      return instance\n    }\n\n    // Register message handler for connection events\n    _messageHandler = (event: ExtendableMessageEvent) => {\n      // Only emit connection event when ports are present\n      if (event.ports && event.ports.length > 0) {\n        // Register ports to the Set\n        for (const port of event.ports) {\n          _ports.add(port)\n        }\n\n        const clientId = (event.source as Client | null)?.id\n        const connectionEvent: ConnectionEvent<MessageData> = {\n          ports: event.ports,\n          source: event.source,\n          data: event.data as MessageData,\n          ...(clientId !== undefined && { clientId })\n        }\n        _emitter.emit('connection', connectionEvent)\n      }\n    }\n    self.addEventListener('message', _messageHandler)\n\n    _listeningConnections = true\n\n    return instance\n  }\n\n  function setFetchHandler(handler: (event: FetchEvent) => void): void {\n    if (typeof handler !== 'function') {\n      throw new SvcWorkerServerError('fetch handler must be a function')\n    }\n\n    // If already registered, remove previous handler first\n    if (_boundFetchHandler) {\n      _svcWorker.removeEventListener('fetch', _boundFetchHandler)\n    }\n\n    // Store user's handler\n    _fetchHandler = handler\n\n    // Create wrapper with suspended/listening check\n    // This wrapper is registered immediately but only calls user's handler when listening\n    _boundFetchHandler = (event: FetchEvent) => {\n      // Don't call user's handler if not listening or suspended\n      if (!_listening || _svcWorker.suspended) {\n        return // Fall through to network\n      }\n      try {\n        _fetchHandler!(event)\n      } catch (err) {\n        _emitter.emit('error', err as Error)\n      }\n    }\n\n    // Register fetch handler immediately (required by Service Worker spec)\n    // IMPORTANT: Service Workers require fetch event listeners to be added during\n    // the initial script execution, not asynchronously during event callbacks.\n    _svcWorker.addEventListener('fetch', _boundFetchHandler)\n  }\n\n  function listen(listenOptions?: ListenOptions): SvcWorkerServer<MessageData> {\n    // Prevent double listen\n    if (_listening) {\n      queueMicrotask(() =>\n        _emitter.emit('error', new SvcWorkerServerError('Server is already listening'))\n      )\n      return instance\n    }\n\n    // Validate fetch handler is set\n    if (!_fetchHandler) {\n      queueMicrotask(() =>\n        _emitter.emit(\n          'error',\n          new SvcWorkerServerError('Fetch handler not set. Call setFetchHandler() first.')\n        )\n      )\n      return instance\n    }\n\n    // Resolve options\n    const activateTimeout = listenOptions?.activateTimeout ?? DEFAULT_ACTIVATE_TIMEOUT\n    const enableListenConnections = listenOptions?.enableListenConnections ?? false\n\n    // Update state - this enables the fetch handler wrapper to call user's handler\n    _listening = true\n\n    // NOTE: addEventListener('fetch') is already registered in setFetchHandler()\n\n    // Register message handler if enableListenConnections is true\n    if (enableListenConnections) {\n      listenConnections()\n    }\n\n    // Check activated state\n    const sw = _svcWorker as unknown as ServiceWorkerGlobalScope\n    const isActivated = sw.registration.active !== null\n\n    if (isActivated) {\n      // Already activated -> emit 'listening' immediately (async)\n      queueMicrotask(() => {\n        if (_listening) {\n          _emitter.emit('listening')\n        }\n      })\n    } else {\n      // Not activated -> wait for activate event with timeout\n\n      // Set timeout\n      _activateTimeoutId = setTimeout(() => {\n        cleanupActivateWaiting()\n        if (_listening) {\n          _listening = false\n          _fetchHandler = null\n          _boundFetchHandler = null\n          _emitter.emit(\n            'error',\n            new SvcWorkerServerError(\n              `Activate timeout: Service Worker did not activate within ${activateTimeout}ms`\n            )\n          )\n        }\n      }, activateTimeout)\n\n      // Set activate handler\n      _activateHandler = (event: ExtendableEvent) => {\n        // Cleanup timeout and handler\n        cleanupActivateWaiting()\n\n        // Call `clients.claim()` if `claimOnActivate` is true\n        if (_options.claimOnActivate) {\n          const serviceWorkerScope = _svcWorker as unknown as ServiceWorkerGlobalScope\n          event.waitUntil(serviceWorkerScope.clients.claim())\n        }\n\n        // Emit listening event after activation\n        if (_listening) {\n          _emitter.emit('listening')\n        }\n      }\n      _svcWorker.addEventListener('activate', _activateHandler)\n    }\n\n    return instance\n  }\n\n  function closeConnections(cb?: (err?: Error) => void): SvcWorkerServer<MessageData> {\n    // Remove message event listener\n    if (_messageHandler) {\n      self.removeEventListener('message', _messageHandler)\n      _messageHandler = null\n    }\n\n    // Close all MessagePort connections\n    closeAllConnections()\n\n    // Update state\n    _listeningConnections = false\n\n    // Emit callback (async)\n    queueMicrotask(() => {\n      cb?.()\n    })\n\n    return instance\n  }\n\n  function close(\n    cb?: (err?: Error) => void,\n    stopConnectionListening?: boolean\n  ): SvcWorkerServer<MessageData> {\n    // Emit callback and 'close' event even if not listening\n    if (!_listening) {\n      queueMicrotask(() => {\n        cb?.()\n        _emitter.emit('close')\n      })\n      return instance\n    }\n\n    // Cleanup activate waiting state (timeout and handler)\n    cleanupActivateWaiting()\n\n    // Remove fetch event listener\n    if (_boundFetchHandler) {\n      _svcWorker.removeEventListener('fetch', _boundFetchHandler)\n      _boundFetchHandler = null\n    }\n\n    // Stop connection listening if requested (via closeConnections)\n    if (stopConnectionListening) {\n      closeConnections()\n    }\n\n    // Clear handler reference\n    _fetchHandler = null\n\n    // Update state\n    _listening = false\n\n    // Emit callback and 'close' event (async)\n    queueMicrotask(() => {\n      cb?.()\n      _emitter.emit('close')\n    })\n\n    return instance\n  }\n\n  function address(): URL | null {\n    // TODO: implement\n    return null\n  }\n\n  function getConnections(\n    cb: (error: Error | null, count: number) => void\n  ): SvcWorkerServer<MessageData> {\n    queueMicrotask(() => cb(null, _ports.size))\n    return instance\n  }\n\n  function closeAllConnections(): void {\n    for (const port of _ports) {\n      port.close()\n    }\n    _ports.clear()\n  }\n\n  function dispose(): void {\n    close()\n  }\n\n  async function asyncDispose(): Promise<void> {\n    return new Promise((resolve, reject) => {\n      close(err => {\n        if (err) {\n          reject(err)\n        } else {\n          resolve()\n        }\n      })\n    })\n  }\n\n  const instance: SvcWorkerServer<MessageData> = {\n    ..._emitter,\n    get state(): SvcWorkerServerState {\n      // TODO:\n      return 'installing'\n    },\n    setFetchHandler,\n    listen,\n    listenConnections,\n    close,\n    closeConnections,\n    address,\n    getConnections,\n    [Symbol.dispose]: dispose,\n    [Symbol.asyncDispose]: asyncDispose\n  } as SvcWorkerServer<MessageData>\n\n  return instance\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@vrowzer/service-worker-server",
+  "description": "Serverized service worker with the Node Server interface",
+  "version": "0.0.0",
+  "author": {
+    "name": "kazuya kawaguchi",
+    "email": "kawakazu80@gmail.com"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/kazupon",
+  "bugs": {
+    "url": "https://github.com/kazupon/vrowzer/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazupon/vrowzer.git",
+    "directory": "packages/service-worker-server"
+  },
+  "keywords": [
+    "service-worker",
+    "vrowzer",
+    "server"
+  ],
+  "homepage": "https://github.com/kazupon/vrowzer/packages/service-worker-server/README.md",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 20.19.0"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@kazupon/jts-utils": "^0.17.0",
+    "@vrowzer/service-worker": "0.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.57.0",
+    "get-port-please": "^3.2.0",
+    "publint": "^0.3.18",
+    "tsdown": "0.18.4",
+    "typedoc": "^0.28.17",
+    "vite": "^8.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "build": "tsdown",
+    "build:docs": "typedoc --excludeInternal"
+  }
+}