{"id":21151105,"url":"https://github.com/johnsonjo4531/worker-channel","last_synced_at":"2025-03-14T14:24:54.276Z","repository":{"id":71977463,"uuid":"604749936","full_name":"johnsonjo4531/worker-channel","owner":"johnsonjo4531","description":"A WebWorker Communication library","archived":false,"fork":false,"pushed_at":"2023-02-27T15:16:57.000Z","size":587,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-06T04:52:22.580Z","etag":null,"topics":["async","async-iterable","channels","communication","orchestrator","rpc","webworker","worker"],"latest_commit_sha":null,"homepage":"https://johnsonjo4531.github.io/worker-channel/","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/johnsonjo4531.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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-02-21T17:57:53.000Z","updated_at":"2024-03-31T20:56:06.000Z","dependencies_parsed_at":"2023-05-04T22:31:15.153Z","dependency_job_id":null,"html_url":"https://github.com/johnsonjo4531/worker-channel","commit_stats":{"total_commits":13,"total_committers":1,"mean_commits":13.0,"dds":0.0,"last_synced_commit":"bf7600535da69b9d26b64048f6c43fab207a3605"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjo4531%2Fworker-channel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjo4531%2Fworker-channel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjo4531%2Fworker-channel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjo4531%2Fworker-channel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnsonjo4531","download_url":"https://codeload.github.com/johnsonjo4531/worker-channel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243590906,"owners_count":20315762,"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":["async","async-iterable","channels","communication","orchestrator","rpc","webworker","worker"],"created_at":"2024-11-20T10:13:44.409Z","updated_at":"2025-03-14T14:24:54.239Z","avatar_url":"https://github.com/johnsonjo4531.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Worker-Channel\n\nA modern zero-dependency Worker communication and orchestration library\n\n- [What](#what)\n- [Why](#why)\n- [How](#how)\n  - [Getting Started](#getting-started)\n    - [An Example](#an-example)\n    - [Reading and Writing from the same worker.](#reading-and-writing-from-the-same-worker)\n    - [Using MessageChannels to orchestrate on the main thread.](#using-messagechannels-to-orchestrate-on-the-main-thread)\n\n\n# What\n\nA zero-dependency cross-worker communication library. It works with any kind of W3 based WebWorker.\nIt also allows setting up and orchestrating the communication between any amount of workers\nthe orchestration is generally handled by the UI thread but any worker can orchestrate.\nYou decide what communication takes place between your seperate workers using typescript types.\n\n# Why\n\nThis library provides an easy to use, modern, and type-safe way of cross-worker communication. \n\n# How\n\nThe major primitives are a read, write, and read/write channel.\n\n## Getting Started\n\nFirst install the package.\n\n```bash\nnpm i worker-channel\n```\n\n### An Example\n\n\u003e Want more examples with runnable code see [the examples directory](https://github.com/johnsonjo4531/worker-channel/tree/main/examples).\n\nFirst we start with a type file this will be used from both the worker and the client:\n\n\n**message-types.ts**\n\n```ts\nexport type MessageType = {\n  // This will determine the name of our channel.\n  type: \"string\",\n  // This will determine its data.\n  data: string\n}\n```\n\n\u003ctable\u003e\n\u003cthead\u003e\u003ctr\u003e\u003cth\u003e\u003cstrong\u003emain.ts\u003c/strong\u003e\u003c/th\u003e\u003cth\u003e\u003cstrong\u003eworker.ts\u003c/strong\u003e\u003c/th\u003e\u003c/tr\u003e\u003c/thead\u003e\n\u003ctbody\u003e\u003ctr\u003e\u003ctd\u003e\n\n```ts\nimport { \n  WriteChannel \n} from \"worker-channel\";\nimport { \n  MessageType \n} from \"./message-types\";\n\n// Setup our webworker.\n// Depending on your environment \n// this could look a little different\nconst worker = new Worker(\n  new URL(\n    \"./worker.ts\", \n    import.meta.url\n  ), {\n  type: \"module\",\n});\n\n// Create a write channel to the worker.\nconst wChannel = new WriteChannel\u003c\n  MessageType\n\u003e({\n  writeTo: worker,\n});\n\n// Write to the worker.\n(async () =\u003e {\n  const { write, close } = wChannel;\n  for await (const item of [\n    \"foo\", \"bar\", \"baz\", \"qux\"\n    ]) {\n    // Writing to the \"string\" channel\n    // The .string channel/property \n    // is from our MessageType's type.\n    write.string(item);\n  }\n  // Always good practice to close\n  // the writer.\n  // In node this is especially \n  // important because it can\n  // hang the process without it.\n  close.writer.string();\n})();\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n```ts\nimport { \n  ReadChannel \n} from \"worker-channel\";\nimport { \n  MessageType \n} from \"./message-types\";\n\nconst rwChannel = new ReadChannel\u003c\n  MessageType,\n  MessageType\n\u003e();\n\n(async () =\u003e {\n  // Recieve on the \"string\" channel.\n  for await (const item of rwChannel.readAll.string()) {\n    // Write back to the \"string\" channel in uppercase.\n    console.log(item.toUpperCase());\n  }\n})();\n\n```\n\n\u003c/td\u003e\u003c/tr\u003e\u003c/tbody\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n\n\n### Reading and Writing from the same worker.\n\nA slightly more involved example is to read to and write from a worker over a channel.\nOn the UI side of the application this involves setting up a webworker on the client and setting up our channel as readable and writable.\n\nLets use the same types as last time:\n\n**message-types.ts**\n\n```ts\nexport type MessageType = {\n  // This will determine the name of our channel.\n  type: \"string\",\n  // This will determine its data.\n  data: string\n}\n```\n\n\u003ctable\u003e\n\u003cthead\u003e\u003ctr\u003e\u003cth\u003e\u003cstrong\u003emain.ts\u003c/strong\u003e\u003c/th\u003e\u003cth\u003e\u003cstrong\u003eworker.ts\u003c/strong\u003e\u003c/th\u003e\u003c/tr\u003e\u003c/thead\u003e\n\u003ctbody\u003e\u003ctr\u003e\u003ctd\u003e\n\n```ts\nimport { \n  ReadWriteChannel \n} from \"worker-channel\";\nimport { \n  MessageType \n} from \"./message-types\";\n\nconst worker = new Worker(\n  new URL(\n    \"./worker.ts\",\n    import.meta.url\n  ), {\n  type: \"module\",\n});\n\n// Create a read and write channel \n// to and from the worker.\nconst rwChannel = new ReadWriteChannel\u003c\n  MessageType, \n  MessageType\n\u003e({\n  writeTo: worker,\n  // NEW: Notice we want to read as well this time.\n  readFrom: worker,\n});\n\n// Write to the worker like last time.\n(async () =\u003e {\n  const { write, close } = rwChannel;\n  for await (const item of [\n    \"foo\", \"bar\", \"baz\", \"qux\"\n  ]) {\n    write.string(item);\n  }\n  close.writer.string();\n})();\n// NEW: Listen back from the worker.\n(async () =\u003e {\n  const { readAll } = rwChannel;\n  // Reads everything from the \"string\" channel.\n  for await (const item of readAll.string()) {\n    console.log(item); // logs: \"FOO\", \"BAR\", \"BAZ\", then \"QUX\"\n  }\n  worker.terminate();\n})();\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n```ts\nimport { \n  ReadWriteChannel \n} from \"worker-channel\";\nimport { \n  MessageType \n} from \"./message-types\";\n\nconst rwChannel = new ReadWriteChannel\u003c\n  MessageType, \n  MessageType\n\u003e();\n\n(async () =\u003e {\n  // Recieve on the \"string\" channel.\n  for await (const item of rwChannel.readAll.string()) {\n    // Notice no log this time instead we \n    // write back to the \"string\" channel with\n    // the item in uppercase.\n    rwChannel.write.string(item.toUpperCase());\n  }\n})();\n\n```\n\n\u003c/td\u003e\u003c/tr\u003e\u003c/tbody\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n### Using MessageChannels to orchestrate on the main thread.\n\nAn even more sophisticated example is reading to and writing from a worker using the web's built in MessageChannel.\nOn the UI side of the application this involves using MessageChannels to orchestrate.\nHow your workers can talk to one another.\n\nLets use the same types as last time:\n\n**message-types.ts**\n\n```ts\nexport type MessageType = {\n  // This will determine the name of our channel.\n  type: \"string\",\n  // This will determine its data.\n  data: string\n}\n```\n\n\u003ctable\u003e\n\u003cthead\u003e\u003ctr\u003e\n\u003cth\u003e\u003cstrong\u003emain.ts\u003c/strong\u003e\u003c/th\u003e\n\u003cth\u003e\u003cstrong\u003eworker1.ts\u003c/strong\u003e\u003c/th\u003e\n\u003cth\u003e\u003cstrong\u003eworker2.ts\u003c/strong\u003e\u003c/th\u003e\n\u003c/tr\u003e\u003c/thead\u003e\n\u003ctbody\u003e\u003ctr\u003e\u003ctd\u003e\n\n```ts\nimport { \n  ReadChannel,\n  WriteChannel\n} from \"worker-channel\";\nimport { MyMessage } from \"./message-types.js\";\n\n/// Setup the workers we want to communicate with\n\n// Once everything is setup then\n// this first worker will uppercase\n// whatever string we send in.\nconst worker1 = new Worker(\n  new URL(\n    \"./worker1.ts\",\n    import.meta.url\n  ), {\n  type: \"module\",\n});\n\n// Once everything is setup then \n// this second worker will add \n// three exclamation points to \n// whatever string we send in.\nconst worker2 = new Worker(\n  new URL(\n    \"./worker2.ts\",\n    import.meta.url\n  ), {\n  type: \"module\",\n});\n\n/// Create a message channel to send \n// so the workers can talk to each other.\n/// We'll connect worker1's output to\n// worker2's input.\nconst channel = new MessageChannel();\n\n// Create a writable channel to worker 1\nconst wChannel = new WriteChannel\u003cMyMessage\u003e({\n  writeTo: worker1,\n});\n// Connect worker1 (our wChannel's writeTo)\n// to write to port1.\n// The \"change-writer\" sets our worker1's internal writeTo option.\nwChannel.connect(\n  \"writeTo\",\n  \"change-writer\",\n  channel.port1\n);\n\n// Create a readable channel from worker2.\nconst rChannel = new ReadChannel\u003cMyMessage\u003e({\n  readFrom: worker2,\n});\n\n// Connect worker2 to read from port2\n// The \"change-reader\" sets our worker2's internal readFrom option.\nrChannel.connect(\n  \"readFrom\",\n  \"change-reader\",\n  channel.port2\n);\n\n// Now we use our wChannel to write strings to worker1.\n\n(async () =\u003e {\n  const { write, close } = wChannel;\n  for await (const item of [\"foo\", \"bar\", \"baz\", \"qux\"]) {\n    write.string(item);\n  }\n  // always good practice to tell it you're done.\n  // If you're in node this is especially important, so you don't possibly hang the process.\n  close.writer.string();\n})();\n\n// Finally we read from worker2.\n(async () =\u003e {\n  const { readAll } = rChannel;\n\n  for await (const item of readAll.string()) {\n    // LOGS: \"FOO!!!\", \"BAR!!!\", \"BAZ!!!\", \"QUX!!!\"\n    console.log(item);\n  }\n  // It's good to close the worker when you know you're done.\n  worker1.terminate();\n  worker2.terminate();\n})();\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n```ts\nimport { \n  ReadWriteChannel \n} from \"worker-channel\";\nimport { \n  MessageType \n} from \"./message-types\";\n\nconst rwChannel = new ReadWriteChannel\u003c\n  MessageType, \n  MessageType\n\u003e();\n\n(async () =\u003e {\n  // Recieve on the \"string\" channel.\n  for await (const item of rwChannel.readAll.string()) {\n    // Notice no log this time instead we \n    // write back to the \"string\" channel with\n    // the item in uppercase.\n    rwChannel.write.string(item.toUpperCase());\n  }\n})();\n\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n```ts\nimport { \n  ReadWriteChannel \n} from \"worker-channel\";\nimport { \n  MessageType \n} from \"./message-types\";\n\nconst rwChannel = new ReadWriteChannel\u003c\n  MessageType, \n  MessageType\n\u003e();\n\n(async () =\u003e {\n  // Recieve on the \"string\" channel.\n  for await (const item of rwChannel.readAll.string()) {\n    // Notice no log this time instead we \n    // write back to the \"string\" channel with\n    // the item with three exclamation points.\n    rwChannel.write.string(`${item}!!!`);\n  }\n})();\n```\n\n\n\n\u003c/td\u003e\u003c/tr\u003e\u003c/tbody\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnsonjo4531%2Fworker-channel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnsonjo4531%2Fworker-channel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnsonjo4531%2Fworker-channel/lists"}