npm package: @reframework/qx
Description: State manager for React apps
Latest version: 0.1.1

<p align="center">
  <img width="300" src="https://user-images.githubusercontent.com/49458012/210452432-27d09c8a-5cdc-4916-8f4c-4daa3e9125c7.png">
</p>

<p align="center">
  <a href="#about">About</a> •
  <a href="#installation">Installation</a> •
  <a href="#example">Example</a> •
  <a href="#api">Api</a> •
  <a href="#license">License</a>
</p>

## About

The `qx` library is a state container based on queues. It provides a powerful
way to manage the state of your application using a simple and intuitive API.
The library is designed to be easy to use and flexible enough to handle a wide
range of use cases.

One of the main goals of the `qx` library is to provide a way to manage the
state of your application that is easy to reason about and test. The library is
designed to be highly modular, allowing you to use only the parts of the library
that you need. This makes it easy to integrate the library into your existing
codebase and to customize it to meet your specific needs.

[![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](http://forthebadge.com)

## Installation

NPM

```bash
npm install --save @reframework/qx
```

Yarn

```bash
yarn add @reframework/qx
```

## How to use

**Defining a store**

A store is an object that holds the state of your application. You can define
multiple stores using the `makeStore` method. The `makeStore` method takes the
name of store and an initial state object as its arguments and returns a store
object.

```ts
import { makeStore } from '@reframework/qx';

interface CounterState {
  count: number;
}

const store = makeStore<CounterState>({
  count: 0,
});

export const $counter = {
  store,
  // ...
}
```

**Using a store**

The `useStore` hook is used to access the state of a specific store from within
a component. The `useStore` hook takes the store object as its argument and
returns the current state of the store. You can use this state to render your
component and update the UI based on changes to the state.

```ts
import { useStore } from '@reframework/qx';
import $counter from 'counter/store';

const store = useStore($counter.store);
```

<hr/>

**Defining a selector**

A selector is a function that takes the current state of the store as its input
and returns a derived value. Selectors are used to compute derived data from the
state of the store, allowing you to keep your state normalized and avoid
unnecessary recomputations.

```ts
import { makeSelector } from '@reframework/qx';

const count = makeSelector(store, (state) => state.count);

export $counter = {
  // ...
  count,
}
```

**Using selectors**

The `useSelector` hook is used to access the value of a selector from within a
component.

```tsx
import { useSelector } from '@reframework/qx';
import $counter from './counterStore';

const Counter = () => {
  const count = useSelector($counter.count);

  return <div>Count: {count}</div>;
};
```

<hr/>

**Defining methods**

The `makeMethod` function is used to define a method that can be called on a
store object. A method is a function that operates on the state of the store and
can be used to update the state in a predictable and consistent way.

When defining a method using `makeMethod`, it is important to follow the
principles of immutability and purity. This means that the method should not
modify the original state object, but instead should return a new state object
that reflects the updated state of the store.

```ts
import { makeMethod } from '@refamework/qx';

const increment = makeMethod(store, (state) => {
  return {
    ...state,
    count: state.count + 1,
  };
});

const decrement = makeMethod(store, (state) => {
  return {
    ...state,
    count: state.count - 1,
  };
});

export $counter = {
  // ...,
  increment,
  decrement
}
```

**Using methods**

```tsx
import { useSelector } from '@reframework/qx';
import $counter from './counterStore';

const Counter = () => {
  const count = useSelector($counter.count);

  return (
    <div>
      <h1>Count: {count}</h1>
      <button onClick={$counter.increment}>Increment</button>
      <button onClick={$counter.decrement}>Decrement</button>
    </div>
  );
};
```

<hr />

**Full example**

```tsx
// store.ts

import { makeStore, makeSelector, makeMethod } from '@reframework/qx';

interface CounterState {
  count: number;
}

const store = makeStore<CounterState>({
  count: 0,
});

const increment = makeMethod(store, (state) => {
  return {
    ...state,
    count: state.count + 1,
  };
});

const decrement = makeMethod(store, (state) => {
  return {
    ...state,
    count: state.count - 1,
  };
});

const setCount = makeMethod(store, (state, count: number) => {
  return {
    ...state,
    count: count,
  };
});

export const $counter = {
  store,
  count,
  increment,
  decrement,
  setCount,
};
```

```tsx
// Counter.tsx

import { useSelector } from '@reframework/qx';
import $counter from './counterStore';

const Counter = () => {
  const count = useSelector($counter.count);

  return (
    <div>
      <h1>Count: {count}</h1>
      <button onClick={$counter.increment}>Increment</button>
      <button onClick={$counter.decrement}>Decrement</button>
      <button onClick={() => $counter.setCount(Math.random())}>
        Set random
      </button>
    </div>
  );
};
```

**Other api**

- makeEvent,
- useEmit,
- emit,
- getSnapshot,
- setSnapshot,
- getState
- setState

## License

MIT