{"id":19319668,"url":"https://github.com/blockcoders/nestjs-io-client","last_synced_at":"2025-04-22T17:31:57.433Z","repository":{"id":95504700,"uuid":"402731970","full_name":"blockcoders/nestjs-io-client","owner":"blockcoders","description":"Socket.io Client for NestJS based on socket.io-client","archived":false,"fork":false,"pushed_at":"2022-03-24T14:09:43.000Z","size":347,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-02T02:22:30.540Z","etag":null,"topics":["io","io-client","nest","nestjs","socket","socket-io","socket-io-client","socket-io-library","socket-io-protocol","socketio","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blockcoders.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2021-09-03T10:30:29.000Z","updated_at":"2025-03-26T17:08:21.000Z","dependencies_parsed_at":"2023-05-22T17:15:25.472Z","dependency_job_id":null,"html_url":"https://github.com/blockcoders/nestjs-io-client","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockcoders%2Fnestjs-io-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockcoders%2Fnestjs-io-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockcoders%2Fnestjs-io-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockcoders%2Fnestjs-io-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blockcoders","download_url":"https://codeload.github.com/blockcoders/nestjs-io-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250287646,"owners_count":21405656,"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":["io","io-client","nest","nestjs","socket","socket-io","socket-io-client","socket-io-library","socket-io-protocol","socketio","websocket"],"created_at":"2024-11-10T01:24:45.973Z","updated_at":"2025-04-22T17:31:57.422Z","avatar_url":"https://github.com/blockcoders.png","language":"TypeScript","readme":"# NestJS Socket.io Client\n\n[![npm](https://img.shields.io/npm/v/nestjs-io-client)](https://www.npmjs.com/package/nestjs-io-client)\n[![CircleCI](https://circleci.com/gh/blockcoders/nestjs-io-client/tree/main.svg?style=svg)](https://circleci.com/gh/blockcoders/nestjs-io-client/tree/main)\n[![Coverage Status](https://coveralls.io/repos/github/blockcoders/nestjs-io-client/badge.svg?branch=main)](https://coveralls.io/github/blockcoders/nestjs-io-client?branch=main)\n[![vulnerabilities](https://img.shields.io/snyk/vulnerabilities/npm/nestjs-io-client)](https://snyk.io/test/github/blockcoders/nestjs-io-client)\n[![supported platforms](https://img.shields.io/badge/platforms-Express%20%26%20Fastify-green)](https://img.shields.io/badge/platforms-Express%20%26%20Fastify-green)\n\nSocket.io Client for NestJS based on [socket.io-client](https://www.npmjs.com/package/socket.io-client)\n\n## Install\n\n```sh\nnpm i nestjs-io-client\n```\n\n## Register module\n\n### Configuration params\n\n`nestjs-io-client` can be configured with this options:\n\n```ts\n/**\n * Socket.io Client options\n * @see {@link https://socket.io/docs/v4/client-api/#iourl}\n */\ninterface IoClientModuleOptions {\n  /**\n   * Required parameter a URL to connect.\n   * such as http://localhost:3000/my-namespace or ws://localhost:3000/my-namespace.\n   */\n  uri: string;\n\n  /**\n   * Optional parameter a client or http request options.\n   */\n  options?: Partial\u003cManagerOptions \u0026 SocketOptions\u003e\n}\n```\n\n### Synchronous configuration\n\nUse `IoClientModule.forRoot` method with [Options interface](#configuration-params):\n\n```ts\nimport { IoClientModule } from 'nestjs-io-client'\n\n@Module({\n  imports: [\n    IoClientModule.forRoot({\n      uri: 'ws://localhost:3000/my-namespace',\n      options: {\n        reconnectionDelayMax: 10000,\n        auth: { token: '123' },\n        query: {\n          foo: 'value'\n        },\n      },\n    }),\n  ],\n  ...\n})\nclass MyModule {}\n```\n\n### Asynchronous configuration\n\nWith `IoClientModule.forRootAsync` you can, for example, import your `ConfigModule` and inject `ConfigService` to use it in `useFactory` method.\n\n`useFactory` should return object with [Options interface](#configuration-params)\n\nHere's an example:\n\n```ts\nimport { Module, Injectable } from '@nestjs/common'\nimport { IoClientModule } from 'nestjs-io-client'\n\n@Injectable()\nclass ConfigService {\n  public readonly uri = 'ws://localhost:3000/my-namespace'\n}\n\n@Module({\n  providers: [ConfigService],\n  exports: [ConfigService]\n})\nclass ConfigModule {}\n\n@Module({\n  imports: [\n    IoClientModule.forRootAsync({\n      imports: [ConfigModule],\n      inject: [ConfigService],\n      useFactory: (config: ConfigService) =\u003e {\n        return {\n          uri: config.uri,\n        }\n      },\n    }),\n  ],\n  ...\n})\nclass MyModule {}\n```\n\nOr you can just pass `ConfigService` to `providers`, if you don't have any `ConfigModule`:\n\n```ts\nimport { Module, Injectable } from '@nestjs/common'\nimport { IoClientModule } from 'nestjs-io-client'\n\n@Injectable()\nclass ConfigService {\n  public readonly uri = 'ws://localhost:3000/my-namespace'\n}\n\n@Module({\n  imports: [\n    IoClientModule.forRootAsync({\n      providers: [ConfigService],\n      inject: [ConfigService],\n      useFactory: (config: ConfigService) =\u003e {\n        return {\n          uri: config.uri,\n        }\n      },\n    }),\n  ],\n  controllers: [TestController]\n})\nclass TestModule {}\n```\n\n## IoClient\n\n`IoClient` implements a [Socket](https://socket.io/docs/v4/client-api/#socket). So if you are familiar with it, you are ready to go.\n\n```ts\nimport { Injectable } from '@nestjs/common'\nimport {\n  InjectIoClientProvider,\n  IoClient,\n  OnConnect,\n  OnConnectError,\n  EventListener,\n} from 'nestjs-io-client';\n\n@Injectable()\nclass TestService {\n  constructor(\n    @InjectIoClientProvider()\n    private readonly io: IoClient,\n  ) {}\n\n  @OnConnect()\n  connect() {\n    console.log('connected!')\n    console.log(this.io.id); // \"G5p5...\"\n    console.log(this.io.connected); // true\n  }\n  \n  @OnConnectError()\n  connectError(err: Error) {\n    console.error(`An error occurs: ${err}`)\n  }\n\n  @EventListener('news')\n  message(data: any) {\n    console.log(data);\n  }\n}\n```\n\n## Socket.io Events\n\n### EventListener\n\n`@EventListener` decorator will handle any event emitted from socket.io server.\n\n```ts\nimport { Injectable } from '@nestjs/common'\nimport {\n  EventListener\n} from 'nestjs-io-client';\n\n@Injectable()\nclass TestService {\n  @EventListener('connect')\n  open() {\n    console.log('The connection is established.')\n  }\n  \n  @EventListener('ping')\n  ping() {\n    console.log('A ping is received from the server.')\n  }\n  \n  @EventListener('reconnect')\n  unexpectedResponse() {\n    console.log('successful reconnection')\n  }\n  \n  @EventListener('news')\n  upgrade(data: any) {\n    console.log(data);\n  }\n}\n```\n\n### OnConnect\n\n`@OnConnect` is a shortcut for `@EventListener('connect')`. Event emitted when the connection is established.\n\n```ts\nimport { Injectable } from '@nestjs/common'\nimport {\n  OnConnect\n} from 'nestjs-io-client';\n\n@Injectable()\nclass TestService {\n  @OnConnect()\n  connect() {\n    console.log('The connection is established.')\n  }\n}\n```\n\n### OnDisconnect\n\n`@OnDisconnect` is a shortcut for `@EventListener('disconnect')` Event emitted when the connection is closed. `reason` is a string explaining why the connection has been closed.\n\n```ts\nimport { Injectable } from '@nestjs/common'\nimport {\n  IoClient,\n  OnDisconnect\n} from 'nestjs-io-client';\n\n@Injectable()\nclass TestService {\n  @OnDisconnect()\n  disconnect(reason: IoClient.DisconnectReason) {\n    if (reason === \"io server disconnect\") {\n      // the disconnection was initiated by the server, you need to reconnect manually\n      socket.connect();\n    }\n    // else the socket will automatically try to reconnect\n  }\n}\n```\n\n### OnConnectError\n\n`@OnConnectError` is a shortcut for `@EventListener('connect_error')` Event emitted when when an namespace middleware error occurs.\n\n```ts\nimport { Injectable } from '@nestjs/common'\nimport {\n  OnConnectError\n} from 'nestjs-io-client';\n\n@Injectable()\nclass TestService {\n  @OnConnectError()\n  connectError(err: Error) {\n    console.error(`An error occurs: ${err}`)\n  }\n}\n```\n\n## Testing a class that uses @InjectIoClientProvider\n\nThis package exposes a `getIoClientToken()` function that returns a prepared injection token based on the provided context.\nUsing this token, you can easily provide a mock implementation of the [Socket](https://socket.io/docs/v4/client-api/#socket) using any of the standard custom provider techniques, including useClass, useValue, and useFactory.\n\n```ts\nconst module: TestingModule = await Test.createTestingModule({\n  providers: [\n    MyService,\n    {\n      provide: getIoClientToken(),\n      useValue: mockProvider,\n    },\n  ],\n}).compile();\n```\n\n## Change Log\n\nSee [Changelog](CHANGELOG.md) for more information.\n\n## Contributing\n\nContributions welcome! See [Contributing](CONTRIBUTING.md).\n\n## Collaborators\n\n- [**Jose Ramirez**](https://github.com/0xslipk)\n\n## License\n\nLicensed under the Apache 2.0 - see the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockcoders%2Fnestjs-io-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblockcoders%2Fnestjs-io-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockcoders%2Fnestjs-io-client/lists"}