{"id":21037592,"url":"https://github.com/faranalytics/port_agent","last_synced_at":"2026-02-18T16:31:34.644Z","repository":{"id":181638544,"uuid":"667094660","full_name":"faranalytics/port_agent","owner":"faranalytics","description":"A RPC-like facility for making inter-thread function calls.","archived":false,"fork":false,"pushed_at":"2025-01-18T23:02:53.000Z","size":243,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T10:11:18.344Z","etag":null,"topics":["ipc","multithreading","nodejs","rpc","worker-threads"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/port_agent","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faranalytics.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-16T16:10:24.000Z","updated_at":"2025-01-18T23:02:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"bac7a8ed-b261-4a1e-9e1e-be43918d6090","html_url":"https://github.com/faranalytics/port_agent","commit_stats":null,"previous_names":["faranalytics/port_agent"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faranalytics%2Fport_agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faranalytics%2Fport_agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faranalytics%2Fport_agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faranalytics%2Fport_agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faranalytics","download_url":"https://codeload.github.com/faranalytics/port_agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251321453,"owners_count":21570742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ipc","multithreading","nodejs","rpc","worker-threads"],"created_at":"2024-11-19T13:27:01.781Z","updated_at":"2025-04-28T13:43:27.617Z","avatar_url":"https://github.com/faranalytics.png","language":"TypeScript","readme":"# Port Agent\n\nA RPC-like facility for making inter-thread function calls.\n\n## Introduction\n\nPort Agent provides a simple and intuitive interface that makes inter-thread function calls _easy_. Please see the [Usage](#usage) or [Examples](#examples) for instructions on how to use Port Agent in your application.\n\n### Features\n\n- Bi-directional inter-thread function calls.\n- Port Agent will marshal the return value or `Error` from the _other_ thread back to the caller.\n- The _other_ thread may be the main thread or a worker thread.\n- Registered functions (i.e., `agent.register`) persist until deregistered (i.e., `agent.deregister`) .\n- Late binding registrants will be called with previously awaited invocations.\n\n## Table of contents\n\n- [Installation](#installation)\n- [Concepts](#concepts)\n- [Usage](#usage)\n- [Examples](#examples)\n- [API](#api)\n- [Versioning](#versioning)\n- [Notes](#notes)\n- [Support](#support)\n\n## Installation\n\n```bash\nnpm install port_agent --save\n```\n\n## Concepts\n\n### Agent\n\nAn instance of an `Agent` facilitates bi-directional communication between threads. The `Agent` can be used in order to register a function in one thread and call it from another thread. Calls may be made from the main thread to a worker thread, and conversely from a worker thread to the main thread.\n\nLate binding registrants will be called with previously awaited invocations; thus preventing a race condition. This means that you may await a call to a function that has not yet been registered. Once the function is registered in the _other_ thread it will be called and its return value or `Error` will be marshalled back to the caller.\n\nPlease see the [Examples](#examples) for variations on the `Agent`'s usage.\n\n## Usage\n\n### How to create an Agent instance\n\n#### Import the Agent class and relevant dependencies.\n\n```ts\nimport { Worker, parentPort } from 'node:worker_threads';\nimport { fileURLToPath } from 'node:url';\nimport { Agent } from \"port_agent\";\n```\n\n#### You can create a new Agent by passing a MessagePort or Worker instance to the Agent constructor.\n\nIn the main thread,\n\n```ts\nconst worker = new Worker(fileURLToPath(import.meta.url));\nconst agent = new Agent(worker);\n```\n\nor, in a worker thread,\n\n```ts\nconst agent = new Agent(parentPort);\n```\n\n### How to use an Agent instance\n\n#### You can register a function in the main thread or in a worker thread using the `agent.register` method.\n\n```ts\nagent.register(\n  \"hello_world\",\n  (value: string): string =\u003e `Hello, ${value} world!`\n);\n```\n\n#### You can call a function registered in another thread (i.e., the main thread or a worker thread) using the `agent.call` method:\n\n```ts\nconst greeting = await agent.call\u003cstring\u003e(\"hello_world\", \"happy\");\nconsole.log(greeting); // Hello, happy world!\n```\n\n## Examples\n\n### _A simple example_ \u003csup\u003e\u003csup\u003e\\\u003c/Node.js\\\u003e\u003c/sup\u003e\u003c/sup\u003e\n\nPlease see the [simple example](https://github.com/faranalytics/port_agent/tree/main/examples/simple) for a working implementation.\n\n### _A comprehensive example_ \u003csup\u003e\u003csup\u003e\\\u003c/TypeScript\\\u003e\u003c/sup\u003e\u003c/sup\u003e\n\nPlease see the [comprehensive example](https://github.com/faranalytics/port_agent/tree/main/examples/comprehensive) for a working implementation.\n\n## API\n\n### The Agent class\n\n#### new port_agent.Agent(port)\n\n- port `\u003cthreads.MessagePort\u003e` or `\u003cthreads.Worker\u003e` The message port.\n\n_public_ **agent.call\\\u003cT\\\u003e(name, ...args)**\n\n- name `\u003cstring\u003e` The name of the registered function.\n- ...args `\u003cArray\u003cunknown\u003e\u003e` Arguments to be passed to the registered function.\n\nReturns: `\u003cPromise\u003cT\u003e\u003e`\n\nErrors:\n\n- If the registered function in the _other_ thread throws an `Error`, the `Error` will be marshalled back from the _other_ thread to _this_ thread and the `Promise` will reject with the `Error` as its failure reason.\n- If a worker thread throws an unhandled exception while a call is awaited, the `Error` will be marshalled back from the _other_ thread to _this_ thread and the `Promise` will reject with the unhandled exception as its failure reason.\n- If a worker exits while a call is awaited, the `Error` will be marshalled back from the _other_ thread to _this_ thread and the `Promise` will reject with the exit code as its failure reason.\n\n_public_ **agent.register(name, fn)**\n\n- name `\u003cstring\u003e` The name of the registered function.\n- fn `\u003c(...args: Array\u003cany\u003e) =\u003e any\u003e` The registered function.\n\nReturns: `\u003cvoid\u003e`\n\n_public_ **agent.deregister(name)**\n\n- name `\u003cstring\u003e` The name of the registered function.\n\nReturns: `\u003cvoid\u003e`\n\n## Versioning\n\nThe Port Agent package adheres to semantic versioning. Breaking changes to the public API will result in a turn of the major. Minor and patch changes will always be backward compatible.\n\nExcerpted from [Semantic Versioning 2.0.0](https://semver.org/):\n\n\u003e Given a version number MAJOR.MINOR.PATCH, increment the:\n\u003e\n\u003e 1. MAJOR version when you make incompatible API changes\n\u003e 2. MINOR version when you add functionality in a backward compatible manner\n\u003e 3. PATCH version when you make backward compatible bug fixes\n\u003e\n\u003e Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.\n\n## Notes\n\n### Support for broadcastChannels\n\nPort Agent supports one to one communication over a `MessagePort`. `BroadcastChannel`s are not presently supported.\n\n### Support for other communication channels\n\nPort Agent is strictly focused on efficient communication over `MessagePort`s. Port Agent will not support communication over other communication channels e.g., `Socket`s, IPC, etc.\n\n## Support\n\nIf you have a feature request or run into any issues, feel free to submit an [issue](https://github.com/faranalytics/port_agent/issues) or start a [discussion](https://github.com/faranalytics/port_agent/discussions). You’re also welcome to reach out directly to one of the authors.\n\n- [Adam Patterson](https://github.com/adamjpatterson)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaranalytics%2Fport_agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaranalytics%2Fport_agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaranalytics%2Fport_agent/lists"}