recontextual v0.2.0

Recontextual: simple, easy-to-type, selectable contexts

This is a library built upon use-context-selector.

It has a simpler API and is easier to type and select from.

Install

Simply install the package:

npm install --save recontextual

Example

import * as React from 'react';
import recontextualize from '../.';

interface IExample {
  value: string;
  setValue: (newValue: string) => void;
}

const [ExampleProvider, useExample] = recontextualize<IExample>();

function FirstComponent() {
  const { value, setValue } = useExample(
    ({ value, setValue }) => ({ value, setValue }),
    true
  );
  return <input value={value} onChange={evt => setValue(evt.target.value)} />;
}
function SecondComponent() {
  const value = useExample(({ value }) => value);
  return <h1>Second, value is: {value}</h1>;
}

function App() {
  const [value, set] = React.useState('initial');
  const contextValue = {
    value,
    setValue: (newValue: string) => set(newValue),
  };
  return (
    <ExampleProvider value={contextValue}>
      <FirstComponent />
      <SecondComponent />
    </ExampleProvider>
  );
}

export default App;

API Reference

recontextualize

function recontextualize<IType>(): [Provider<IType>, Selector<IType>];

recontextualize is the default export and takes no arguments, but should be given a type argument.

The function returns an array of two items: A context provider, and a context selector hook.

The returned context provider can be used as any other context provider, by supplying a value property that conforms to the type argument. Components consuming the context must be wrapped in a provider, or they will throw a runtime error. No default value can be set.

The returned context selector hook can be invoked with 0, 1, or 2 arguments and returns the whole context or a selection from the context. However, if the context has changed, but the selection from the context has not, the hook will not cause a component render but rather abort the render loop.

As an example, imagine we have this:

interface ISomething { ... };
const [SomethingProvider, useSomething] = recontextualize<ISomething>();

This context selector hook, useSomething has the following three call signatures:

function useSomething(): ISomething;
function useSomething<U>(selector: (ctx: ISomething) => U): U;
function useSomething<U>(selector: (ctx: ISomething) => U, isMulti: boolean): U;

If useSomething is invoked without arguments, the hook returns the nearest provided context value as-is. Use this variant to select the entire context.

If useSomething is invoked with a single selector argument or with a selector argument and isMulti=false, the hook returns the value returned by the selector argument, but only if the value has changed using strict equality. If the selector return value is unchanged, this hook aborts the component render (as long as this is the only changed hook of course). Use this variant to select a single value from the context.

If useSomething is invoked with a selector argument and isMulti=true, the hook returns the object returned by the selector argument only if the object has changed using shallow equality on the values of the object. If the selector return value is shallowly unchanged, this hook aborts the component render (as long as this is the only changed hook of course). Use this variant to select multiple values from the context.