\n\n> Oh my, your store is in a right\n> [two and eight](https://cockneyrhymingslang.co.uk/slang/two_and_eight/).\n\nA lightweight JavaScript / TypeScript state management library that uses a class-based store.\n\nKey features include:\n\n- Action/event based state flow (like Redux or Zustand).\n- Reset entire state or specific fields.\n- Type-safe state management.\n- Minimal boilerplate.\n- 730 bytes, minified and gzipped.\n\n```tsx\nimport { TwoAndEight, createReactStore } from '2n8'\n\nclass Store extends TwoAndEight {\n count = 0\n\n // Make sure to use arrow-functions to bind `this`.\n addClicked = () => {\n this.count++\n }\n\n resetClicked = () => {\n this.$reset('count')\n }\n}\n\nconst useStore = createReactStore(new Store())\n\nconst Counter = () => {\n const count = useStore('count')\n const addClicked = useStore('addClicked')\n const resetClicked = useStore('resetClicked')\n return (\n
\n {count}\n \n \n
\n )\n}\n```\n\n## Getting Started\n\n### Installation\n\n```sh\nnpm i 2n8\nyarn add 2n8\npnpm add 2n8\nbun add 2n8\n```\n\n### Create a store\n\nYour store is a class, and turning it into a React hook is as easy as passing it to the\n`createReactStore` utility.\n\n```ts\n// store.ts\nimport { TwoAndEight, createReactStore } from '2n8'\n\nclass Store extends TwoAndEight {\n expression: '🫤' | '🥸' = '🫤'\n\n addDisguise = () => {\n this.expression = '🥸'\n }\n\n resetToConfusion = () => {\n this.$reset('expression')\n }\n}\n\nexport const useStore = createReactStore(new Store())\n```\n\n### Import the hook into your React components\n\nThe hook provides a direct connection to your store. When you modify the state, the consuming\ncomponent automatically re-renders to reflect those changes.\n\n```tsx\n// Expression.tsx\nimport { useStore } from './store'\n\nfunction Expression() {\n const expression = useStore('expression')\n return
{expression}
\n}\n```\n\n```tsx\n// App.tsx\nimport { useStore } from './store'\n\nfunction App() {\n const addDisguise = useStore('addDisguise')\n const resetToConfusion = useStore('resetToConfusion')\n return (\n <>\n \n \n \n )\n}\n```\n\n## State and Actions\n\n_State_ is initiated using class fields. The class must be extended from 2n8's parent class which\nenhances the store with a few utilities.\n\n```tsx\n// store.ts\nimport { TwoAndEight } from '2n8'\n\nclass Store extends TwoAndEight {\n counter = 0\n}\n```\n\nState changes are made inside _actions_, which are simply class methods that mutate the fields.\n\n```tsx\n// store.ts\nclass Store extends TwoAndEight {\n counter = 0\n\n addButtonClicked = () => {\n this.counter++\n }\n}\n```\n\n> [!WARNING] \n> The class methods must use arrow functions in order to bind the store's `this` to the action,\n> allowing you to access your state and actions.\n\nGenerate your React hook:\n\n```tsx\n// store.ts\nexport const useStore = createReactStore(new Store())\n```\n\nThis uses React's [`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore)\nhook to _subscribe_ to state changes:\n\n```tsx\n// Component.tsx\nimport { useStore } from './store'\n\nconst Component = () => {\n const counter = useStore('counter')\n\n return
{counter}
\n}\n```\n\nWhen, and only when, the selected state changes, the component is rerendered by React. This is more\noptimal than simply passing state down the component tree via props.\n\nSelect and call actions from the store:\n\n```tsx\n// Component2.tsx\nimport { useStore } from './store'\n\nconst Component2 = () => {\n const addButtonClicked = useStore('addButtonClicked')\n\n return \n}\n```\n\nWhen actions are called, the current values of all state are _emitted_ to the subscribers at the end\nof the action.\n\n## Async Actions\n\nRunning asynchronous actions is as simple as making an async method on your store class.\n\n```tsx\n// store.ts\nimport { TwoAndEight } from '2n8'\n\nimport { fetchData } from './data-fetcher'\n\nclass Store extends TwoAndEight {\n data: { id: string; name: string }[] = []\n\n loadDataButtonClicked = async () => {\n this.data = await fetchData()\n }\n}\n```\n\nAs state is only emitted at the **end** of actions, you may find you'd like to emit earlier to\ntrigger state changes in your app. For this you can use the special `$emit` action.\n\n```tsx\n// store.ts\nimport { TwoAndEight } from '2n8'\n\nimport { fetchData } from './data-fetcher'\n\nclass Store extends TwoAndEight {\n data: { id: string; name: string }[] = []\n status: 'idle' | 'pending' = 'idle'\n\n loadDataButtonClicked = async () => {\n this.status = 'pending'\n this.$emit()\n this.data = await fetchData()\n this.status = 'idle'\n }\n}\n```\n\n> [!WARNING] \n> All state currently set within the store will be emitted when you call the `$emit` action. This\n> includes changes made by other actions in this time.\n\n## Derived State\n\nState values based on one or more other state values, known as derived state, can be created using\n_getters_.\n\n```tsx\n// store.ts\nimport { TwoAndEight } from '2n8'\n\nclass Store extends TwoAndEight {\n counter = 0\n secondCounter = 10\n\n // Getters do not use arrow functions.\n get totalCounters() {\n return this.counter + this.secondCounter\n }\n}\n\nexport const useStore = createReactStore(new Store())\n```\n\nAny subscribers to `totalCounters` will update when either `counter` or `secondCounter` are updated.\n\n```tsx\n// Component.tsx\nimport { useStore } from './store'\n\nconst Component = () => {\n const totalCounters = useStore('totalCounters')\n\n return
{totalCounters}
\n}\n```\n\n## Reset State\n\nIf you need to reset a state value to its initial value, you can call the special `$reset` action.\n\n```tsx\n// store.ts\nimport { TwoAndEight } from '2n8'\n\nclass Store extends TwoAndEight {\n counter = 0\n\n addButtonClicked = () => {\n this.counter++\n }\n\n resetButtonClicked = () => {\n this.$reset('counter')\n }\n}\n\nexport const useStore = createReactStore(new Store())\n```\n\n```tsx\n// Component.tsx\nimport { useStore } from './store'\n\nconst Component = () => {\n const counter = useStore('counter')\n const addButtonClicked = useStore('addButtonClicked')\n const resetButtonClicked = useStore('resetButtonClicked')\n\n return (\n
\n
{counter}
\n \n \n
\n )\n}\n```\n\nIn the above example, clicking `Add` will update the displayed `counter` to `1`. Clicking `Reset`\nwill put the `counter` back to `0`.\n\n> [!TIP] \n> You can call `$reset()` without a field parameter to reset _all_ state in the store.\n\n## Nested Actions\n\nBeginning an action name with a `$` will mean it won't emit subscription announcements at the end of\nthe action. This can be useful if you wish to use actions from other actions.\n\n```tsx\n// store.ts\nimport { TwoAndEight } from '2n8'\n\nclass Store extends TwoAndEight {\n counter = 0\n face: '🫤' | '🥸' = '🫤'\n\n $repeatedAction = () => {\n this.counter++\n // Will not emit when called but state will change.\n }\n\n action1 = (arg: boolean) => {\n if (arg) {\n this.$repeatedAction()\n }\n this.face = '🥸'\n }\n\n action2 = (arg: boolean) => {\n if (!arg) {\n this.$repeatedAction()\n }\n this.face = '🫤'\n }\n}\n\nexport const useStore = createReactStore(new Store())\n```\n\n> [!NOTE] \n> `$` prefixed actions are not available to select from `useStore`, this is because these should be\n> called from other public actions.\n\n## Comparison\n\n2n8 feels like a blend between two excellent state management libraries:\n[Zustand](https://zustand.docs.pmnd.rs/) and [MobX](https://mobx.js.org/). Therefore, here's a quick\ncomparison with those two packages.\n\n> [!IMPORTANT] \n> There are always compromises. 2n8 aims for simplicity when setting up your store code using\n> TypeScript, but the other two libraries mentioned here are far more mature and have a great\n> ecosystem and community. Please use the tool that best suits your use case.\n\n### Boilerplate\n\nThe main reason for creating 2n8 was to limit the amount of boilerplate and repetition required to\nmake a store when using TypeScript. Here's a simple counter example:\n\n#### 2n8\n\n```tsx\nimport { TwoAndEight, createReactStore } from '2n8'\n\nclass Store extends TwoAndEight {\n count = 0\n\n addClicked = () => {\n this.count++\n }\n\n resetClicked = () => {\n this.$reset('count')\n }\n}\n\nconst useStore = createReactStore(new Store())\n\nconst Counter = () => {\n const count = useStore('count')\n const addClicked = useStore('addClicked')\n const resetClicked = useStore('resetClicked')\n return (\n
\n )\n}\n```\n\n#### Mobx\n\n```tsx\nimport { observer } from 'mobx-react-lite'\nimport { makeAutoObservable } from 'mobx'\n\ntype State = {\n count: number\n}\n\nconst initialState: State = {\n count: 0,\n}\n\nclass Store {\n count = initialState.count\n\n constructor() {\n makeAutoObservable(this)\n }\n\n addClicked() {\n this.count++\n }\n\n resetClicked() {\n this.count = initialState.count\n }\n}\n\nconst store = new Store()\n\nconst Counter = observer(() => {\n return (\n
\n {store.count}\n \n \n
\n )\n})\n```\n\nIn this example, 2n8 requires the least store boilerplate whereas MobX needs less component binding.\n\nThe advantage of 2n8's concise store implementation is that it doesn't require external type\ndefinitions or an initial state object. TypeScript can infer types inside the class too; take\nanother look at the 2n8 example, there's no types in sight, but this store automatically has the\ncorrect types for both state and actions.\n\n### Features\n\n| | 2n8 | Zustand | MobX |\n| ----------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------- |\n| When do subscribers run? | After action (or on manual emit). | After set state. | At the end of actions. |\n| What equality checks are made on state changes? | Deep equality check is built-in. | Uses `Object.is` by default for equality, and shallow or deep equality checking must be manually added. | Deep changes are observed. |\n| How do components connect to state and actions? | Hooks. | Hooks. | Observer wrapper function. |\n\n### Bundle size\n\nPlease note that\n[8.46 kB (3.26 kB)](https://bundlejs.com/?q=react%4019.1.0&treeshake=%5B%7BuseSyncExternalStore%7D%5D)\nof the below values are React.\n\n| | Bundle size | GZipped | Notes |\n| ------------------------- | ----------- | ------- | -------------------------------------------------------------------------- |\n| [2n8][2n8-bundle] | 11.2 kB | 4.22 kB | |\n| [Zustand][zustand-bundle] | 17.4 kB | 6.53 kB | Includes `useShallow` hook and `immer` middleware to match feature parity. |\n| [MobX][mobx-bundle] | 74.9 kB | 21.9 kB | |\n\n[2n8-bundle]:\n https://bundlejs.com/?q=2n8%400.19.4&treeshake=%5B%7BTwoAndEight%2CcreateReactStore%7D%5D\n[zustand-bundle]:\n https://bundlejs.com/?q=zustand%405.0.3%2Czustand%405.0.3%2Freact%2Fshallow%2Czustand%2Fmiddleware%2Fimmer&treeshake=%5B%7B+create+%7D%5D%2C%5B%7B+useShallow+%7D%5D%2C%5B%7B+immer+%7D%5D\n[mobx-bundle]:\n https://bundlejs.com/?q=mobx%406.13.5%2Cmobx-react-lite%404.1.0&treeshake=%5B%7BmakeAutoObservable%7D%5D%2C%5B%7Bobserver%7D%5D\n\n### Benchmarks\n\nHere's a benchmark for the libraries running in React on an Apple MacBook Air M2. It shows that the\nlibraries all display very similar performance.\n\nRun 1:\n\n```\n✓ src/react.bench.tsx > simple count 1874ms\n name hz min max mean p75 p99 p995 p999 rme samples\n · 2n8 75.8525 11.6857 14.8863 13.1835 13.6438 14.8863 14.8863 14.8863 ±1.87% 38 fastest\n · mobx 74.2115 11.6380 18.4382 13.4750 13.6820 18.4382 18.4382 18.4382 ±3.23% 38\n · zustand 72.6212 11.7150 19.2436 13.7701 14.7164 19.2436 19.2436 19.2436 ±3.85% 37 slowest\n\nBENCH Summary\n\n2n8 - src/react.bench.tsx > simple count\n 1.02x faster than mobx\n 1.04x faster than zustand\n```\n\nRun 2:\n\n```\n✓ src/react.bench.tsx > simple count 1881ms\n name hz min max mean p75 p99 p995 p999 rme samples\n · 2n8 75.1111 11.7725 17.8066 13.3136 13.6982 17.8066 17.8066 17.8066 ±2.45% 38 fastest\n · mobx 72.5903 11.9117 17.1061 13.7759 14.4564 17.1061 17.1061 17.1061 ±3.28% 37 slowest\n · zustand 74.0253 11.5298 16.7901 13.5089 14.3196 16.7901 16.7901 16.7901 ±2.92% 38\n\nBENCH Summary\n\n2n8 - src/react.bench.tsx > simple count\n 1.01x faster than zustand\n 1.03x faster than mobx\n```\n\nRun 3:\n\n```\n✓ src/react.bench.tsx > simple count 1890ms\n name hz min max mean p75 p99 p995 p999 rme samples\n · 2n8 74.5884 11.6642 16.5621 13.4069 13.6273 16.5621 16.5621 16.5621 ±1.81% 38\n · mobx 73.2655 11.6450 16.9816 13.6490 14.1171 16.9816 16.9816 16.9816 ±3.48% 37 slowest\n · zustand 74.8296 11.3695 16.7610 13.3637 14.3461 16.7610 16.7610 16.7610 ±3.23% 38 fastest\n\nBENCH Summary\n\nzustand - src/react.bench.tsx > simple count\n 1.00x faster than 2n8\n 1.02x faster than mobx\n```\n\n## API\n\n### `TwoAndEight`\n\nThe abstract class that all stores must extend if you would like to use the following utility\nmethods.\n\n```ts\nclass Store extends TwoAndEight {\n // ...\n}\n```\n\n#### Fields\n\nCustom fields are your state, and should only be mutated in your actions.\n\n#### Methods\n\nCustom methods are your actions, and should be used to mutate state.\n\nThere are also some in-built actions. All in-built actions will always be prefixed with a `$` to\navoid clashing with your own action names.\n\n##### `$emit`\n\n```ts\n$emit(): void\n```\n\nEmit to subscribers early instead of waiting until the end of the action. This is useful in\nasynchronous actions where you may want subscribers to update before the async event has finished.\n\n```ts\nclass Store extends TwoAndEight {\n isFetching = false\n\n actionName = async () => {\n this.isFetching = true\n this.$emit()\n await fetchThing()\n this.isFetching = false\n }\n}\n```\n\n##### `$reset`\n\n```ts\n$reset(stateName?: string): void\n```\n\nCall this to reset the state to its original value. Use a state name to reset a single field of\nstate, or call it without any arguments to reset _all_ state to their original values.\n\n```ts\nthis.$reset()\nthis.$reset('stateName')\n```\n\n```ts\nclass Store extends TwoAndEight {\n counter = 0\n\n resetCounter = () => {\n this.$reset('counter')\n }\n\n resetAll = () => {\n this.$reset()\n }\n}\n```\n\n### `createReactStore`\n\n```ts\ncreateReactStore(store: Store extends TwoAndEight): useStore\n```\n\nEnhances a store instance, returning a React Hook with API utilities attached. This should only be\ncalled _outside_ of components.\n\n```ts\nconst useStore = createReactStore(new Store())\n\nconst Component = () => {\n const actionName = useStore('actionName')\n const stateName = useStore('stateName')\n // ...\n}\n```\n\n#### `useStore.get`\n\n```ts\nuseStore.get(key: Key): Store[Key]\n```\n\nGet any state field, derived state, or action of your store, useful in subscribers where hooks are\nnot available.\n\n#### `useStore.subscribe`\n\n```ts\nuseStore.subscribe(field: Field, callback: () => void): () => void\n```\n\nSubscribes to state updates for a particular state field or derived state; registers a callback that\nfires whenever an action emits that affects the chosen field.\n\n```ts\nuseStore.subscribe('counter', () => {\n writeCounterToFile(useStore.get('counter'))\n})\n```\n\n### `createStore`\n\n```ts\ncreateStore(store: Store extends TwoAndEight): store\n```\n\nThis is the vanilla store creator used by `createReactStore`. You should only need this if you are\ncreating other, non-React, integrations with a 2n8 store.\n\n#### `store.get`\n\n```ts\nuseStore.get(key: Key): Store[Key]\n```\n\nGet any state field, derived state, or action of your store, useful in subscribers where hooks are\nnot available.\n\n#### `store.subscribe`\n\n```ts\nstore.subscribe(field: Field, callback: () => void): () => void\n```\n\nSubscribes to state updates; registers a callback that fires whenever an action emits and the\nselected state field or derived state is changed.\n\n### Types\n\n#### `Keys`\n\n```ts\ntype T = Keys\n```\n\nGiven your `Store` class, this will extract all state field names, derived state name, and action\nnames.\n\ne.g.\n\n```ts\nclass Store extends TwoAndEight {\n count = 0\n\n get countPlusOne() {\n return this.count + 1\n }\n\n increment = () => {\n this.count++\n }\n\n $noEmitAction = () => {\n this.count++\n }\n}\n\ntype T = Keys\n// \"count\" | \"countPlusOne\" | \"increment\"\n```\n\n#### `State`\n\n```ts\ntype T = State\n```\n\nGiven your `Store`, this will extract the type of your state object.\n\ne.g.\n\n```ts\nclass Store extends TwoAndEight {\n count = 0\n\n get countPlusOne() {\n return this.count + 1\n }\n\n increment = () => {\n this.count++\n }\n\n $noEmitAction = () => {\n this.count++\n }\n}\n\ntype T = State\n// {\n// count: number;\n// }\n```\n","readmeFilename":"README.md"}
![\"tings\"](\"https://raw.githubusercontent.com/will-stone/2n8/main/media/logo.png\"){kind=logo}
\n