• Stars
    star
    698
  • Rank 63,160 (Top 2 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created about 7 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A debugging library for RxJS

rxjs-spy

GitHub License NPM version Downloads Build status dependency status devDependency Status peerDependency Status Greenkeeper badge

What is it?

rxjs-spy is a debugging library for RxJS.

Why might you need it?

The usual approach to debugging RxJS-based code involves sprinkling do operators and logging throughout composed observables. That's something that I find tedious, so I wrote this library and implemented an unobtrusive mechanism for identifying observables and logging and inspecting observable subscriptions.

If you, too, are looking for a less painful RxJS debugging experience, you might find this library useful. The engineers at Slack have adopted rxjs-spy and have this to say about it:

You might be like, "[...] but aren't Observables impossible to debug?" And you'd have been mostly right less than a year ago. But this is JavaScript and in JavaScript, the only const is change. rxjs-spy makes debugging (i.e. logging and visualizing) streams as simple as adding a tag. A tagged stream can be monitored, paused, and replayed, right from the console.

For more detail regarding how the library works and what it can do, you can have a look at:

Install

Install the package using NPM:

npm install rxjs-spy --save-dev

And import the functions for use with TypeScript or ES2015:

import { create } from "rxjs-spy";
const spy = create();

Or require the module for use with Node or a CommonJS bundler:

const { create } = require("rxjs-spy");
const spy = create();

Or include the UMD bundle for use as a script:

<script src="https://unpkg.com/rxjs@6/bundles/rxjs.umd.min.js"></script>
<script src="https://unpkg.com/rxjs-spy@7/bundles/rxjs-spy.min.umd.js"></script>
<script>
const { create } = rxjsSpy;
create();
</script>

Core concepts

rxjs-spy introduces a tag operator that can be used to identify observables. It attaches a string tag to an observable; it performs no additional processing and does not alter the observable's behaviour or value in any way.

The tag operator can be used with pipe:

import { tag } from "rxjs-spy/operators/tag";
const source = Observable.of("some-value").pipe(tag("some-tag"));

The API's methods are tag-based and tags can be matched using explicit literals, regular expressions or function predicates. For example, logging for the above tag could be enabled like this:

import { create } from "rxjs-spy";
const spy = create();
spy.log("some-tag");

// Or like this:
spy.log(/^some-tag$/);

// Or like this:
spy.log(tag => tag === "some-tag");

rxjs-spy exposes a module API intended to be called from code and a console API - via the spy global - intended for interactive use via the browser's console.

Module API

The methods in the module API are callable via imports, requires or the UMD rxjsSpy global. Most methods return a teardown function that will undo the API method's action when called.

create

function create(options: {
    [key: string]: any,
    audit?: number,
    defaultLogger?: PartialLogger,
    defaultPlugins?: boolean,
    warning?: boolean
} = {}): Teardown

Calling create attaches the spy to Observable.prototype.subscribe and returns the following interface:

interface Spy {
  readonly tick: number;
  debug(match: Match, ...notifications: Notification[]): Teardown;
  find<T extends Plugin>(ctor: Ctor<T>): T | undefined;
  findAll<T extends Plugin>(ctor: Ctor<T>): T[];
  findAll(): Plugin[];
  flush(): void;
  let(match: Match, select: (source: Observable<any>) => Observable<any>, options?: Options): Teardown;
  log(match: Match, partialLogger?: PartialLogger): Teardown;
  log(partialLogger?: PartialLogger): Teardown;
  pause(match: Match): Deck;
  plug(...plugins: Plugin[]): Teardown;
  show(match: Match, partialLogger?: PartialLogger): void;
  show(partialLogger?: PartialLogger): void;
  stats(partialLogger?: PartialLogger): void;
  teardown(): void;
  unplug(...plugins: Plugin[]): void;
}

By default, create will wire up the snapshotting plugin and numerous others. However, if the defaultPlugins option is specified as false, no plugins will be wired up and the caller can wire up plugins individually using the plug method. For example:

import { create } from "rxjs-spy";
import { GraphPlugin, SnapshotPlugin } from "rxjs-spy/plugin";
const spy = create({ defaultPlugins: false });
spy.plug(
  new GraphPlugin({ keptDuration: -1 }),
  new SnapshotPlugin(spy, { keptValues: 1 })
);

If the audit option is specified, the logging of notifications will be audited within the specified (milliseconds) duration. Each notification source will only be logged once in each duration and the number of ignored notifications (if any) will be included in the console output. This can be useful for logging high-frequency observables. audit defaults to zero - i.e. no auditing.

Options passed to create are forwarded to the plugins, so the following can be specified:

Option Type Description Default
keptDuration number The number of milliseconds for which the subscription graph and snapshots should be kept after unsubscription occurs. 30000
keptValues number The maximum number of values that should be kept in a snapshot. 4
sourceMaps boolean Whether or not the StackTracePlugin should use source maps. false

This method returns a teardown function.

show

interface Spy {
  show(
    match: string | RegExp | MatchPredicate | Observable<any>,
    partialLogger: PartialLogger = console
  ): void;
  show(
    partialLogger: PartialLogger = console
  ): void;
}

show will log information regarding the matching observables to the console or to the specified logger. If no match is specified, all tagged observables will be logged.

The logged information is retrieved from the most recent snapshot, so if snapshotting is not enabled, an error will be thrown.

log

interface Spy {
  log(
    match: string | RegExp | MatchPredicate | Observable<any>,
    partialLogger: PartialLogger = console
  ): Teardown;
  log(
    partialLogger: PartialLogger = console
  ): Teardown;
}

Wires up an instance of the log plugin for matching observables. If no match is specified, all tagged observables will be logged.

All subscribe, next, complete, error and unsubscribe notifications will be logged to the console or to the specified logger.

This method returns a teardown function.

pause

interface Spy {
  pause(
    match: string | RegExp | MatchPredicate | Observable<any>
  ): Deck;
}

Wires up an instance of the pause plugin for matching observables.

All subscriptions to matching observables will be placed into a paused state and notifications that would otherwise be emitted will be buffered inside the plugin.

This method returns a Deck instance that can be used to resume and pause the observables.

interface Deck {
  readonly paused: boolean;
  clear(): void;
  log(partialLogger: PartialLogger = console): void;
  pause(): void;
  resume(): void;
  skip(): void;
  step(): void;
  teardown(): void;
}

Calling step will release a single paused notification. The other methods to what their names suggest. Calling resume will play all buffered notifications before resuming.

let

interface Spy {
  let(
    match: string | RegExp | MatchPredicate | Observable<any>,
    select: (source: Observable<any>) => Observable<any>,
    options?: Options
  ): Teardown;
}

Wires up an instance of the let plugin for matching observables.

This is equivalent to the let operator. All subscriptions to matching observables will instead be made to the observable returned by the specified select function.

If complete option is false, completion notifications received from the selected observable will not be forwarded to subscribers.

This method returns a teardown function.

debug

interface Spy {
  debug(
    match: string | RegExp | MatchPredicate | Observable<any>,
    ...notifications: ("complete" | "error" | "next" | "subscribe" | "unsubscribe")[]
  ): Teardown;
}

Wires up an instance of the debug plugin for matching observables.

Whenever one of the specified notifications occurs, a debugger statement in the plugin will pause execution. If no notifications are specified in the call, execution will be paused when any of the notifications occurs.

This method returns a teardown function.

flush

interface Spy {
  flush(): void;
}

Calling flush will see flush called on each plugin.

If snapshotting is enabled, calling flush will release excess values and completed or errored obervables from within snapshots.

plug

interface Spy {
  plug(...plugins: Plugin[]): Teardown;
}

Wires up the specified plugin(s) and returns a teardown function.

unplug

interface Spy {
  unplug(...plugins: Plugin[]): void;
}

Removes the specified plugin(s).

find

interface Spy {
  find<T extends Plugin>(constructor: { new (...args: any[]): T }): T | undefined;
}

Returns the first plugin matching the specified constructor/class.

findAll

interface Spy {
  findAll<T extends Plugin>(constructor: { new (...args: any[]): T }): T[];
  findAll(): T[];
}

Returns all plugins matching the specified constructor/class. Or all plugins of no constructor is specified.

stats

interface Spy {
  stats(partialLogger: PartialLogger = console): void;
}

Writes, to the console, counts of the number of notifications, etc.

teardown

interface Spy {
  teardown(): void;
}

Tears down the spy.

detect

function detect(id: string): void;

Writes, to the console, any subscriptions and unsubscriptions that have occurred since the previous detect call with the specified id.

The detect method is implemented so that it can be imported and called regardless of whether or not the spy is configured. That is, calls can be left in production code, as they become no-ops. It should be imported like this:

import { detect } from "rxjs-spy/detect";

Console API

The methods in the console API are callable via the spy global and are intended to be used interactively in the browser's console.

They are identical to the methods in the spy instances created using the module API except for the fact that they do not return teardown functions. Instead, calls can be undone using the undo API method.

undo

function undo(...calls: number[]): void

When called without arguments, the undo method will display in the console a list of the rxjs-spy calls that can be undone.

Calls are listed against a call number and one or more of those numbers can be passed to undo to undo specific calls.

Undoing a spy call will undo all calls.

deck

function deck(call?: number): Deck | undefined

In the console, it's easy to forget to use a variable to capture the Deck returned by a call to pause. In those situations, you can call the deck method without an argument to see a list of numbered pause calls. Calling deck again, passing a call number, will return the Deck associated with the specified pause call.

More Repositories

1

rxjs-tslint-rules

TSLint rules for RxJS
TypeScript
370
star
2

rxjs-marbles

An RxJS marble testing library for any test framework
TypeScript
300
star
3

eslint-plugin-rxjs

ESLint rules for RxJS
TypeScript
280
star
4

rxjs-etc

Observables and operators for RxJS
TypeScript
214
star
5

ts-action

TypeScript action creators for Redux
TypeScript
184
star
6

eslint-plugin-etc

More general-purpose (TypeScript-related) ESLint rules
TypeScript
140
star
7

rxjs-observe

A library for observing an object's property assignments and method calls
TypeScript
96
star
8

eslint-plugin-rxjs-angular

ESLint rules for RxJS and Angular
TypeScript
94
star
9

tslint-etc

More rules for TSLint
TypeScript
43
star
10

firebase-key

Firebase key utility and encoding/decoding functions
TypeScript
39
star
11

rxjs-spy-devtools

Chrome DevTools for rxjs-spy
TypeScript
39
star
12

firebase-nightlight

An in-memory, JavaScript mock for the Firebase Web API
TypeScript
37
star
13

ts-action-operators

TypeScript action operators for NgRx and redux-observable
TypeScript
33
star
14

ts-snippet

A TypeScript snippet compiler for any test framework
TypeScript
32
star
15

eslint-plugin-react-etc

More ESLint rules for React
TypeScript
16
star
16

devtools-example

DevTools extension examples
JavaScript
16
star
17

eslint-etc

Utils for ESLint TypeScript rules
TypeScript
15
star
18

rxjs-xyz

RxJS community packages
JavaScript
14
star
19

rxjs-pluggables

RxJS observables and operators with pluggable strategies
TypeScript
14
star
20

firebase-thermite

Firebase RxJS observables
TypeScript
13
star
21

rxjs-traits

RxJS Traits for Static Analysis
TypeScript
13
star
22

rxjs-report-usage

Report a project's RxJS API usage to the core team
JavaScript
10
star
23

rxjs-interop

Observable interop helpers for RxJS
TypeScript
8
star
24

eslint-plugin-rxjs-traits

TypeScript
8
star
25

blog

Blog post Markdown content
Shell
6
star
26

tsutils-etc

TypeScript
6
star
27

recompose-etc

React function components and higher-order components based on recompose and RxJS
TypeScript
4
star
28

cartant

3
star
29

memoize-resolver

A general-purpose key resolver for memoize
TypeScript
3
star
30

eslint-plugin-dtslint

ESLint rules for dtslint tests
TypeScript
2
star
31

eslint-issues

A repo for reproducing ESLint plugin problems
TypeScript
1
star
32

eslint-config-rxjs

JavaScript
1
star
33

eslint-config-etc

JavaScript
1
star
34

eslint-config

JavaScript
1
star
35

eslint-config-react

JavaScript
1
star