# little-state-machine

> State management made super simple

Latest version **5.0.1** (published 2025-01-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install little-state-machine
pnpm add little-state-machine
yarn add little-state-machine
bun add little-state-machine
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.1 |
| Published | 2025-01-10 |
| First published | 2019-04-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 41.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1539 |
| Maintainers | bluebill1049 |
| Keywords | state, flux |

## Links

- npm: https://www.npmjs.com/package/little-state-machine
- Repository: https://github.com/bluebill1049/little-state-machine
- Homepage: https://github.com/bluebill1049/little-state-machine#readme
- Issues: https://github.com/bluebill1049/little-state-machine/issues
- npm.io page: https://npm.io/package/little-state-machine

## Alternatives

- [@reckona/mreact-store](https://npm.io/package/@reckona/mreact-store.md) — 976 weekly downloads
- [regular-state](https://npm.io/package/regular-state.md) — 410 weekly downloads
- [@pacote/flux-actions](https://npm.io/package/@pacote/flux-actions.md) — 65 weekly downloads
- [@pilotlab/lux-debug](https://npm.io/package/@pilotlab/lux-debug.md) — 39 weekly downloads
- [vue-persist-state](https://npm.io/package/vue-persist-state.md) — 19 weekly downloads

## Recent versions

- 5.0.1 (latest) — 2025-01-10
- 5.0.0-next.1 (next) — 2025-01-05
- 4.4.1-beta.0 (beta) — 2022-05-29
- 5.0.0 — 2025-01-10
- 5.0.0-next.0 — 2025-01-05
- 4.8.1 — 2024-12-16
- 4.8.0 — 2022-09-23
- 4.7.0 — 2022-09-17
- 4.7.0-next.1 — 2022-09-11
- 4.7.0-next.0 — 2022-09-11
- 4.6.0 — 2022-09-01
- 4.6.0-next.1 — 2022-08-31
- 4.6.0-next.0 — 2022-08-31
- 4.4.1 — 2022-05-29
- 4.4.0 — 2022-05-29
- … 200 more at https://npm.io/package/little-state-machine/versions

## README

<div align="center">
    <h1>📠 Little State Machine</h1>
    
State management made super simple
</div>

<div align="center">

[![npm downloads](https://img.shields.io/npm/dm/little-state-machine.svg?style=for-the-badge)](https://www.npmjs.com/package/little-state-machine)
[![npm](https://img.shields.io/npm/dt/little-state-machine.svg?style=for-the-badge)](https://www.npmjs.com/package/little-state-machine)
[![npm](https://img.shields.io/bundlephobia/minzip/little-state-machine?style=for-the-badge)](https://bundlephobia.com/result?p=little-state-machine)

</div>

<h2>✨ Features</h2>

- Tiny with 0 dependency and simple (715B _gzip_)
- Persist state by default (`sessionStorage` or `localStorage`)
- Fine-tune the performance with partial render and selector

<h2>📦 Installation</h2>

    $ npm install little-state-machine

<h2>🕹 API</h2>

#### 🔗 `createStore`

Function to initialize the global store.

```tsx
function log(store) {
  console.log(store);
  return store;
}

createStore(
  {
    yourDetail: { firstName: '', lastName: '' } // it's an object of your state
  },
  {
     name?: string; // rename the store
     middleWares?: [ log ]; // function to invoke each action
     storageType?: Storage; // session/local storage (default to session)
     persist?: 'action' // onAction is default if not provided
     // when 'none' is used then state is not persisted
     // when 'action' is used then state is saved to the storage after store action is completed
     // when 'beforeUnload' is used then state is saved to storage before page unloa
  },
);
```

#### 🔗 `useStateMachine`

This hook function will return action/actions and the state of the app.

```tsx
const { actions, state, getState } = useStateMachine<T>({
  actions?: Record<string, Function> // Optional action to update global state
  selector?: Function, // Optional selector to isolate re-render based on selected state
});
```

<h2>📖 Example</h2>

Check out the <a href="https://codesandbox.io/p/sandbox/compassionate-forest-ql3f56?workspaceId=ws_4xFLLpCJQLXZtvdkd1DS72">Demo</a>.

```tsx
import { createStore, useStateMachine } from 'little-state-machine';

createStore({
  yourDetail: { name: '' },
});

function updateName(state, payload) {
  return {
    ...state,
    yourDetail: {
      ...state.yourDetail,
      ...payload,
    },
  };
}

function selector(state) {
  return state.yourDetails.name.length > 10;
}

function YourComponent() {
  const { actions, state } = useStateMachine({ actions: { updateName } });

  return (
    <buttton onClick={() => actions.updateName({ name: 'bill' })}>
      {state.yourDetail.name}
    </buttton>
  );
}

function YourComponentSelectorRender() {
  const { state } = useStateMachine({ selector });
  return <p>{state.yourDetail.name]</p>;
}

const App = () => (
  <>
    <YourComponent />
    <YourComponentSelectorRender />
  </>
);
```

## ⌨️ Type Safety (TS)

You can create a `global.d.ts` file to declare your GlobalState's type.

Check out the [example](https://codesandbox.io/s/typescript-forked-xs30h).

```ts
import 'little-state-machine';

declare module 'little-state-machine' {
  interface GlobalState {
    yourDetail: {
      name: string;
    };
  }
}
```

## ⌨️ Migrate to V5

- `StateMachineProvider` has been removed, simple API

```diff
const App = () => (
- <StateMachineProvider>
    <YourComponent />
- <StateMachineProvider>
);
```

- Actions now is an object payload `useStateMachine({ actions: { updateName } })`
- Upgrade react >= 18

## By the makers of BEEKAI

We also make [BEEKAI](https://www.beekai.com/). Build the next-generation forms with modern technology and best in class user experience and accessibility.

<h2>🤝 Contributors</h2>

Thanks go to these wonderful people:

<a href="https://github.com/beekai-oss/little-state-machine/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=beekai-oss/little-state-machine" />
</a>

---
_Source: https://npm.io/package/little-state-machine · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._