Temper ·

Table of contents

• Getting Started
  • Create React App
  • Installation
  • withTemper
  • Traits
  • Selectors
  • Nested Traits
  • Wrapping things up
• API Documentation
• Licence

Getting Started

This readme is meant to get you familiar with the Temper way of doing things. If you're looking for something specific, please visit the documentation site. If you're just starting out with Temper, read on!

For the purpose of this guide, we'll create a simple counter that prints You've reached the target! when you get to the value of 5.

Create React App

Temper is a state management library for React, so you need to have React installed and running to use Temper. The easiest and recommended way for bootstrapping a React application is to use Create React App:

npx create-react-app my-app

npx is a package runner tool that comes with npm 5.2+ and higher, see instructions for older npm versions.

For more ways to install Create React App, see the official documentation.

Installation

Using npm:

npm install temperjs

Using yarn:

yarn add temperjs

withTemper

If you want to use Temper states, you need to wrap your component (preferably the root component) with the hoc withTemper.

import React from 'react';
import { withTemper } from 'temperjs';

function App() {
  return <Counter />
}

export default withTemper(App);

We'll implement the Counter component in the following section.

Traits

Temper states are called Traits. Traits are globally shared units of state that components can subscribe to. Traits can be read and written from any component in the application tree. Subscribed components will rerender everytime the Trait value changes.

If you want to set a Trait, use can use the action setTrait:

import React from 'react';
import { withTemper, setTrait } from 'temperjs';

function App() {
  setTrait('count', 0);
  return <Counter />
}

export default withTemper(App);

If you need to read from and write to a Trait, you can use the hook useTrait:

import React from 'react';
import { useTrait } from 'temperjs';

function Counter() {
  const [count, setCount] = useTrait('count');

  function incrementCounter() {
    setCount(({ value }) => value + 1);
  }
  function decrementCounter() {
    setCount(({ value }) => value - 1);
  }

  return (
    <div>
      <p>{count}</p>
      <button onClick={incrementCounter}>Increment</button>
      <button onClick={decrementCounter}>Decrement</button>
    </div>
  );
}

export default Counter;

Selectors

Selectors are derived Traits. You can think of selectors as the output of passing a state to a pure function that executes some logic based on that state.

If you want to create a selector, you can use the following syntax:

import React from 'react';
import { withTemper, setTrait } from 'temperjs';

function App() {
  // This is a simple Trait
  setTrait('count', 0);
  // This is a selector Trait
  setTrait('isTargetReached', ({ get }) => get('count') >= 5);

  return <Counter />
}

export default withTemper(App);

⚠️ CAUTION:

Selectors permanently depend on their reference Trait. When the reference Trait changes, the selector value is updated automatically.

Therefore, you cannot manually update selectors once set, since their value tightly depends on their base Trait.

Nested Traits

Temper encourages you to wrap related Traits in a single object. When a Trait is an object, each attribute will become a new Trait that is individually updatable and subscribable:

import React from 'react';
import { withTemper, setTrait } from 'temperjs';

function App() {
  setTrait('counter', {
    count: 0,
    isTargetReached: ({ get }) => get('counter.count') >= 5
  });

  return <Counter />
}

export default withTemper(App);

If you just need to read a Trait, you can use the hook useTraitValue (nested Traits are referenced with the dot notation.):

import React from 'react';
import { useTrait, useTraitValue } from 'temperjs';

function Counter() {
  const [count, setCount] = useTrait('counter.count');
  const isTargetReached = useTraitValue('counter.isTargetReached');

  function incrementCounter() {
    setCount(({ value }) => value + 1);
  }
  function decrementCounter() {
    setCount(({ value }) => value - 1);
  }

  return (
    <div>
      <p>{count} { isTargetReached && (<span>You've reached the target!</span>)}</p>
      <button onClick={incrementCounter}>Increment</button>
      <button onClick={decrementCounter}>Decrement</button>
    </div>
  );
}

export default Counter;

Wrapping things up

Run the Counter on CodeSandbox.

API Documentation

Have a look at the documentation site for more details on Temper.

Licence

MIT