State ·

:zap: Tiny, simple, and robust technique for defining and acting with local states (for all js environments - node, browser, etc.)

Synopsis

A local state for modules, functions, and other ECs

Motivation

We all love functional programming and the concepts of it. It gives us many clean patterns, which we use in our code regardless of exactly which paradigm is in the base of our codebase. But sometimes, for some reason, we can't keep our code "clean" and have to interact with items that are outside of the current lexical environment

For example:

:x:

1let x = 0;
2let y = 1;
3
4// ...
5function someFn() {
6  // ...
7  x++;
8}
9
10// ...
11function anotherFn() {
12 // ...
13 y = 6;
14 console.log(x);
15}
16
17// ...
18function yetAnotherFn() {
19  // ...
20  y = x + 4;
21  x = null; // 🚶
22}

The example above lacks control over the mutations and consumption, which can lead to unpredictable and unwanted results. It is just an example of real-life usage and there are many similar cases that belong to the same class of the problem

The purpose of this library is to give an opportunity to work with local states in a clear, predictable, trackable, and strict way

:white_check_mark:

1import state from 'state-local';
2
3const [getState, setState] = state.create({ x: 0, y: 1 });
4
5// ...
6function someFn() {
7  // ...
8  setState(state => ({ x: state.x + 1 }));
9}
10
11// ...
12function anotherFn() {
13 // ...
14 setState({ y: 6 });
15 const state = getState();
16 console.log(state);
17}
18
19// ...
20function yetAnotherFn() {
21  // ...
22  setState(state => ({ y: state.x + 4, x: null }));
23}

codesandbox

We also can track the changes in items:

1import state from 'state-local';
2
3const [getState, setState] = state.create({ x: 0, y: 1 }, {
4  x: latestX => console.log('(⌐▀ ̯ʖ▀) Houston we have a problem; "x" has been changed. "x" now is:', latestX),
5  y: latestY => console.log('(⌐▀ ̯ʖ▀) Houston we have a problem; "y" has been changed. "y" now is:', latestY),
6});
7
8// ...

codesandbox

We can use the subset of the state in some execution contexts:

1import state from 'state-local';
2
3const [getState, setState] = state.create({ x: 5, y: 7 });
4
5// ...
6function someFn() {
7  const state = getState(({ x }) => ({ x }));
8
9  console.log(state.x); // 5
10  console.log(state.y); // ❌ undefined - there is no y
11}

codesandbox

And much more...

Documentation

Contents

• Installation
• Usage
  • create
  • initial state
  • handler
  • getState
  • selector
  • setState

Installation

You can install this library as an npm package or download it from the CDN and use it in node or browser:

1npm install state-local

or

1yarn add state-local

or

1<script src="https://unpkg.com/state-local/dist/state-local.js"></script>
2
3<script>
4// now it is available in `window` (window.state)
5const [getState, setState] = state.create({ x: 11, y: 13 });
6// ...
7</script>

create

The default export has a method called create, which is supposed to be a function to create a state:

1import state from 'state-local';
2
3// state.create
4
5// ...

codesandbox

create is a function with two parameters:

1. initial state (required)
2. handler (optional)

initial state

initial state is a base structure and a value for the state. It should be a non-empty object

1import state from 'state-local';
2
3/*
4const [getState, setState] = state.create(); // ❌ error - initial state is required
5const [getState, setState] = state.create(5); // ❌ error - initial state should be an object
6const [getState, setState] = state.create({}); // ❌ error - initial state shouldn\'t be an empty object
7*/
8
9const [getState, setState] = state.create({ isLoading: false, payload: null }); // ✅
10// ...

codesandbox

handler

handler is a second parameter for create function and it is optional. It is going to be a handler for state updates. Hence it can be either a function or an object.

• If the handler is a function than it should be called immediately after every state update (with the latest state)
• If the handler is an object than the keys of that object should be a subset of the state and the values should be called immediately after every update of the corresponding field in the state (with the latest value of the field)

see example below:

if handler is a function

1import state from 'state-local';
2
3const [getState, setState] = state.create({ x: 2, y: 3, z: 5 }, handleStateUpdate /* will be called immediately after every state update */);
4
5function handleStateUpdate(latestState) {
6  console.log('hey state has been updated; the new state is:', latestState); // { x: 7, y: 11, z: 13 }
7}
8
9setState({ x: 7, y: 11, z: 13 });
10// ...

codesandbox

if handler is an object

1import state from 'state-local';
2
3const [getState, setState] = state.create({ x: 2, y: 3, z: 5 }, {
4  x: handleXUpdate, // will be called immediately after every "x" update
5  y: handleYUpdate, // will be called immediately after every "y" update
6  // and we don't want to listen "z" updates 😔
7});
8
9function handleXUpdate(latestX) {
10  console.log('(⌐▀ ̯ʖ▀) Houston we have a problem; "x" has been changed. "x" now is:', latestX); // ... "x" now is 7
11}
12
13function handleYUpdate(latestY) {
14  console.log('(⌐▀ ̯ʖ▀) Houston we have a problem; "y" has been changed. "y" now is:', latestY); // ... "y" now is 11
15}
16
17setState({ x: 7, y: 11, z: 13 });
18// ...

codesandbox

getState

getState is the first element of the pair returned by create function. It will return the current state or the subset of the current state depending on how it was called. It has an optional parameter selector

1import state from "state-local";
2
3const [getState, setState] = state.create({ p1: 509, p2: 521 });
4
5const state = getState();
6console.log(state.p1); // 509
7console.log(state.p2); // 521
8
9// or
10
11const { p1, p2 } = getState();
12console.log(p1); // 509
13console.log(p2); // 521

codesandbox

selector

selector is a function that is supposed to be passed (optional) as an argument to getState. It receives the current state and returns a subset of the state

1import state from 'state-local';
2
3const [getState, setState] = state.create({ p1: 389, p2: 397, p3: 401 });
4
5function someFn() {
6  const state = getState(({ p1, p2 }) => ({ p1, p2 }));
7  console.log(state.p1); // 389
8  console.log(state.p2); // 397
9  console.log(state.p3); // ❌ undefined - there is no p3
10}

codesandbox

setState

setState is the second element of the pair returned by create function. It is going to receive an object as a change for the state. The change object will be shallow merged with the current state and the result will be the next state

NOTE: the change object can't contain a field that is not specified in the "initial" state

1import state from 'state-local';
2
3const [getState, setState] = state.create({ x:0, y: 0 });
4
5setState({ z: 'some value' }); // ❌ error - it seams you want to change a field in the state which is not specified in the "initial" state
6
7setState({ x: 11 }); // ✅ ok
8setState({ y: 1 }); // ✅ ok
9setState({ x: -11, y: 11 }); // ✅ ok

codesandbox

setState also can receive a function which will be called with the current state and it is supposed to return the change object

1import state from 'state-local';
2
3const [getState, setState] = state.create({ x:0, y: 0 });
4
5setState(state => ({ x: state.x + 2 })); // ✅ ok
6setState(state => ({ x: state.x - 11, y: state.y + 11 })); // ✅ ok
7
8setState(state => ({ z: 'some value' })); // ❌ error - it seams you want to change a field in the state which is not specified in the "initial" state

codesandbox

License

MIT