State class CQRS reactive based for handling cache and API requests

A fully reactive, CQRS‑style data store that binds Angular’s HttpClient to an in‑memory cache, exposing safe, immutable operations via RxJS.

Table of Contents

• Description

• Features

• Getting Started

• Usage

• API

Description

A CQRS reactive API–bound approach that uses RxJS and Angular’s HttpClient to manage queries (selections) and commands in a single, easy‑to‑use class.

Features

• Cache: Keeps fetched data in a private Map and exposes it reactively.

• Queries: value$() and values$() selectors let you subscribe to single or multiple items by key.

• Commands: post(), put(), delete() methods call the API and synchronize the cache on success.

• Immutability: Every cache update creates a new Map so subscribers always see fresh references.

• Builder Pattern: Configure unique key, default values, and optional auto‑reset timer via .withUniqueKey(), .withDefaultValues(), and .withResetTimer().

• Reset: Opt‑in automatic cache reset after a configurable interval.

Getting Started

Step 1 – Install the package

npm install ngx-s-state-api

Step 2 – Import & configure

You can either instantiate State directly in a component or wrap it in an Angular service.

example.service.ts

import { Injectable } from '@angular/core';
import { State }      from 'ngx-s-state-api';
import { User }       from './models/user.model';

@Injectable({ providedIn: 'root' })
export class UserStateService {
  public readonly users = new State<User>('https://api.myapp.com', 'users')
    .withUniqueKey('userId')
    .withDefaultValues([])
    // optionally:
    // .withResetTimer(300_000) // reset cache every 5 minutes
}

Usage

Basic

Inject your service (or instantiate State directly) and subscribe:

@Component({...})
export class UserListComponent {
  users$: Observable<User[]>;

  constructor(private userState: UserStateService) {
    this.users$ = this.userState.users.values$();
    // fetch and cache
    this.userState.users.getAll().subscribe();
  }
}

Fetch single entity

this.userState.users
  .getSingle(42)
  .subscribe(user => console.log('User:', user));

Create / Update / Delete

// create
this.userState.users.post(newUser).subscribe();

// update
this.userState.users.put(updatedUser).subscribe();

// delete
this.userState.users.delete(42).subscribe();

API

Builder Methods

| Method | Signature | Description | | ------------------- | ------------------------------------- | --------------------------------------------------- | | withUniqueKey | (key: string) => this | Change the property name used as the unique key. | | withDefaultValues | (vals: T[]) => this | Seed the cache with an initial array of values. | | withResetTimer | (): this(ms: number) => this | Enable auto‑reset of cache every ms milliseconds. |

Cache Selectors

| Method | Signature | Returns | | --------- | ------------------------------------------------------------ | ------------------------------ | | value$ | (key: K) => Observable<T \| undefined> | Latest value by key | | values$ | () => Observable<T[]>(keys: K[]) => Observable<T[]> | All values or filtered by keys |

HTTP Commands

| Method | Signature | Typical REST Semantics | | ----------- | -------------------------------------------------- | --------------------------------- | | getSingle | (key: K, opts?: HttpOptions) => Observable<T> | GET /endpoint/{key} | | getAll | (opts?: HttpOptions) => Observable<T[]> | GET /endpoint | | post | (entity: T, opts?: HttpOptions) => Observable<T> | POST /endpoint → created entity | | put | (entity: T, opts?: HttpOptions) => Observable<T> | PUT /endpoint → updated entity | | delete | (key: K, opts?: HttpOptions) => Observable<void> | DELETE /endpoint/{key} |

Interval Management

| Method | Signature | Description | | ------------ | ------------ | --------------------------------------------------- | | resetTimer | () => void | Manually restart the auto‑reset timer (if enabled). |