@platformatic/itc 3.4.1 → 3.5.0

package/eslint.config.js

@@ -1,3 +1,3 @@
-'use strict'
+import neostandard from 'neostandard'
 
-module.exports = require('neostandard')({ ts: true })
+export default neostandard({ ts: true })

package/lib/errors.js

@@ -1,24 +1,32 @@
-'use strict'
+import createError from '@fastify/error'
 
-const createError = require('@fastify/error')
+export const ERROR_PREFIX = 'PLT_ITC'
 
-const ERROR_PREFIX = 'PLT_ITC'
-
-module.exports = {
-  HandlerFailed: createError(`${ERROR_PREFIX}_HANDLER_FAILED`, 'Handler failed with error: %s'),
-  HandlerNotFound: createError(`${ERROR_PREFIX}_HANDLER_NOT_FOUND`, 'Handler not found for request: "%s"'),
-  PortAlreadyListening: createError(`${ERROR_PREFIX}_ALREADY_LISTENING`, 'ITC is already listening'),
-  SendBeforeListen: createError(`${ERROR_PREFIX}_SEND_BEFORE_LISTEN`, 'ITC cannot send requests before listening'),
-  InvalidRequestVersion: createError(`${ERROR_PREFIX}_INVALID_REQUEST_VERSION`, 'Invalid ITC request version: "%s"'),
-  InvalidResponseVersion: createError(`${ERROR_PREFIX}_INVALID_RESPONSE_VERSION`, 'Invalid ITC response version: "%s"'),
-  MissingRequestName: createError(`${ERROR_PREFIX}_MISSING_REQUEST_NAME`, 'ITC request name is missing'),
-  MissingResponseName: createError(`${ERROR_PREFIX}_MISSING_RESPONSE_NAME`, 'ITC response name is missing'),
-  MissingRequestReqId: createError(`${ERROR_PREFIX}_MISSING_REQUEST_REQ_ID`, 'ITC request reqId is missing'),
-  MissingResponseReqId: createError(`${ERROR_PREFIX}_MISSING_RESPONSE_REQ_ID`, 'ITC response reqId is missing'),
-  RequestNameIsNotString: createError(
-    `${ERROR_PREFIX}_REQUEST_NAME_IS_NOT_STRING`,
-    'ITC request name is not a string: "%s"'
-  ),
-  MessagePortClosed: createError(`${ERROR_PREFIX}_MESSAGE_PORT_CLOSED`, 'ITC MessagePort is closed'),
-  MissingName: createError(`${ERROR_PREFIX}_MISSING_NAME`, 'ITC name is missing')
-}
+export const HandlerFailed = createError(`${ERROR_PREFIX}_HANDLER_FAILED`, 'Handler failed with error: %s')
+export const HandlerNotFound = createError(`${ERROR_PREFIX}_HANDLER_NOT_FOUND`, 'Handler not found for request: "%s"')
+export const PortAlreadyListening = createError(`${ERROR_PREFIX}_ALREADY_LISTENING`, 'ITC is already listening')
+export const SendBeforeListen = createError(
+  `${ERROR_PREFIX}_SEND_BEFORE_LISTEN`,
+  'ITC cannot send requests before listening'
+)
+export const InvalidRequestVersion = createError(
+  `${ERROR_PREFIX}_INVALID_REQUEST_VERSION`,
+  'Invalid ITC request version: "%s"'
+)
+export const InvalidResponseVersion = createError(
+  `${ERROR_PREFIX}_INVALID_RESPONSE_VERSION`,
+  'Invalid ITC response version: "%s"'
+)
+export const MissingRequestName = createError(`${ERROR_PREFIX}_MISSING_REQUEST_NAME`, 'ITC request name is missing')
+export const MissingResponseName = createError(`${ERROR_PREFIX}_MISSING_RESPONSE_NAME`, 'ITC response name is missing')
+export const MissingRequestReqId = createError(`${ERROR_PREFIX}_MISSING_REQUEST_REQ_ID`, 'ITC request reqId is missing')
+export const MissingResponseReqId = createError(
+  `${ERROR_PREFIX}_MISSING_RESPONSE_REQ_ID`,
+  'ITC response reqId is missing'
+)
+export const RequestNameIsNotString = createError(
+  `${ERROR_PREFIX}_REQUEST_NAME_IS_NOT_STRING`,
+  'ITC request name is not a string: "%s"'
+)
+export const MessagePortClosed = createError(`${ERROR_PREFIX}_MESSAGE_PORT_CLOSED`, 'ITC MessagePort is closed')
+export const MissingName = createError(`${ERROR_PREFIX}_MISSING_NAME`, 'ITC name is missing')

package/lib/index.d.ts

