@tiga-ipc/mmap 0.1.0 → 0.3.0

package/README.md

@@ -2,12 +2,14 @@
 
 `@tiga-ipc/mmap` is the Node.js package for the Tiga memory-mapped IPC protocol.
 
-It provides a small CommonJS wrapper around the native `index.node` addon and exposes the current Tiga channel APIs:
+It provides a CommonJS wrapper around the native `index.node` addon and exposes both low-level channel primitives and a higher-level server helper:
 
 - `initialized()`
 - `tigaWrite(name, message, options?)`
 - `tigaRead(name, options?)`
 - `tigaInvoke(requestName, responseName, method, data, options?)`
+- `startTigaServer(options)`
+- `createTigaServer(options)`
 
 ## Install
 
@@ -19,39 +21,66 @@ Current package scope:
 
 - Windows only
 - File-backed mapping usage
-- `mappingDirectory` must be passed explicitly by the caller
+- `ipcDirectory` must be passed explicitly by the caller
 
 ## Usage
 
 ```js
-const { tigaInvoke, tigaWrite, tigaRead } = require('@tiga-ipc/mmap');
-
-const mappingDirectory = 'C:\\temp\\tiga-ipc';
-
-const reply = tigaInvoke(
-  'sample.req.client-a',
-  'sample.resp.client-a',
-  'echo',
-  'hello from node',
-  {
-    mappingDirectory,
-    timeoutMs: 3000,
-  },
-);
-
-console.log(reply);
-
-tigaWrite('sample.events', 'event payload', {
-  mappingDirectory,
-  mediaType: 'text/plain',
-});
+const {
+  startTigaServer,
+  tigaInvoke,
+  tigaWrite,
+  tigaRead,
+} = require('@tiga-ipc/mmap');
+
+async function main() {
+  const ipcDirectory = 'C:\\temp\\tiga-ipc';
+  const server = startTigaServer({
+    channelName: 'sample',
+    ipcDirectory,
+    onInvoke(method, data) {
+      if (method === 'echo') {
+        return `reply:${data}`;
+      }
+
+      throw new Error(`method not supported: ${method}`);
+    },
+  });
+
+  try {
+    const reply = tigaInvoke(
+      'sample.req.client-a',
+      'sample.resp.client-a',
+      'echo',
+      'hello from node',
+      {
+        ipcDirectory,
+        timeoutMs: 3000,
+      },
+    );
+
+    console.log(reply);
+
+    tigaWrite('sample.events', 'event payload', {
+      ipcDirectory,
+      mediaType: 'text/plain',
+    });
+
+    const result = tigaRead('sample.events', {
+      ipcDirectory,
+      lastId: 0,
+    });
+
+    console.log(result.lastId, result.entries.length);
+  } finally {
+    await server.close();
+  }
+}
 
-const result = tigaRead('sample.events', {
-  mappingDirectory,
-  lastId: 0,
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
 });
-
-console.log(result.lastId, result.entries.length);
 ```
 
 ## API
@@ -60,7 +89,7 @@ console.log(result.lastId, result.entries.length);
 
 - `name: string`
 - `message: Buffer | string`
-- `options?.mappingDirectory: string`
+- `options?.ipcDirectory: string`
 - `options?.mediaType?: string`
 
 Returns a short write result string from the native addon.
@@ -68,7 +97,7 @@ Returns a short write result string from the native addon.
 ### `tigaRead(name, options?)`
 
 - `name: string`
-- `options?.mappingDirectory: string`
+- `options?.ipcDirectory: string`
 - `options?.lastId?: number`
 
 Returns:
