Package Exports

observable-hooks

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (observable-hooks) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

observable-hooks

React hooks for RxJS Observables with super flexible APIs.

Seamless integration of React and RxJS.
- Props and states to Observables.
- Observables to states and props events.
- Conditional rendering with stream of React Components. (Or Suspense with use-suspensible)
Full-powered RxJS. Do whatever you want with Observables. No limitation nor compromise.
Fully tested.
Tiny and fast. A lot of efforts had been put into improving integration. This library should have zero visible impact on performance.

Why?

React added hooks for reusing stateful logic.

Observable is a powerful way to encapsulate both sync and async logic.

Testing Observables is also way easier than testing other async implementations.

With observable-hooks we can create rich reusable Components with ease.

What It Is Not

This library is not for replacing state management tools like Redux but to reduce the need of dumping everything into global state.

Using this library does not mean you have to turn everything observable which is not encouraged. It plays well side by side with other hooks. Use it only on places where it's needed.

At First Glance

import * as React from 'react'
import { useObservableState } from 'observable-hooks'
import { timer } from 'rxjs'
import { switchMap, mapTo, startWith } from 'rxjs/operators'

const App = () => {
  const [isTyping, updateIsTyping] = useObservableState(
    transformTypingStatus,
    false
  )

  return (
    <div>
      <input type="text" onKeyDown={updateIsTyping} />
      <p>{isTyping ? 'Good you are typing.' : 'Why stop typing?'}</p>
    </div>
  )
}

// Logic can be tested like Epic in redux-observable
function transformTypingStatus(event$) {
  return event$.pipe(
    switchMap(() =>
      timer(1000).pipe(
        mapTo(false),
        startWith(true)
      )
    )
  )
}

Installation

yarn

yarn add observable-hooks

npm

npm install --save observable-hooks

Usage

Read the docs at https://observable-hooks.js.org.

Here is how I designed the API. Might give you a perspective on when use what.

mindmap

Examples are in here. Play on CodeSandbox:

Note that there are also some useful utilities for common use cases to reduce garbage collection.

All available APIs can be imported from the entry.

import { ... } from 'observable-hooks'

Overly Simplified Examples

Conditional rendering (with vanilla JavaScript)

With observable-hooks you can have a stream of React elements. This is like React Suspense but armed with the incredible RxJS operators. If you want Suspense instead see use-suspensible.

import { from, of } from 'rxjs'
import { map, switchMap, startWith, catchError } from 'rxjs/operators'
import { useObservableState } from 'observable-hooks'
import { fetchData } from './api'
import { SuccessUI, LoadingUI, ErrorUI } from './components'

export function App() {
  const [status, onFetchData] = useObservableState(
    event$ => event$.pipe(
      // initial fetching
      startWith(),
      // OMG I don't have to deal with race condition
      switchMap(event =>
        from(fetchData(event && event.currentTarget.id)).pipe(
          map(value => <SuccessUI value={value} />),
          startWith(<LoadingUI />)
        )
      ),
      catchError(error => of(<ErrorUI error={error} />))
    )
  )

  return (
    <div>
      <button id="data1" onClick={onFetchData}>fetch</button>
      {status}
    </div>
  )
}

Debounce Text Verification (with vanilla JavaScript)

import React from 'react'
import PropTypes from 'prop-types'
import { withLatestFrom, switchMap, debounceTime, pluck } from 'rxjs/operators'
import { useObservable, useObservableState, pluckFirst } from 'observable-hooks'

const checkText = (text, uuid) =>
  fetch(`https://api/${text}?uuid=${uuid}`)
    .then(response => response.ok)
    .catch(() => false)

export const App = props => {
  // `pluckFirst` is a simple helper function to avoid garbage collection,
  // equivalent to `inputs$ => inputs$.pipe(map(inputs => inputs[0]))`
  const uuid$ = useObservable(pluckFirst, [props.uuid])

  const [isValid, onChange] = useObservableState(
    event$ =>
      event$.pipe(
        // React synthetic event object will be reused.
        // Pluck the value out first.
        pluck('currentTarget', 'value'),
        debounceTime(400),
        withLatestFrom(uuid$),
        switchMap(([text, uuid]) => checkText(text, uuid))
      ),
    false
  )

  return (
    <>
      <input onChange={onChange} />
      <button type="submit" disabled={!isValid}>
        Submit
      </button>
    </>
  )
}

App.propTypes = {
  uuid: PropTypes.string
}

Auto-cancelation (with TypeScript)

import React, { FC, useState } from 'react'
import { timer, empty } from 'rxjs'
import { switchMap, mapTo } from 'rxjs/operators'
import { useObservable, useSubscription } from 'observable-hooks'

const sendBeacon = (beacon: string) => fetch(`https://api?beacon=${beacon}`)

export interface AppProps {
  beacon: string
}

export const App: FC<AppProps> = props => {
  const [shouldSendBeacon, setShouldSendBeacon] = useState(false)

  const beacon$ = useObservable(
    inputs$ =>
      inputs$.pipe(
        // auto-cancelation
        switchMap(([shouldSendBeacon, beacon]) =>
          shouldSendBeacon ? timer(1000).pipe(mapTo(beacon)) : empty()
        )
      ),
    // `as const` is a simple way to make an array tuple.
    // You can also use `as [boolean, string]` or `as [typeof xxx, typeof xxx]`
    [shouldSendBeacon, props.beacon] as const
  )

  useSubscription(beacon$, sendBeacon)

  return (
    <label>
      <input
        type="checkbox"
        checked={shouldSendBeacon}
        onChange={e => setShouldSendBeacon(e.currentTarget.checked)}
      />
      Should Send Beacon
    </label>
  )
}