Quickstart guide using BigState Client Angular

Ngx BigState Client is a lightweight Angular wrapper around the core BigState JavaScript client. It provides a clean, service-driven API that integrates seamlessly with Angular’s dependency injection system, enabling real-time BigState data access through RxJS streams or Angular Signals within any component or service.

Requirements#

To use BigState Client Angular, your project must meet the following requirements:

• Angular 19.0.0 or higher
• TypeScript (optional) If your project uses TypeScript, version 5.x or higher is recommended.
• bigstate.client.javascript The core JavaScript client is included automatically as a dependency — no manual installation required.

Installation#

npm install ngx-bigstate-client

Configuration#

import { bootstrapApplication } from '@angular/platform-browser';
import { provideBsClientConfig } from 'ngx-bigstate-client';
import { AppComponent } from './app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideBsClientConfig({
      http: {
        baseUrl: 'https://api.bigstate.io',
        apiKey: API_KEY,
      },
      ws: {
        baseUrl: 'https://ws.delivery.bigstate.io',
        apiKey: API_KEY,
      },
    }),
  ],
});

Below is a list of the allowed properties.

• http - required - object - An array of sids whose states need to be listened to.
• baseUrl - required - string - this is the root URL to which the client will automatically add the paths of all its HTTP requests. This is the "entry point" to API.
• apiKey - optional - string - the API key used to authenticate requests. It is transmitted to the client if access to service is based on static keys. If an apiKey is specified, the token field is usually not required. How get an ApiKey?
• token - optional - string - the access window that is used to authorize requests. If a token is specified, the apiKey field can be omitted.
• ws - required - object - An array of sids whose states need to be listened to.
• baseUrl - required - string - this is the root URL to which the client will automatically add the paths of all its HTTP requests. This is the "entry point" to API.
• maxReconnectCount - optional - number - Maximum number of reconnection attempts if the WebSocket connection is lost. (11 by default)
• reconnectTime - optional - number - Delay in milliseconds before attempting to reconnect to the WebSocket delivery. (5000 by default)
• apiKey - optional - string - the API key used to authenticate requests. It is transmitted to the client if access to service is based on static keys. If an apiKey is specified, the token field is usually not required. How get an ApiKey?
• token - optional - string - the access window that is used to authorize requests. If a token is specified, the apiKey field can be omitted.

Basic usage#

NgxBigStateClientService — an Angular service that subscribes to BigState delivery channels over WebSocket and receives real-time updates for the specified subject states (SIDs). It automatically: establishes the WebSocket delivery stream, retrieves initial state values via HTTP, merges and synchronizes incoming updates, tracks the most recent change (lastChanged), and exposes the current state map (BigStateResult) for all requested SIDs.

import { NgxBigStateClientService } from 'ngx-bigstate-client';

constructor(private bigState: NgxBigStateClientService) {}

stream$ = this.bigState.stream(deliveryIds, sids);
// or
streamSignal = this.bigState.streamSignal(deliveryIds, sids);

Below is a list of the allowed properties.

• deliveryIds - required - array[string] - A list of delivery IDs that updates will be sent through.
• sids - required - array[string] - An array of sids whose states need to be listened to.

Return values#

• lastChanged is ideal for side effects (notifications, UI updates).
• bigState is the best place to read the current data.
• You can subscribe to multiple deliveryIds and SIDs at the same time.
• Using the generic TMap provides strict type safety for each SID’s value.

Example (RxJS)#

const SID = "simple:counter";
const DELIVERY = 'deliveryId';

import { NgxBigStateClientService } from 'ngx-bigstate-client';

constructor(private bigState: NgxBigStateClientService) {}

state$ = this.bigState
  .stream<MyStateMap>([DELIVERY], [SID])
  .subscribe(result => {
    console.log(result.bigState);
    console.log(result.lastChanged);
  });

Example (Signals)#

const SID = "simple:counter";
const DELIVERY = 'deliveryId';

import { NgxBigStateClientService } from 'ngx-bigstate-client';

constructor(private bigState: NgxBigStateClientService) {}

stateSignal = this.bigState.streamSignal<MyStateMap>(
  [DELIVERY],
  [SID]
);

const currentState = this.stateSignal().bigState;
const lastChanged = this.stateSignal().lastChanged;

• bigState - Contains the states of all signed SIDs as an object.
• prevState -object - returns an object containing the previous state value and its timestamp (value, at).
• currState - object - returns an object containing the current state value and its timestamp (value, at).
• error - object - returns an object describing the error, including its value and the time it occurred (value, at).
• lastChanged - Contains information about the latest update.
• sid -string - the unique identifier of the subject.
• currState - object - returns an object containing the current state value and its timestamp (value, at).
• error - object - returns an object describing the error, including its value and the time it occurred (value, at).

Using bigState#

RxJS example#

const SID = "simple:counter";
const DELIVERY = 'deliveryId';

counter = 0;

state$ = this.bigState.stream<MyStateMap>([DELIVERY], [SID]);

constructor(private bigState: NgxBigStateClientService) {}

ngOnInit() {
  state$.subscribe(result => {
    this.counter = result.lastChanged.value.currState.value.count;
  });
}

<div class="counter-container">
  <div>{{ counter }}</div>
</div>

Signals example#

const SID = "simple:counter";
const DELIVERY = 'deliveryId';

constructor(private bigState: NgxBigStateClientService) {}

stateSignal = this.bigState.streamSignal(
  [DELIVERY],
  [SID],
);

counter = computed(() => {
  const result = this.stateSignal();
  return result.lastChanged?.value?.currState?.value?.count ?? 0;
});

<div class="counter-container">
  <div>{{ counter() }}</div>
</div>

Reaction to updates (typical case)#

Use matchPattern to determine whether the latest update belongs to a SID you care about. This is especially useful when monitoring multiple SIDs.

RxJS example#

import { matchPattern } from 'ngx-bigstate-client';

constructor(private bigState: NgxBigStateClientService) {}

this.bigState.stream([DELIVERY], [SID]).subscribe(result => {
  const last = result.lastChanged;
  if (!last) return;

  const isCurrentSid = matchPattern(SID, last.sid);
  const value = last.value?.currState?.value;

  if (isCurrentSid && value) {
    callback(value);
  }
});

Signals example#

import { effect } from '@angular/core';
import { matchPattern } from 'ngx-bigstate-client';

constructor(private bigState: NgxBigStateClientService) {
  effect(() => {
    const result = this.stateSignal();
    const last = result.lastChanged;
    if (!last) return;

    const isCurrentSid = matchPattern(SID, last.sid);
    const value = last.value?.currState?.value;

    if (isCurrentSid && value) {
      callback(value);
    }
  });
}