@@ -90,16 +119,55 @@ interface TigaReadResult {
 - `responseName: string`
 - `method: string`
 - `data: string`
-- `options?.mappingDirectory: string`
+- `options?.ipcDirectory: string`
 - `options?.timeoutMs?: number`
 
 Returns the response payload string.
 
+### `startTigaServer(options)` / `createTigaServer(options)`
+
+- `options.channelName: string`
+- `options.ipcDirectory: string`
+- `options.discoveryIntervalMs?: number`
+- `options.waitTimeoutMs?: number`
+- `options.onInvoke(method, data, context): unknown | Promise<unknown>`
+- `options.onError?(error, context): void`
+
+Returns a `TigaServer` instance. `startTigaServer(...)` starts it immediately. `createTigaServer(...)` returns the instance so the caller can decide when to call `server.start()`.
+
+`context` includes:
+
+```ts
+interface TigaServerContext {
+  channelName: string;
+  clientId: string;
+  requestName: string;
+  responseName: string;
+  ipcDirectory: string;
+  requestId: string;
+  entryId: number;
+  mediaType?: string | null;
+}
+```
+
+The server helper keeps transport concerns inside the package:
+
+- discovers per-client request channels under the configured `ipcDirectory`
+- registers request listeners using the native notification mechanism
+- decodes invoke payloads and writes response payloads back to the matching response channel
+- surfaces business logic as a single `onInvoke(...)` callback
+
+### `createTigaNotificationListener(name, options?)`
+
+Advanced low-level API for consumers that need direct access to the native notification wait handle. Most applications should use `startTigaServer(...)` instead.
+
 ## Notes
 
 - This package intentionally uses the current `tiga*` API only. The old generic `write/read` export surface is not part of the published package entry.
 - The native binary is packaged as `index.node`, so publish from a Windows environment after rebuilding the addon you want to ship.
 - For repository examples and cross-language smoke tests, see the monorepo root README and `examples/`.
+- `tigaInvoke(...)` is synchronous. In practice the server and client should live in different processes, which matches the real Tiga IPC usage model.
+- For per-client channels, the first invoke may wait up to the discovery interval until the server notices the newly created request channel and registers a listener.
 
 ## License
 

package/index.d.ts

@@ -14,17 +14,54 @@ export interface TigaEntry {
   mediaType?: string
 }
 export interface TigaChannelOptions {
-  mappingDirectory?: string
+  ipcDirectory?: string
 }
-export interface TigaWriteOptions extends TigaChannelOptions {
-  mediaType?: string | null
+export interface TigaWriteOptions {
+  mediaType?: string
+  ipcDirectory?: string
 }
-export interface TigaReadOptions extends TigaChannelOptions {
+export interface TigaReadOptions {
   lastId?: number
+  ipcDirectory?: string
 }
-export interface TigaInvokeOptions extends TigaChannelOptions {
+export interface TigaInvokeOptions {
   timeoutMs?: number
+  ipcDirectory?: string
+}
+export declare function tigaWrite(name: string, message: Buffer | string, options?: TigaWriteOptions | undefined | null): string
+export declare function tigaRead(name: string, options?: TigaReadOptions | undefined | null): TigaReadResult
+export declare function tigaInvoke(requestName: string, responseName: string, method: string, data: string, options?: TigaInvokeOptions | undefined | null): string
+export declare function createTigaNotificationListener(name: string, options?: TigaChannelOptions | undefined | null): TigaNotificationListener
+export declare class TigaNotificationListener {
+  wait(timeoutMs?: number): boolean
+  close(): void
+  get closed(): boolean
+}
+export interface TigaServerContext {
+  channelName: string
+  clientId: string
+  requestName: string
+  responseName: string
+  ipcDirectory: string
+  requestId: string
+  entryId: number
+  mediaType?: string | null
+}
+export interface TigaServerOptions extends TigaChannelOptions {
+  channelName: string
+  discoveryIntervalMs?: number
+  waitTimeoutMs?: number
+  onInvoke(method: string, data: unknown, context: TigaServerContext): unknown | Promise<unknown>
+  onError?(error: Error, context: Record<string, unknown>): void
+}
+export declare class TigaServer {
+  constructor(options: TigaServerOptions)
+  readonly channelName: string
+  readonly ipcDirectory: string
+  readonly closed: boolean
+  readonly started: boolean
+  start(): TigaServer
+  close(): Promise<void>
 }
-export declare function tigaWrite(name: string, message: Buffer | string, options?: TigaWriteOptions): string
-export declare function tigaRead(name: string, options?: TigaReadOptions): TigaReadResult
-export declare function tigaInvoke(requestName: string, responseName: string, method: string, data: string, options?: TigaInvokeOptions): string
+export declare function createTigaServer(options: TigaServerOptions): TigaServer
+export declare function startTigaServer(options: TigaServerOptions): TigaServer

package/index.js

@@ -1,8 +1 @@
-const binding = require('./index.node');
-
-module.exports = {
-  initialized: binding.initialized,
-  tigaWrite: binding.tigaWrite,
-  tigaRead: binding.tigaRead,
-  tigaInvoke: binding.tigaInvoke,
-};
+module.exports = require('./runtime');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiga-ipc/mmap",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Windows memory-mapped IPC bindings for Tiga channels.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -16,19 +16,22 @@
     "README.md",
     "index.js",
     "index.d.ts",
-    "index.node"
+    "index.node",
+    "runtime/"
   ],
   "os": [
     "win32"
   ],
   "scripts": {
     "test": "cargo test",
-    "cargo-build": "npx @napi-rs/cli build",
-    "cross-build": "npx @napi-rs/cli build",
+    "cargo-build": "node ./scripts/build-addon.js",
+    "cross-build": "node ./scripts/build-addon.js",
     "debug": "npm run cargo-build --",
     "build": "npm run cargo-build -- --release",
     "cross": "npm run cross-build -- --release",
-    "prepack": "node -e \"require('fs').accessSync('index.node')\""
+    "sync:types": "node ./scripts/sync-package-types.js",
+    "publish:check": "npm publish --dry-run --access public",
+    "prepack": "node -e \"require('fs').accessSync('index.node')\" && npm run sync:types"
   },
   "keywords": [
     "ipc",
@@ -51,6 +54,9 @@
     "url": "https://github.com/sugarbearr/TigaIpc/issues"
   },
   "homepage": "https://github.com/sugarbearr/TigaIpc",
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.2"
+  },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.0"
   }

package/runtime/index.js

@@ -0,0 +1,13 @@
+const binding = require('./native');
+const {
+  TigaServer,
+  createTigaServer,
+  startTigaServer,
+} = require('./server');
+
+module.exports = {
+  ...binding,
+  TigaServer,
+  createTigaServer,
+  startTigaServer,
+};

package/runtime/native.js

@@ -0,0 +1 @@
+module.exports = require('../index.node');

package/runtime/protocol.js

@@ -0,0 +1,73 @@
+const zlib = require('zlib');
+
+const { decode, encode } = require('@msgpack/msgpack');
+
+const TIGA_MEDIA_TYPE_MSGPACK = 'application/x-msgpack';
+const TIGA_MEDIA_TYPE_MSGPACK_COMPRESSED =
+  'application/x-msgpack-compressed';
+
+const parseTigaInvokeEntry = (entry) => {
+  try {
+    const raw =
+      entry && entry.mediaType === TIGA_MEDIA_TYPE_MSGPACK_COMPRESSED
+        ? zlib.gunzipSync(entry.message)
+        : entry && entry.message;
+    const decoded = decode(raw);
+    if (!Array.isArray(decoded) || decoded.length < 4) {
+      return null;
+    }
+
+    const [id, protocol, method, data] = decoded;
+    if (protocol !== 1 || typeof id !== 'string' || typeof method !== 'string') {
+      return null;
+    }
+
+    return { id, method, data };
+  } catch {
+    return null;
+  }
+};
+
+const buildTigaResponseBuffer = (id, data, code) =>
+  Buffer.from(encode([id, 2, data, code]));
+
+const stringifyTigaResponseData = (value) => {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (Buffer.isBuffer(value)) {
+    return value.toString('utf8');
+  }
+
+  if (value === undefined) {
+    return '';
+  }
+
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+};
+
+const getTigaErrorMessage = (error, fallback = 'invoke failed') => {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  if (typeof error === 'string' && error.trim()) {
+    return error;
+  }
+
+  return fallback;
+};
+
+module.exports = {
+  TIGA_MEDIA_TYPE_MSGPACK,
+  TIGA_MEDIA_TYPE_MSGPACK_COMPRESSED,
+  buildTigaResponseBuffer,
+  getTigaErrorMessage,
+  parseTigaInvokeEntry,
+  stringifyTigaResponseData,
+};

package/runtime/server.js

@@ -0,0 +1,436 @@
+const fs = require('fs');
+const path = require('path');
+const { Worker } = require('worker_threads');
+
+const binding = require('./native');
+const {
+  TIGA_MEDIA_TYPE_MSGPACK,
+  buildTigaResponseBuffer,
+  getTigaErrorMessage,
+  parseTigaInvokeEntry,
+  stringifyTigaResponseData,
+} = require('./protocol');
+
+const FILE_PREFIX = 'tiga_';
+const STATE_SUFFIX = '_state';
+const SINGLE_CLIENT_ID = '__single__';
+const DEFAULT_DISCOVERY_INTERVAL_MS = 1000;
+const DEFAULT_WAIT_TIMEOUT_MS = 1000;
+const WORKER_CLOSE_TIMEOUT_MS = 2000;
+
+const ensureString = (value, label) => {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} is required`);
+  }
+
+  return value.trim();
+};
+
+const getStatePath = (ipcDirectory, name) =>
+  path.join(ipcDirectory, `${FILE_PREFIX}${name}${STATE_SUFFIX}`);
+
+const hasSingleChannel = (channelName, ipcDirectory) =>
+  fs.existsSync(getStatePath(ipcDirectory, channelName));
+
+const listClientIds = (channelName, ipcDirectory) => {
+  try {
+    const prefix = `${FILE_PREFIX}${channelName}.req.`;
+    return fs
+      .readdirSync(ipcDirectory)
+      .filter((fileName) => fileName.startsWith(prefix))
+      .filter((fileName) => fileName.endsWith(STATE_SUFFIX))
+      .map((fileName) =>
+        fileName.slice(prefix.length, fileName.length - STATE_SUFFIX.length),
+      )
+      .filter((clientId) => clientId.length > 0);
+  } catch {
+    return [];
+  }
+};
+
+const toClientState = (clientId, channelName) =>
+  clientId === SINGLE_CLIENT_ID
+    ? {
+        key: SINGLE_CLIENT_ID,
+        clientId,
+        requestName: channelName,
+        responseName: channelName,
+      }
+    : {
+        key: clientId,
+        clientId,
+        requestName: `${channelName}.req.${clientId}`,
+        responseName: `${channelName}.resp.${clientId}`,
+      };
+
+class TigaServer {
+  constructor(options) {
+    const resolved = options || {};
+    this.channelName = ensureString(resolved.channelName, 'channelName');
+    this.ipcDirectory = ensureString(resolved.ipcDirectory, 'ipcDirectory');
+    if (typeof resolved.onInvoke !== 'function') {
+      throw new Error('onInvoke must be a function');
+    }
+
+    this.onInvoke = resolved.onInvoke;
+    this.onError =
+      typeof resolved.onError === 'function' ? resolved.onError : null;
+    this.discoveryIntervalMs = Math.max(
+      100,
+      Number(resolved.discoveryIntervalMs || DEFAULT_DISCOVERY_INTERVAL_MS),
+    );
+    this.waitTimeoutMs = Math.max(
+      100,
+      Number(resolved.waitTimeoutMs || DEFAULT_WAIT_TIMEOUT_MS),
+    );
+
+    this.clients = new Map();
+    this.discoveryTimer = null;
+    this.closed = false;
+    this.started = false;
+  }
+
+  start() {
+    if (this.started) {
+      return this;
+    }
+
+    fs.mkdirSync(this.ipcDirectory, { recursive: true });
+    this.started = true;
+    this.closed = false;
+    this.discoveryTimer = setInterval(() => {
+      this.discover().catch((error) => {
+        this.reportError(error, {
+          stage: 'discover',
+          channelName: this.channelName,
+          ipcDirectory: this.ipcDirectory,
+        });
+      });
+    }, this.discoveryIntervalMs);
+    this.discover().catch((error) => {
+      this.reportError(error, {
+        stage: 'discover',
+        channelName: this.channelName,
+        ipcDirectory: this.ipcDirectory,
+      });
+    });
+
+    return this;
+  }
+
+  async close() {
+    if (this.closed) {
+      return;
+    }
+
+    this.closed = true;
+    this.started = false;
+    if (this.discoveryTimer) {
+      clearInterval(this.discoveryTimer);
+      this.discoveryTimer = null;
+    }
+
+    const clients = Array.from(this.clients.values());
+    this.clients.clear();
+    await Promise.all(clients.map((client) => this.closeClient(client)));
+  }
+
+  async discover() {
+    if (this.closed) {
+      return;
+    }
+
+    const nextClients = listClientIds(this.channelName, this.ipcDirectory);
+    nextClients.forEach((clientId) => {
+      if (!this.clients.has(clientId)) {
+        this.registerClient(toClientState(clientId, this.channelName));
+      }
+    });
+
+    if (
+      !this.clients.has(SINGLE_CLIENT_ID) &&
+      hasSingleChannel(this.channelName, this.ipcDirectory)
+    ) {
+      this.registerClient(toClientState(SINGLE_CLIENT_ID, this.channelName));
+    }
+  }
+
+  registerClient(client) {
+    const state = {
+      ...client,
+      lastId: 0,
+      draining: false,
+      pendingDrain: false,
+      closing: false,
+      worker: null,
+      workerExit: null,
+      restartTimer: null,
+    };
+
+    this.clients.set(state.key, state);
+    this.startWorker(state);
+  }
+
+  startWorker(client) {
+    if (this.closed || client.closing) {
+      return;
+    }
+
+    const worker = new Worker(
+      path.join(__dirname, 'workers', 'notification-listener.js'),
+      {
+        workerData: {
+          name: client.requestName,
+          ipcDirectory: this.ipcDirectory,
+          waitTimeoutMs: this.waitTimeoutMs,
+        },
+      },
+    );
+
+    client.worker = worker;
+    client.workerExit = new Promise((resolve) => {
+      worker.once('exit', () => resolve());
+    });
+
+    worker.on('message', (message) => {
+      if (!message || client.closing || this.closed) {
+        return;
+      }
+
+      if (message.type === 'ready' || message.type === 'signal') {
+        this.scheduleDrain(client);
+        return;
+      }
+
+      if (message.type === 'error') {
+        this.reportError(new Error(message.message), {
+          stage: 'listener',
+          clientId: client.clientId,
+          requestName: client.requestName,
+          responseName: client.responseName,
+          channelName: this.channelName,
+          ipcDirectory: this.ipcDirectory,
+        });
+      }
+    });
+
+    worker.on('error', (error) => {
+      this.reportError(error, {
+        stage: 'listener',
+        clientId: client.clientId,
+        requestName: client.requestName,
+        responseName: client.responseName,
+        channelName: this.channelName,
+        ipcDirectory: this.ipcDirectory,
+      });
+    });
+
+    worker.on('exit', () => {
+      client.worker = null;
+      client.workerExit = null;
+      if (!this.closed && !client.closing) {
+        this.scheduleWorkerRestart(client);
+      }
+    });
+  }
+
+  scheduleWorkerRestart(client) {
+    if (client.restartTimer || this.closed || client.closing) {
+      return;
+    }
+
+    client.restartTimer = setTimeout(() => {
+      client.restartTimer = null;
+      if (!this.closed && !client.closing && this.clients.has(client.key)) {
+        this.startWorker(client);
+      }
+    }, 200);
+  }
+
+  scheduleDrain(client) {
+    if (this.closed || client.closing) {
+      return;
+    }
+
+    client.pendingDrain = true;
+    if (client.draining) {
+      return;
+    }
+
+    client.draining = true;
+    void this.runDrainLoop(client);
+  }
+
+  async runDrainLoop(client) {
+    try {
+      while (client.pendingDrain && !client.closing && !this.closed) {
+        client.pendingDrain = false;
+        await this.drainClient(client);
+      }
+    } finally {
+      client.draining = false;
+      if (client.pendingDrain && !client.closing && !this.closed) {
+        this.scheduleDrain(client);
+      }
+    }
+  }
+
+  async drainClient(client) {
+    let result;
+    try {
+      result = binding.tigaRead(client.requestName, {
+        lastId: client.lastId,
+        ipcDirectory: this.ipcDirectory,
+      });
+    } catch (error) {
+      this.reportError(error, {
+        stage: 'read',
+        clientId: client.clientId,
+        requestName: client.requestName,
+        responseName: client.responseName,
+        channelName: this.channelName,
+        ipcDirectory: this.ipcDirectory,
+      });
+      return;
+    }
+
+    if (
+      result &&
+      typeof result.lastId === 'number' &&
+      result.lastId < client.lastId
+    ) {
+      client.lastId = result.lastId;
+    }
+
+    const entries = Array.isArray(result && result.entries)
+      ? result.entries.filter((entry) => entry && entry.id > client.lastId)
+      : [];
+
+    for (const entry of entries) {
+      await this.processEntry(client, entry);
+      client.lastId = Math.max(client.lastId, entry.id);
+    }
+  }
+
+  async processEntry(client, entry) {
+    const invoke = parseTigaInvokeEntry(entry);
+    if (!invoke) {
+      return;
+    }
+
+    const context = {
+      channelName: this.channelName,
+      clientId: client.clientId,
+      requestName: client.requestName,
+      responseName: client.responseName,
+      ipcDirectory: this.ipcDirectory,
+      requestId: invoke.id,
+      entryId: entry.id,
+      mediaType: entry.mediaType || null,
+    };
+
+    try {
+      const result = await Promise.resolve(
+        this.onInvoke(invoke.method, invoke.data, context),
+      );
+      this.writeResponse(
+        client,
+        buildTigaResponseBuffer(
+          invoke.id,
+          stringifyTigaResponseData(result),
+          0,
+        ),
+      );
+    } catch (error) {
+      const message = getTigaErrorMessage(error);
+      this.reportError(error, {
+        ...context,
+        stage: 'invoke',
+        method: invoke.method,
+      });
+      this.writeResponse(
+        client,
+        buildTigaResponseBuffer(invoke.id, message, -1),
+      );
+    }
+  }
+
+  writeResponse(client, payload) {
+    try {
+      binding.tigaWrite(client.responseName, payload, {
+        mediaType: TIGA_MEDIA_TYPE_MSGPACK,
+        ipcDirectory: this.ipcDirectory,
+      });
+    } catch (error) {
+      this.reportError(error, {
+        stage: 'write',
+        clientId: client.clientId,
+        requestName: client.requestName,
+        responseName: client.responseName,
+        channelName: this.channelName,
+        ipcDirectory: this.ipcDirectory,
+      });
+    }
+  }
+
+  async closeClient(client) {
+    client.closing = true;
+    client.pendingDrain = false;
+    if (client.restartTimer) {
+      clearTimeout(client.restartTimer);
+      client.restartTimer = null;
+    }
+
+    const worker = client.worker;
+    const workerExit = client.workerExit;
+    client.worker = null;
+    client.workerExit = null;
+    if (!worker) {
+      return;
+    }
+
+    try {
+      worker.postMessage({ type: 'close' });
+    } catch {
+      // Ignore worker shutdown races.
+    }
+
+    if (workerExit) {
+      const terminated = workerExit.then(() => true);
+      const timeout = new Promise((resolve) => {
+        setTimeout(() => resolve(false), WORKER_CLOSE_TIMEOUT_MS);
+      });
+
+      const exited = await Promise.race([terminated, timeout]);
+      if (exited) {
+        return;
+      }
+    }
+
+    await worker.terminate();
+  }
+
+  reportError(error, context) {
+    if (!this.onError) {
+      return;
+    }
+
+    try {
+      const normalizedError =
+        error instanceof Error ? error : new Error(String(error));
+      this.onError(normalizedError, context);
+    } catch {
+      // Ignore user callback errors to keep the server alive.
+    }
+  }
+}
+
+const createTigaServer = (options) => new TigaServer(options);
+
+const startTigaServer = (options) => createTigaServer(options).start();
+
+module.exports = {
+  TigaServer,
+  createTigaServer,
+  startTigaServer,
+};

package/runtime/workers/notification-listener.js

@@ -0,0 +1,72 @@
+const { parentPort, workerData } = require('worker_threads');
+
+const { createTigaNotificationListener } = require('../native');
+
+const post = (message) => {
+  if (parentPort) {
+    parentPort.postMessage(message);
+  }
+};
+
+const getErrorMessage = (error) => {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return String(error);
+};
+
+let closed = false;
+let listener;
+
+if (!parentPort) {
+  throw new Error('tiga notification worker requires parentPort');
+}
+
+parentPort.on('message', (message) => {
+  if (!message || message.type !== 'close') {
+    return;
+  }
+
+  closed = true;
+  if (listener) {
+    try {
+      listener.close();
+    } catch {
+      // Ignore close races during shutdown.
+    }
+  }
+});
+
+try {
+  listener = createTigaNotificationListener(workerData.name, {
+    ipcDirectory: workerData.ipcDirectory,
+  });
+  post({ type: 'ready' });
+
+  while (!closed && !listener.closed) {
+    const signaled = listener.wait(workerData.waitTimeoutMs);
+    if (closed || listener.closed) {
+      break;
+    }
+
+    if (signaled) {
+      post({ type: 'signal' });
+    }
+  }
+} catch (error) {
+  post({
+    type: 'error',
+    message: getErrorMessage(error),
+  });
+} finally {
+  if (listener && !listener.closed) {
+    try {
+      listener.close();
+    } catch {
+      // Ignore close races during shutdown.
+    }
+  }
+
+  post({ type: 'closed' });
+}