\n\n- [Install](#install)\n- [Requirements](#requirements)\n- [What's New in v5.0.0](#whats-new-in-v500)\n- [Use](#use)\n - [Client](#client)\n - [Server](#server)\n- [Migration from v4.x](#migration-from-v4x)\n\n## Install\n\n```sh\nnpm install @hydre/shimio\n```\n\n## Requirements\n\n- **Node.js**: >= 20.0.0\n- **ws**: v8.x (upgraded from v7.x)\n\n## What's New in v5.0.0\n\n- โจ Upgraded to `ws` v8.18.0 (from v7.3.1)\n- ๐ Node.js 20+ support with native private methods and class properties\n- ๐งน Removed Babel dependencies (no longer needed for modern Node.js)\n- ๐ฆ Modernized development dependencies\n- ๐ง Simplified test scripts (removed `--harmony` flags)\n\n## Use\n\n### Client\n\n`threshold` represent the maximum WebSocket `bufferedAmount` length\nbefore starting to delay write operations\n\nThe client emit 3 events\n\n- `connected` when connected\n- `disconnected` when disconnected\n- `channel` when a new channel was openned\n\n```js\nimport Client from '@hydre/shimio/client'\n\nconst client = Client({\n host: 'ws://0.0.0.0:3000',\n threshold: 4096,\n retry_strategy: attempts => 100 // retry connection every 100ms\n })\n\n// possible to pass an option object for testing in nodejs\n// see https://github.com/websockets/ws/blob/41b0f9b36749ca1498d22726d22f72233de1424a/lib/websocket.js#L445\nawait client.connect({\n headers: {}\n})\n```\n\nopen some channel (must be awaited but do not make any network request so it's free)\n\n```js\nconst foo = await client.open_channel()\nconst bar = await client.open_channel()\nconst baz = await client.open_channel()\n```\n\n- write is an async function in which you have to pass an Uint8Array\n- read is an async Iterable\n\nA channel emit a `close` event\n\n```js\nawait foo.write(Uint8Array.of(100))\nawait bar.write(Uint8Array.of(42))\nawait baz.write(Uint8Array.of(100))\n\nfor await const(chunk of bar.read)\n console.log(chunk) // Uint8Array<42>\n```\n\n### Server\n\n```js\nimport Server from '@hydre/shimio/server'\nimport Koa from 'koa'\n\n// not a Class\nconst server = Server({\n koa: new Koa(),\n timeout: 30_000, // dropping unresponding clients\n on_upgrade: ({ request, socket, head, context }) => true, // authentication\n on_socket : ({ socket, context }) => {\n // the client opened a channel (and wrote at least once)\n socket.on('channel', async channel => {\n // let's send back all datas transparently\n for await (const chunk of channel.read)\n await channel.write(chunk)\n })\n },\n channel_limit: 50, // prevent a client from openning too much channel (encoded on an Uint32 (4,294,967,295))\n threshold : 4096, // max bufferedAmount before delaying writes\n ws_options : { // @see https://github.com/websockets/ws\n path : '/',\n perMessageDeflate: false,\n maxPayload : 4096 * 4,\n },\n request_limit: { // 20 request max every 10s\n max : 20,\n every: 1000 * 10,\n },\n time_between_connections: 1000 * 30, // min 30s between 2 connection for an ip\n})\n\nawait server.listen(3000) // promisified for you folks\nawait server.close()\n```\n\n### Testing Pattern: Lazy Server Startup\n\nFor test environments, avoid auto-starting the server on module import. Instead, export startup/shutdown functions:\n\n```js\n// src/index.js - Application setup\nimport Server from '@hydre/shimio/server'\nimport Koa from 'koa'\n\n// Create server instance (does NOT start listening)\nexport const server = Server({\n koa: new Koa(),\n on_upgrade: () => true,\n on_socket: ({ socket }) => {\n socket.on('channel', async channel => {\n for await (const chunk of channel.read)\n await channel.write(chunk)\n })\n },\n ws_options: { path: '/ws' }\n})\n\n// Export start/shutdown functions\nexport async function start() {\n await server.listen(3000)\n console.log('Server started on port 3000')\n}\n\nexport async function shutdown() {\n await server.close()\n console.log('Server stopped')\n}\n```\n\n```js\n// src/server.js - Production entry point\nimport { start } from './index.js'\nawait start()\n```\n\n```js\n// test/server.test.js - Tests create their own instances\nimport { describe, it, before, after } from 'node:test'\nimport Server from '@hydre/shimio/server'\nimport Koa from 'koa'\n\ndescribe('Server tests', () => {\n let server\n\n before(async () => {\n server = Server({ koa: new Koa(), /* ... */ })\n await server.listen(4000)\n })\n\n after(async () => {\n await server.close()\n })\n\n it('should work', async () => {\n // test logic\n })\n})\n```\n\n**Key Points:**\n- The exported `server` instance is never started in test environment\n- Tests create and manage their own server instances in `before`/`after` hooks\n- Production uses a separate entry point that calls `start()`\n- This prevents tests from hanging due to open server connections\n\n\n## Migration from v4.x\n\n### Breaking Changes\n\n#### ws v8 Import Changes\n\nIf you were importing `ws` directly in your code (not recommended, but if you did):\n\n**v4.x (ws v7):**\n```js\nimport ws from 'ws'\nconst wss = new ws.Server({ port: 3000 })\nglobalThis.WebSocket = ws\n```\n\n**v5.0.0 (ws v8):**\n```js\nimport { WebSocketServer } from 'ws'\nimport WebSocket from 'ws'\nconst wss = new WebSocketServer({ port: 3000 })\nglobalThis.WebSocket = WebSocket\n```\n\n**Note:** If you only use `@hydre/shimio/client` and `@hydre/shimio/server`, no code changes needed! The ws v8 migration is handled internally.\n\n### Node.js Version\n\nUpgrade to Node.js >= 20.0.0 before upgrading shimio to v5.0.0.\n\n### No Other Breaking Changes\n\nThe shimio API remains unchanged. All client and server APIs are backward compatible.\n\n","readmeFilename":"README.md"}
![](\"https://img.shields.io/badge/license-Unlicense-blue.svg?style=for-the-badge\"){kind=icon}
\n ![](\"https://img.shields.io/codecov/c/github/hydreio/shimio/master?logo=codecov&style=for-the-badge\"/)
\n \n ![](\"https://img.shields.io/npm/v/@hydre/shimio.svg?logo=npm&style=for-the-badge\"){kind=spacer}
\n \n ![](\"https://img.shields.io/npm/dw/@hydre/shimio?logo=npm&style=for-the-badge\"){kind=spacer}
\n