@ssv/signalr-client
Version:
SignalR client library built on top of @microsoft/signalr. This gives you more features and easier to use.
168 lines (131 loc) • 4.96 kB
Markdown
[projectUri]: https://github.com/sketch7/signalr-client
[changeLog]: ./CHANGELOG.md
[developmentWorkflowWiki]: ./docs/DEVELOPMENT-WORKFLOW.md
[apiWiki]: ./docs/API.md
[npm]: https://www.npmjs.com/package/@ssv/signalr-client
# @ssv/signalr-client
[](https://github.com/sketch7/signalr-client/actions/workflows/ci.yml)
[](https://badge.fury.io/js/%40ssv%2Fsignalr-client)
SignalR client library built on top of **@aspnet/signalr**. This gives you more features and easier to use.
**Quick links**
[Change logs][changeLog] | [Project Repository][projectUri] | [API Documentation][apiWiki]
## Features
* Fully **TypeScript** and **ReactiveX**
* Multiple hub connections state management
* Connection state notifications
* Update connection details easily without losing current connection state
* Subscriptions are handled through **RxJS** streams
* Reconnection strategies
* Random strategy
* BackOff strategy
* Random BackOff strategy
* Custom strategy
* Auto re-subscriptions after getting disconnected and re-connected
* Contains minimal dependencies (**SignalR** and **RxJS** only)
* **No constraints** with any framework
* Designed to be straight forward integrated with **any framework** such as *[Angular](#angular-adapter)*, *Aurelia*, *React*, *Vue*, etc...
## Samples
* Real world example [(***Orleans Heroes***)](https://github.com/sketch7/orleans-heroes):
* Client: Angular
* Server: Microsoft Orleans integrated with [Sketch7 SignalR](https://github.com/sketch7/SignalR.Orleans)
* [Angular basic example](#angular-basic-example)
## Installation
Get library via [npm]
```bash
npm install @ssv/signalr-client @microsoft/signalr
```
## API Documentation
Check out the [API Documentation Page][apiWiki].
## Usage
There are **three simple steps**:
1. Register `HubConnectionFactory` in your DI eco system
2. In application bootstrap:
* Register one or more hub connections (by injecting `HubConnectionFactory` and using `create`)
3. Somewhere in your components/services you need:
* Inject `HubConnectionFactory` and call method `get` by passing the `key` for a specific hub connection, this will return `HubConnection`
* Use `HubConnection` to use enhanced signalr features
## Angular Adapter
1. Register `HubConnectionFactory` as a **Provider**
You're all set! Now it's fully integrated with your Angular application.
Continue from the [vanilla usage - step 2](#usage) onwards
### Angular Basic Example
```ts
import { HubConnectionFactory } from "@ssv/signalr-client";
@NgModule({
providers: [
HubConnectionFactory,
...
]
})
export class AppModule {
constructor(factory: HubConnectionFactory) {
factory.create(
{ key: "hero", endpointUri: "/hero" },
{ key: "user", endpointUri: "/userNotifications" }
);
}
}
```
*sample usage in components:*
```ts
import { Component, OnInit, OnDestroy } from "@angular/core";
import { HubConnectionFactory, HubConnection } from "@ssv/signalr-client";
@Component({
selector: "hero-detail",
templateUrl: "./hero-detail.component.html"
})
export class HeroDetailComponent implements OnInit, OnDestroy {
private hubConnection: HubConnection<HeroHub>;
private readonly _destroy$ = new Subject<void>();
constructor(hubFactory: HubConnectionFactory) {
this.hubConnection = hubFactory.get<HeroHub>("hero");
}
ngOnInit(): void {
this.hubConnection.connect().pipe(
takeUntil(this._destroy$),
).subscribe(() => console.log(`connected!!`));
this.hubConnection.on<Hero>("HeroChanged", "singed").pipe(
takeUntil(this._destroy$),
).subscribe(x => console.log(`hero :: singed :: update received`, x));
}
ngOnDestroy() {
this._destroy$.next();
this._destroy$.complete();
}
}
export interface HeroHub {
HeroChanged: string;
}
export interface Hero {
id: string;
name: string;
health: number;
}
```
### Raw Basic Example
Create an instance of `HubConnectionFactory` ideally will be registered into your DI (if you're using any library) or you can create instance manually.
Step 1:
- Register Hubs in the `HubConnectionFactory`
```ts
import { HubConnectionFactory, HubConnection } from "@ssv/signalr-client";
const hubFactory = new HubConnectionFactory();
hubFactory.create(
{ key: "hero", endpointUri: "/hero" },
{ key: "user", endpointUri: "http://localhost:62551/real-time/user" }
);
```
Step2:
- Get Hub by Key
- Connect
- subscribe for `on`
```ts
const hubConnection = hubFactory.get<HeroHub>("hero");
const hubConnection$$ = hubConnection.connect().subscribe(() => {
console.log(`connected!`);
});
const data$$ = hubConnection.on<string>("Send").subscribe(val => {
console.log(`send :: data received >>>`, val);
});
```
### Contributions
Check out the [development guide][developmentWorkflowWiki].