@@ -0,0 +1,23 @@
+import { EventEmitter } from 'node:events'
+import { MessagePort } from 'node:worker_threads'
+
+export type Handler = ((data: any) => any) | ((data: any) => Promise<any>)
+
+export interface ITCConstructorOptions {
+  port: MessagePort
+}
+
+export class ITC extends EventEmitter {
+  constructor (options: ITCConstructorOptions)
+
+  send (name: string, message: any, options?: Record<string, any>): Promise<any>
+  notify (name: string, message: any, options?: Record<string, any>): void
+  handle (message: string, handler: Handler): void
+  getHandler (message: string): Handler | undefined
+  listen (): void
+  close (): void
+}
+
+declare module '@platformatic/itc' {
+  export { ITC }
+}

package/lib/{itc.js → index.js}

@@ -1,9 +1,21 @@
-'use strict'
-
-const { randomUUID } = require('node:crypto')
-const { EventEmitter, once } = require('node:events')
-const { Unpromise } = require('@watchable/unpromise')
-const errors = require('./errors.js')
+import { Unpromise } from '@watchable/unpromise'
+import { randomUUID } from 'node:crypto'
+import { EventEmitter, once } from 'node:events'
+import {
+  HandlerFailed,
+  HandlerNotFound,
+  InvalidRequestVersion,
+  InvalidResponseVersion,
+  MessagePortClosed,
+  MissingName,
+  MissingRequestName,
+  MissingRequestReqId,
+  MissingResponseName,
+  MissingResponseReqId,
+  PortAlreadyListening,
+  RequestNameIsNotString,
+  SendBeforeListen
+} from './errors.js'
 
 const PLT_ITC_REQUEST_TYPE = 'PLT_ITC_REQUEST'
 const PLT_ITC_RESPONSE_TYPE = 'PLT_ITC_RESPONSE'
@@ -11,35 +23,35 @@ const PLT_ITC_NOTIFICATION_TYPE = 'PLT_ITC_NOTIFICATION'
 const PLT_ITC_UNHANDLED_ERROR_TYPE = 'PLT_ITC_UNHANDLED_ERROR'
 const PLT_ITC_VERSION = '1.0.0'
 
