# @m1st1ck/atomjs

> Flexible state management

Latest version **1.0.1** (published 2023-02-18) · ISC license · 0 weekly downloads

## Install

```sh
npm install @m1st1ck/atomjs
pnpm add @m1st1ck/atomjs
yarn add @m1st1ck/atomjs
bun add @m1st1ck/atomjs
```

## Health

**Score 30/100 (F)** — status: abandoned.

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

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2023-02-18 |
| First published | 2023-02-17 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 21.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | m1st1ck |
| Maintainers | m1st1ck |
| Keywords | state, atom, atomjs |

## Links

- npm: https://www.npmjs.com/package/@m1st1ck/atomjs
- Repository: https://github.com/m1st1ck/atomjs
- Homepage: https://github.com/m1st1ck/atomjs#readme
- Issues: https://github.com/m1st1ck/atomjs/issues
- npm.io page: https://npm.io/package/@m1st1ck/atomjs

## 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

- 1.0.1 (latest) — 2023-02-18
- 1.0.0 — 2023-02-17

## README

# AtomJS

Flexible state management

## Atoms

### atom\<T\>(state: T): Atom\<T\>

```javascript
import { atom } from "atomjs";

// create new atom
const countAtom = atom(0);
// change state - there is no equality check and all subscribers will be notified
countAtom.setState(2);
// change state with callback function
countAtom.setState((previousCount) => previousCount + 1);

const userAtom = atom({ name: "Stad", age: 2 });
// updating objects will merge with previous state
userAtom.setState({ age: 3 }); // { name: "Stad", age: 3 }
// update function needs to return the whole object
userAtom.setState((prevState) => ({
  ...prevState,
  age: 4,
}));
// get state
const count = countAtom.getState(); // count === 3
// listen for state updates - triggered on every atom.setState
const unsubscribe = countAtom.subscribe(() => {
  // do something with new state
  const count = countAtom.getState();
});
// stop listening for changes
unsubscribe();
// reset to default state
countAtom.reset();
```

### asyncAtom\<T\>(state: T): Atom\<T\>

contains an additional async state

```javascript
{
  init: true,
  loading: false,
  loaded: false,
  error: false,
  errorMessage: undefined,
}
```

it provides addition functionallities to manage both states

```javascript
import { asyncAtom } from "atomjs";

// create new async atom
const countAtom = asyncAtom(0);
// getState returns a tuple both states
const [count, asyncState] = countAtom.getState();
// get atom state only
const count = countAtom.getCoreState();
// get async state only
const asyncState = countAtom.getAsyncState();
// update async state - will override previus state
countAtom.setAsyncState({ loading: true }); // { loading: true, init: false, error: false, ... }
// update async state using enum - init, loading, loaded, error
countAtom.setAsyncState("loading"); // { loading: true, init: false, error: false, ... }
// update both state
countAtom.setAsyncState({ loaded: true }, 4); // count === 4
// handle errors
countAtom.setAsyncState({ error: true, errorMessage: "..." });
// reset - will reset both state and asyncState
countAtom.reset(); // ({ init: true, loading: false, ... })
// you can also provide asyncState to reset to
countAtom.reset({ loaded: true }); // ({ init: false, loaded: true, ... })
```

## Utils

### waitForAtom\<T\>(atom: ObservableAtom\<T\>, selector: (atomState: T) => boolean): Promise\<void\>

```javascript
import { asyncAtom, waitForAtom } from "atomjs";

const userAtom = asyncAtom({ name: undefined });

const fetchUser = async () => {
  const { loading } = userAtom.getAsyncState();

  // don't fetch if already fetching
  if (loading) {
    // wait for original fetch to finish
    await waitForAtom(userAtom, ([, { loaded }]) => loaded);
    // return fetch data
    return userAtom.getCoreState();
  }

  // Fetch user... and update atom
  userAtom.setAsyncState({ loaded: true }, user);
};
```

### waitForAtoms<T extends ObservableAtom\<any>\[]>(atoms: readonly [...T], selector: (atomState: IterateAtomsIteratable\<T\>) => boolean): Promise\<void\>

```javascript
import { waitForAtoms } from "atomjs";

waitForAtoms(
  [atom1, atom2],
  ([[atom1Data, atom1AsyncStatus], [atom2Data, atom2AsyncStatus]]) =>
    atom1AsyncStatus.loaded || atom1AsyncStatus.loaded
).then(() => {});
```

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