@angular-kit/rx-stateful

rxStateful$ is a powerful RxJs operator that wraps any sync or async Observable and provides a stateful stream.

Hint: You can use it on both sync and async Observables. However the real benefits you will get for async Observables.

Installation

npm install @angular-kit/rx-stateful
yarn add @angular-kit/rx-stateful
pnpm add @angular-kit/rx-stateful
  

Demo

A live demo is available on here

Usage

rxStateful$ as standalone function

Sync source Observable

import { rxStateful$ } from '@angular-kit/rx-stateful';

/**
 * Sync Observable will return: 
 * [
 * { value: 1, hasValue: true, context: 'next', hasError: false, error: undefined },
 * { value: 2, hasValue: true, context: 'next', hasError: false, error: undefined },
 * { value: 3, hasValue: true, context: 'next', hasError: false, error: undefined },
 * ]
 */
const stateful$ = rxStateful$(of(1, 2, 3));

Async source Observable

Basic Usage

import { rxStateful$ } from '@angular-kit/rx-stateful';

/**
 * Async Observable will return: 
 * [
 * { value: null, hasValue: false, context: 'suspense', hasError: false, error: undefined },
 * { value: SOME_VALUE, hasValue: true, context: 'next', hasError: false, error: undefined },
 * ]
 */

const stateful$ = rxStateful$(from(fetch('...')));

const trigger$$ = new Subject<number>()
const refresh$$ = new Subject<void>()
const stateful$ = rxStateful$((id: number) => from(fetch(`.../${id}`)), {
    sourceTriggerConfig: {
        trigger: trigger$$
    },
    refetchStrategy: withRefetchOnTrigger(refresh$$)
});

API

rxStateful$ returns a Observable of with following properties:

• value - the value
• hasValue - boolean if a value is present
• context - the context of the stream ('suspense', 'next', 'error', 'complete')
• hasError - boolean if an error is present
• error - the error, if present
• isSuspense - suspense/loading state

Configuration

rxStateful$ provides configuration possibility on instance level:

Configuration on instance level

You can also provide a configuration on instance level. This will also override the global configuration (if present).

rxStateful$ takes a configuration object as second parameter. The following options are available:

• keepValueOnRefresh - boolean if the value should be kept when the refreshTrigger$ emits. Default: false
• keepErrorOnRefresh - boolean if thel last error should be kept when the refreshTrigger$ emits. Default: false
• refreshTrigger$ - a Subject or Observable that triggers the source again. Default: not set. deprecated use refetchStrategies
• refetchStrategies - single or multiple RefetchStrategies to trigger the source again. Default: not set

Configuration Example

import { rxStateful$ } from '@angular-kit/rx-stateful';

const rxStateful$ = rxStateful$(someSource$, { keepValueOnRefresh: true });

refetchStrategies

• withRefetchOnTrigger
• withAutoRefetch

Usage via RxStatefulClient

In order to use RxStatefulClient you first need to provide it, e.g. in your AppModule:

import {provideRxStatefulClient} from "@angular-kit/rx-stateful";

@NgModule({
    providers: [
        provideRxStatefulClient()
    ],
})
export class AppModule {}

RxStatefulClient offers a request-method which basically has the same signature as rxStateful$ - so there'is no difference in usage.

Global configuration

provideRxStatefulClient() can be configured:

import {provideRxStatefulClient, withConfig} from "@angular-kit/rx-stateful";

@NgModule({
    providers: [
        provideRxStatefulClient(withConfig({ keepValueOnRefresh: true}))
    ],
})
export class AppModule {}

The global configuration will be used for every request-call. You can still override the global configuration by providing a configuration object as second parameter to request-method.

Configuring refresh behaviour

Both rxStateful$ and RxStatefulClient can be configured to refresh the source (e.g. make a HTTP call again).

To define the refresh behaviour you can make use of so called RefetchStrategy's. Right now there are following strategies built in: withAutoRefetch and withRefetchOnTrigger.

Usage on rxStateful$

```typescript
    const instance = rxStateful$(fetch(), { refetchStrategy: [withAutoRefetch(1000, Infinity)] })

Usage on RxStatefulClient

const client = inject(RxStatefulClient);
const instance = client.request(fetch(), { refetchStrategy: [withAutoRefetch(1000, Infinity)] })

All strategies can be cominded in an arbitrary way.

In the future there will come more strategies built in, as well as an easy way to define custom strategies. However defining custom strategies is already possible by implementing the RefetchStrategy interface.

Testing

Please have a look at the testing documentation.

Versioning

This project follows Semantic Versioning.

• Version 1.x.x supports Angular >=14.0.0

License

MIT

Contributing

Any Contributions are welcome. Please open up an issue or create PR if you would like to contribute.

See CONTRIBUTING.md for more information.