@statepulse/nestjs

NestJS module for StatePulse — background polling and state management.

Installation

npm install statepulse @statepulse/nestjs

Setup

Static Configuration

import { Module } from "@nestjs/common";
import { StatePulseModule } from "@statepulse/nestjs";

@Module({
  imports: [
    StatePulseModule.forRoot({
      enableSignalHandling: false,
    }),
  ],
})
export class AppModule {}

Async Configuration

import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { StatePulseModule } from "@statepulse/nestjs";

@Module({
  imports: [
    ConfigModule.forRoot(),
    StatePulseModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        enableSignalHandling: config.get<boolean>("PULSE_SIGNAL_HANDLING", false),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Usage

StatePulseService is globally available after importing the module — inject it into any provider:

import { Injectable, OnModuleInit } from "@nestjs/common";
import { StatePulseService } from "@statepulse/nestjs";

@Injectable()
export class PriceFeedService implements OnModuleInit {
  constructor(private readonly pulse: StatePulseService) {}

  async onModuleInit(): Promise<void> {
    await this.pulse.register({
      key: "exchange-rates",
      run: async () => {
        const res = await fetch("https://api.example.com/rates");
        return res.json();
      },
      refreshPolicy: { intervalMs: 15000 },
      retryPolicy: { count: 3 },
      logErrors: (err) => console.error("Rate fetch failed:", err),
    });
  }

  async getLatestRates(): Promise<Record<string, number> | null> {
    const snapshot = await this.pulse.get<Record<string, number>>("exchange-rates");
    return snapshot?.value ?? null;
  }
}

Lifecycle

The module automatically calls terminate() on the underlying StatePulse instance when the NestJS application shuts down. Signal handling (SIGINT/SIGTERM) is disabled because NestJS manages its own shutdown hooks.

License

MIT © Leo