\n\n[](https://github.com/ellerbrock/typescript-badges/)\n[](https://www.npmjs.com/package/@libre/atom)\n[](https://bundlephobia.com/result?p=@libre/atom)\n[](https://bundlephobia.com/result?p=@libre/atom)\n\n[](https://travis-ci.com/libre-org/atom)\n[](https://codecov.io/gh/libre-org/atom)\n[](https://www.npmjs.com/package/@libre/atom)\n\n[](https://www.npmjs.com/package/@libre/atom)\n[](http://commitizen.github.io/cz-cli/)\n[](https://github.com/semantic-release/semantic-release)\n\n## Description\n\n`@libre/atom` provides a data type called `Atom`s and a few functions for working with `Atom`s. It is heavily inspired by `atom`s in Clojure(Script). While the full power of Clojure `atom`s cannot be experienced in JavaScript's single-threaded runtime, `Atom`s do still offer similar benefits due to the highly asynchronous and event-driven nature of JavaScript.\n\nAtoms provide a predictable way to manage state shared by multiple components of a\nprogram as that state changes over time. They are particularly useful in the functional and reactive programming paradigms, where most components of a program are pure functions operating on immutable data. `Atoms` provide a controlled mechanism for mutability that lets multiple components access and update the same value without risking mutating another component's reference to it in the middle of some process or asynchronous operation.\n\n### Put your state in an `Atom`:\n\n```ts\nimport { Atom } from \"@libre/atom\";\n\nconst appState = Atom.of({\n color: \"blue\",\n userId: 1\n});\n```\n\n### Read state with `deref`\n\nYou can't inspect `Atom` state directly, you have to `deref`erence it, like this:\n\n```js\nimport { deref } from \"@libre/atom\";\n\nconst { color } = deref(appState);\n```\n\n### Update state with `swap`\n\nYou can't modify an `Atom` directly. The main way to update state is with `swap`. Here's its call signature:\n\n```ts\nfunction swap(\n atom: Atom, \n updateFn: (state: DeepImmutable) => S\n): void;\n```\n\n`updateFn` is applied to `atom`'s state and the return value is set as `atom`'s new state. There are just two simple rules for `updateFn`:\n\n1. it must return a value of the same type/interface as the previous state\n2. it must not mutate the previous state\n\nTo illustrate, here is how we might update `appState`'s color:\n\n```js\nimport { swap } from \"@libre/atom\";\n\nconst setColor = color =>\n swap(appState, state => ({\n ...state,\n color: color\n }));\n```\n\n> **Note:** Our `updateFn` is [spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax)ing the old state onto a new object before overriding `color`. This is an easy way to obey the rules of `updateFn`. If manually spreading values seems tedious, there are many libraries that offer convenient functions for operating on JS data structures in an immutable manner, e.g. see [ramda](https://ramdajs.com/), [sanctuary](https://sanctuary.js.org/), [crocks](https://evilsoft.github.io/crocks/docs/), or (for the wizards among us) [fp-ts](https://gcanti.github.io/fp-ts/).\n\n## Installation\n\n**NPM**: `npm install --save @libre/atom`\n\n**Yarn**: `yarn add @libre/atom`\n\n**CDN**: ``\n\n- Exposed on the global object, like so: `window[\"@libre/atom\"]`\n\n## Usage\n\n**ES6 `import`**\n\n```js\nimport { Atom, deref, set, swap } from \"@libre/atom\";\n```\n\n**CommonJS `require`**\n\n```js\nconst { Atom, deref, set, swap } = require(\"@libre/atom\");\n```\n\n**Web `` tag**\n\n```js\nconst { Atom, deref, set, swap } = window[\"@libre/atom\"];\n```\n\n## Documentation\n\n[You can find API docs for `@libre/atom` here](https://libre-org.github.io/atom/)\n\n## Contributing / Feedback\n\nPlease open an issue if you have any questions, suggestions for\nimprovements/features, or want to submit a PR for a bug-fix (please include\ntests if applicable).\n","readmeFilename":"README.md"}
![\"@libre/atom](\"https://document-export.canva.com/DADLRIBWTFM/45/preview/0001-645846858.png\")
![\"@libre/atom](\"https://document-export.canva.com/DADLRIBWTFM/45/preview/0001-645846858.png\"\n)
\n