-function parseRequest (request) {
+export function parseRequest (request) {
   if (request.reqId === undefined) {
-    throw new errors.MissingRequestReqId()
+    throw new MissingRequestReqId()
   }
   if (request.version !== PLT_ITC_VERSION) {
-    throw new errors.InvalidRequestVersion(request.version)
+    throw new InvalidRequestVersion(request.version)
   }
   if (request.name === undefined) {
-    throw new errors.MissingRequestName()
+    throw new MissingRequestName()
   }
   return request
 }
 
-function parseResponse (response) {
+export function parseResponse (response) {
   if (response.reqId === undefined) {
-    throw new errors.MissingResponseReqId()
+    throw new MissingResponseReqId()
   }
   if (response.version !== PLT_ITC_VERSION) {
-    throw new errors.InvalidResponseVersion(response.version)
+    throw new InvalidResponseVersion(response.version)
   }
   if (response.name === undefined) {
-    throw new errors.MissingResponseName()
+    throw new MissingResponseName()
   }
   return response
 }
 
-function generateRequest (name, data) {
+export function generateRequest (name, data) {
   if (typeof name !== 'string') {
-    throw new errors.RequestNameIsNotString(name.toString())
+    throw new RequestNameIsNotString(name.toString())
   }
 
   return {
@@ -47,31 +59,31 @@ function generateRequest (name, data) {
     version: PLT_ITC_VERSION,
     reqId: randomUUID(),
     name,
-    data: sanitize(data)
+    data
   }
 }
 
-function generateResponse (request, error, data) {
+export function generateResponse (request, error, data) {
   return {
     type: PLT_ITC_RESPONSE_TYPE,
     version: PLT_ITC_VERSION,
     reqId: request.reqId,
     name: request.name,
     error,
-    data: sanitize(data)
+    data
   }
 }
 
-function generateNotification (name, data) {
+export function generateNotification (name, data) {
   return {
     type: PLT_ITC_NOTIFICATION_TYPE,
     version: PLT_ITC_VERSION,
     name,
-    data: sanitize(data)
+    data
   }
 }
 
-function generateUnhandledErrorResponse (error) {
+export function generateUnhandledErrorResponse (error) {
   return {
     type: PLT_ITC_UNHANDLED_ERROR_TYPE,
     version: PLT_ITC_VERSION,
@@ -80,17 +92,16 @@ function generateUnhandledErrorResponse (error) {
   }
 }
 
-function sanitize (data) {
-  if (!data || typeof data !== 'object') {
+export function sanitize (data, transferList) {
+  if (!data || typeof data !== 'object' || transferList?.includes(data) || data instanceof Error) {
     return data
   }
 
   let sanitized
 
-  if (Buffer.isBuffer(data)) {
-    return {
-      data: Array.from(data.values())
-    }
+  if (Buffer.isBuffer(data) || data instanceof Uint8Array) {
+    // This will convert as Uint8Array
+    return data
   } else if (Array.isArray(data)) {
     sanitized = []
 
@@ -102,7 +113,7 @@ function sanitize (data) {
         continue
       }
 
-      sanitized.push(value && typeof value === 'object' ? sanitize(value) : value)
+      sanitized.push(value && typeof value === 'object' ? sanitize(value, transferList) : value)
     }
   } else {
     sanitized = {}
@@ -114,14 +125,14 @@ function sanitize (data) {
         continue
       }
 
-      sanitized[key] = value && typeof value === 'object' ? sanitize(value) : value
+      sanitized[key] = value && typeof value === 'object' ? sanitize(value, transferList) : value
     }
   }
 
   return sanitized
 }
 
-class ITC extends EventEmitter {
+export class ITC extends EventEmitter {
   #requestEmitter
   #handlers
   #listening
@@ -136,7 +147,7 @@ class ITC extends EventEmitter {
     super()
 
     if (!name) {
-      throw new errors.MissingName()
+      throw new MissingName()
     }
 
     // The name property is useful only for debugging purposes.
@@ -177,17 +188,20 @@ class ITC extends EventEmitter {
     }
   }
 
-  async send (name, message) {
+  getHandler (message) {
+    return this.#handlers.get(message)
+  }
+
+  async send (name, message, options) {
     if (!this.#listening) {
-      throw new errors.SendBeforeListen()
+      throw new SendBeforeListen()
     }
 
     try {
       this._enableKeepAlive()
 
       const request = generateRequest(name, message)
-
-      this._send(request)
+      this._send(request, options)
 
       const responsePromise = once(this.#requestEmitter, request.reqId).then(([response]) => response)
 
@@ -200,8 +214,8 @@ class ITC extends EventEmitter {
     }
   }
 
-  async notify (name, message) {
-    this._send(generateNotification(name, message))
+  notify (name, message, options) {
+    this._send(generateNotification(name, message), options)
   }
 
   handle (message, handler) {
@@ -210,18 +224,20 @@ class ITC extends EventEmitter {
 
   listen () {
     if (this.#listening) {
-      throw new errors.PortAlreadyListening()
+      throw new PortAlreadyListening()
     }
     this.#listening = true
 
-    this._setupListener(message => {
+    this._setupListener((message, context) => {
+      context ??= {}
+
       const messageType = message.type
       if (messageType === PLT_ITC_REQUEST_TYPE) {
-        this.#handleRequest(message)
+        this.#handleRequest(message, context)
         return
       }
       if (messageType === PLT_ITC_RESPONSE_TYPE) {
-        this.#handleResponse(message)
+        this.#handleResponse(message, context)
         return
       }
       if (messageType === PLT_ITC_NOTIFICATION_TYPE) {
@@ -234,7 +250,7 @@ class ITC extends EventEmitter {
 
     this.#closePromise = this._createClosePromise().then(() => {
       this.#listening = false
-      const error = new errors.MessagePortClosed()
+      const error = new MessagePortClosed()
       clearInterval(this.#keepAlive)
       this.#keepAliveCount = -1000
       return { error, data: null }
@@ -254,8 +270,9 @@ class ITC extends EventEmitter {
     this.port.on('message', listener)
   }
 
-  _send (request) {
-    this.port.postMessage(request)
+  _send (request, options) {
+    const transferList = options?.transferList || []
+    this.port.postMessage(sanitize(request, transferList), transferList)
   }
 
   _createClosePromise () {
@@ -267,7 +284,7 @@ class ITC extends EventEmitter {
     this.port?.close?.()
   }
 
-  async #handleRequest (raw) {
+  async #handleRequest (raw, context) {
     let request = null
     let handler = null
     let response = null
@@ -279,11 +296,11 @@ class ITC extends EventEmitter {
       handler = this.#handlers.get(request.name)
 
       if (handler) {
-        const result = await handler(request.data)
+        const result = await handler(request.data, context)
         response = generateResponse(request, null, result)
       } else {
         if (this.#throwOnMissingHandler) {
-          throw new errors.HandlerNotFound(request.name)
+          throw new HandlerNotFound(request.name)
         }
 
         response = generateResponse(request, null)
@@ -294,7 +311,7 @@ class ITC extends EventEmitter {
       } else if (!handler) {
         response = generateResponse(request, error, null)
       } else {
-        const failedError = new errors.HandlerFailed(error.message)
+        const failedError = new HandlerFailed(error.message)
         failedError.handlerError = error
         // This is needed as the code might be lost when sending the message over the port
         failedError.handlerErrorCode = error.code
@@ -305,24 +322,27 @@ class ITC extends EventEmitter {
       this.#handling = false
     }
 
-    this._send(response)
+    this._send(response, context)
 
     if (this.#closeAfterCurrentRequest) {
       this.close()
     }
   }
 
-  #handleResponse (response) {
+  #handleResponse (response, context) {
     try {
       response = parseResponse(response)
     } catch (error) {
       response = generateUnhandledErrorResponse(error)
-      this._send(response)
+      this._send(response, context)
       return
     }
 
-    const reqId = response.reqId
-    this.#requestEmitter.emit(reqId, response)
+    this._emitResponse(response)
+  }
+
+  _emitResponse (response) {
+    this.#requestEmitter.emit(response.reqId, response)
   }
 
   _enableKeepAlive () {
@@ -343,13 +363,4 @@ class ITC extends EventEmitter {
   }
 }
 
-module.exports = {
-  ITC,
-  parseRequest,
-  parseResponse,
-  generateRequest,
-  generateResponse,
-  generateNotification,
-  generateUnhandledErrorResponse,
-  sanitize
-}
+export * as errors from './errors.js'

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@platformatic/itc",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "",
-  "main": "index.js",
-  "author": "Matteo Collina <hello@matteocollina.com>",
+  "main": "lib/index.js",
+  "type": "module",
+  "types": "lib/index.d.ts",
+  "author": "Platformatic Inc. <oss@platformatic.dev> (https://platformatic.dev)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/platformatic/platformatic.git"
@@ -15,18 +17,22 @@
   "homepage": "https://github.com/platformatic/platformatic#readme",
   "devDependencies": {
     "@types/node": "^22.5.0",
-    "borp": "^0.17.0",
+    "cleaner-spec-reporter": "^0.5.0",
     "eslint": "9",
-    "neostandard": "^0.11.1",
-    "tsd": "^0.31.0",
+    "neostandard": "^0.12.0",
+    "tsd": "^0.33.0",
     "typescript": "^5.5.4"
   },
   "dependencies": {
     "@fastify/error": "^4.0.0",
     "@watchable/unpromise": "^1.0.2"
   },
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "scripts": {
-    "test": "npm run lint && borp --timeout=180000 --concurrency=1 --coverage && tsd",
+    "test": "node --test --test-reporter=cleaner-spec-reporter --test-concurrency=1 --test-timeout=2000000 test/*.test.js",
+    "posttest": "tsd -t index.test-d.ts test",
     "lint": "eslint"
   }
 }

package/index.d.ts

@@ -1,20 +0,0 @@
-import { EventEmitter } from 'node:events'
-import { MessagePort } from 'node:worker_threads'
-
-export interface ITCConstructorOptions {
-  port: MessagePort;
-}
-
-export class ITC extends EventEmitter {
-  constructor (options: ITCConstructorOptions)
-
-  send (name: string, message: any): Promise<any>
-  notify (name: string, message: any): void
-  handle (message: string, handler: (data: any) => Promise<any>): void
-  listen (): void
-  close (): void
-}
-
-declare module '@platformatic/itc' {
-  export { ITC }
-}

package/index.js

@@ -1,3 +0,0 @@
-'use strict'
-
-module.exports = require('./lib/itc')

package/index.test-d.ts

@@ -1,38 +0,0 @@
-import { MessagePort } from 'node:worker_threads'
-import { expectError, expectType } from 'tsd'
-import { ITC, ITCConstructorOptions } from './index'
-
-const mockPort = {} as MessagePort
-
-const options: ITCConstructorOptions = { port: mockPort }
-expectType<ITCConstructorOptions>(options)
-
-const itc = new ITC({ port: mockPort })
-expectType<ITC>(itc)
-
-expectType<Promise<any>>(itc.send('testMessage', { key: 'value' }))
-expectType<void>(itc.notify('testMessage', { key: 'value' }))
-expectType<void>(
-  itc.handle('testMessage', async (data) => {
-    return { key: 'value' }
-  })
-)
-expectType<void>(itc.listen())
-expectType<void>(itc.close())
-
-expectError(itc.send(123, { key: 'value' })) // send name must be a string
-expectError(itc.notify(123, { key: 'value' })) // send name must be a string
-expectError(
-  itc.handle(123, async (data) => {
-    return { key: 'value' }
-  })
-) // handle message must be a string
-expectError(
-  itc.handle('testMessage', (data) => {
-    return 'string'
-  })
-) // handler must return a Promise
-
-itc.on('unhandledError', (error: Error) => {
-  expectType<Error>(error)
-})