rxjs-audit-with/README.md

A template for creating npm packages using TypeScript and VSCode

# rxjs-audit-with

[![npm package][npm-img]][npm-url]
[![Build Status][build-img]][build-url]
[![Downloads][downloads-img]][downloads-url]
[![Issues][issues-img]][issues-url]
[![Code Coverage][codecov-img]][codecov-url]
[![Commitizen Friendly][commitizen-img]][commitizen-url]
[![Semantic Release][semantic-release-img]][semantic-release-url]

An RxJS operator that serializes async calls in Observables by keeping the latest values and dropping interim ones while the async call is blocked. It's called `auditWith` because it's like RxJS's `audit`, which only keeps the latest value in the pipe, but it feeds that value through the pipe only when the async callback is free again.

```Typescript
import auditWith from "rxjs-audit-with";

async function slowFunc(num: number) {
  await new Promise(resolve =>
    setTimeout(() => {
      console.log("Processed num", num);
      resolve(true);
    }, 3000),   // deliberately slow, taking 3 secs
  );
}

interval(500)
  .pipe(
    take(13),
    auditWith(slowFunc),  // Calls slowFunc with latest value once it's free
  )
  .subscribe();

// Sample output:
// Processed num 0
// Processed num 5
// Processed num 11
// Processed num 12
```

The most common use cases for this are where you have an async function (e.g. web fetch) where you'd like to serialize calls to it (i.e. it shouldn't be concurrent), but you only want to call it with the most recent value generated by the Observable. It can also act as a semaphone to protect data structures that can't be re-entrant across threads.

## Install

RxJS is required as a peer dependency, but you no doubt already have it installed if you're looking at this package. But if not, you should [use these instructions](https://github.com/ReactiveX/rxjs#readme) to install it.

Then:

```bash
npm install rxjs-audit-with
```
or
```bash
yarn add rxjs-audit-with
```

## How It Works

```Typescript
unction auditWith<T>(callback: (value: T) => Promise<any>):
  MonoTypeOperatorFunction<T> {
  const freeToRun = new BehaviorSubject(true);

  return (source: Observable<T>) => {
    return source.pipe(
      audit(val => freeToRun.pipe(filter(free => free))),
      tap(() => freeToRun.next(false)),
      mergeMap(async val => {
        await callback(val);
        return val;
      }),
      tap(() => freeToRun.next(true)),
    );
  };
}
```

`auditWith` is an operator that uses a `BehaviorSubject` to track whether `callback` is busy. It uses `audit` to keep only the most recent value to come down the pipe, and releases that value the next time the `BehaviorSubject` is marked as free. `tap` goes before and after the async call in order to make it as busy/free (respectively), and `mergeMap` is used to actually call the async callback. Note that callback receives the latest value from the pipe, but can return anything it wants (if anything at all); the original value will propagate down the pipe unchanged (by design).

[build-img]:https://github.com/fivecar/rxjs-audit-with/actions/workflows/release.yml/badge.svg
[build-url]:https://github.com/fivecar/rxjs-audit-with/actions/workflows/release.yml
[downloads-img]:https://img.shields.io/npm/dt/rxjs-audit-with
[downloads-url]:https://www.npmtrends.com/rxjs-audit-with
[npm-img]:https://img.shields.io/npm/v/rxjs-audit-with
[npm-url]:https://www.npmjs.com/package/rxjs-audit-with
[issues-img]:https://img.shields.io/github/issues/fivecar/rxjs-audit-with
[issues-url]:https://github.com/fivecar/rxjs-audit-with/issues
[codecov-img]:https://codecov.io/gh/fivecar/rxjs-audit-with/branch/main/graph/badge.svg
[codecov-url]:https://codecov.io/gh/fivecar/rxjs-audit-with
[semantic-release-img]:https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-release-url]:https://github.com/semantic-release/semantic-release
[commitizen-img]:https://img.shields.io/badge/commitizen-friendly-brightgreen.svg
[commitizen-url]:http://commitizen.github.io/cz-cli/