Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mutativejs/jotai-mutative
A Mutative extension for Jotai
https://github.com/mutativejs/jotai-mutative
immutability jotai mutative react
Last synced: about 1 month ago
JSON representation
A Mutative extension for Jotai
- Host: GitHub
- URL: https://github.com/mutativejs/jotai-mutative
- Owner: mutativejs
- License: mit
- Created: 2024-09-14T18:25:00.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-11-23T17:25:00.000Z (about 1 month ago)
- Last Synced: 2024-11-23T18:23:50.505Z (about 1 month ago)
- Topics: immutability, jotai, mutative, react
- Language: TypeScript
- Homepage:
- Size: 576 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# jotai-mutative
[](https://www.npmjs.com/package/jotai-mutative)
A [Mutative](https://github.com/unadlib/mutative) extension for Jotai
With the Mutative extension, you can simplify the handling of immutable data in Jotai in a mutable way, allowing you to use immutable state more conveniently.
`jotai-mutative` is more than 10x faster than `jotai-immer`. [Read more about the performance comparison in Mutative](https://mutative.js.org/docs/getting-started/performance).
## Installation
In order to use the Mutative extension in Jotai, you will need to install Mutative and Jotai as a direct dependency.
```bash
npm install jotai mutative jotai-mutative
# Or use any package manager of your choice.
```
## Usage
### atomWithMutative
`atomWithMutative` creates a new atom similar to the regular atom with a different `writeFunction`. In this bundle, we don't have read-only atoms, because the point of these functions is the mutative create(mutability) function. The signature of writeFunction is `(get, set, update: (draft: Draft) => void) => void`.
```tsx
import { useAtom } from 'jotai';
import { atomWithMutative } from 'jotai-mutative';
const countAtom = atomWithMutative({ value: 0 });
const Counter = () => {
const [count] = useAtom(countAtom);
return
count: {count.value};
};
const Controls = () => {
const [, setCount] = useAtom(countAtom);
// setCount === update : (draft: Draft) => void
const inc = () =>
setCount((draft) => {
++draft.value;
});
return +1;
};
```
### withMutative
`withMutative` takes an atom and returns a derived atom, same as `atomWithMutative` it has a different `writeFunction`.
```tsx
import { useAtom, atom } from 'jotai';
import { withMutative } from 'jotai-mutative';
const primitiveAtom = atom({ value: 0 });
const countAtom = withMutative(primitiveAtom);
const Counter = () => {
const [count] = useAtom(countAtom);
return
count: {count.value};
};
const Controls = () => {
const [, setCount] = useAtom(countAtom);
// setCount === update : (draft: Draft) => void
const inc = () =>
setCount((draft) => {
++draft.value;
});
return +1;
};
```
### useMutativeAtom
This hook takes an atom and replaces the atom's `writeFunction` with the new mutative-like `writeFunction` like the previous helpers.
```tsx
import { useAtom } from 'jotai';
import { useMutativeAtom } from 'jotai-mutative';
const primitiveAtom = atom({ value: 0 });
const Counter = () => {
const [count] = useMutativeAtom(primitiveAtom);
return
count: {count.value};
};
const Controls = () => {
const [, setCount] = useMutativeAtom(primitiveAtom);
// setCount === update : (draft: Draft) => void
const inc = () =>
setCount((draft) => {
++draft.value;
});
return +1;
};
```
> It would be better if you don't use `withMutative` and `atomWithMutative` with `useMutativeAtom` because they provide the mutative-like `writeFunction` and we don't need to create a new one.
> You can use `useSetMutativeAtom` if you need only the setter part of `useMutativeAtom`.
### Mutative Options
- [Strict mode](https://mutative.js.org/docs/advanced-guides/strict-mode)
- [Auto Freeze](https://mutative.js.org/docs/advanced-guides/auto-freeze)
- [Marking data structure](https://mutative.js.org/docs/advanced-guides/mark)
## Credits
`jotai-mutative` is inspired by `jotai-immer`.
It uses the same API as `jotai-immer` but uses Mutative under the hood. The repository is based on the `jotai-immer` repository.
## License
`jotai-mutative` is [MIT licensed](https://github.com/mutativejs/jotai-mutative/blob/main/LICENSE).