Marcisbee
State manager for deeply nested states. Includes integration for React, Preact, Vue, Svelte, Solid, Lit, Rxjs, Angular & No framework. Can be easily used in microfrontends architecture.
Features
- 📦 Small: Just 1 KB minizipped
- 🚀 Fast: Uses no diffing of state changes see benchmarks
- 😍 Simple: Uses classes as state, methods as actions
- 🛡 Typed: Written in strict TypeScript
- 🔭 Devtools: Redux devtools integration
- 💨 Zero dependencies
// store/counter.ts
import { Exome } from "exome"
export class Counter extends Exome {
public count = 0
public increment() {
this.count += 1
}
}
export const counter = new Counter()// components/counter.tsx
import { useStore } from "exome/react"
import { counter } from "../stores/counter.ts"
export default function App() {
const { count, increment } = useStore(counter)
return (
<h1 onClick={increment}>{count}</h1>
)
}Table of contents
- Core concepts
- Usage
- Integration
- Redux devtools
- API
- FAQ
- Benchmarks
- Motivation
Installation
To install the stable version:
npm install --save exomeThis assumes you are using npm as your package manager.
Core concepts
Any piece of state you have, must use a class that extends Exome.
Stores
Store can be a single class or multiple ones. I'd suggest keeping stores small, in terms of property sizes.
State values
Remember that this is quite a regular class (with some behind the scenes logic). So you can write you data inside properties however you'd like. Properties can be public, private, object, arrays, getters, setters, static etc.
Actions
Every method in class is considered as an action. They are only for changing state. Whenever any method is called in Exome it triggers update to middleware and updates view components. Actions can be regular methods or even async ones.
If you want to get something from state via method, use getters.
Usage
Library can be used without typescript, but I mostly recommend using it with typescript as it will guide you through what can and cannot be done as there are no checks without it and can lead to quite nasty bugs.
To create a typed store just create new class with a name of your choosing by extending Exome class exported from exome library.
import { Exome } from "exome"
// We'll have a store called "CounterStore"
class CounterStore extends Exome {
// Lets set up one property "count" with default value "0"
public count = 0
// Now lets create action that will update "count" value
public increment() {
this.count += 1
}
}That is the basic structure of simple store. It can have as many properties as you'd like. There are no restrictions.
Now we should create an instance of CounterStore to use it.
const counter = new CounterStore()Nice! Now we can start using counter state.
Integration
React
Use useStore() from exome/react to get store value and re-render component on store change.
import { useStore } from "exome/react"
import { counter } from "../stores/counter.ts"
export function Example() {
const { count, increment } = useStore(counter)
return <button onClick={increment}>{count}</button>
}Preact
Use useStore() from exome/preact to get store value and re-render component on store change.
import { useStore } from "exome/preact"
import { counter } from "../stores/counter.ts"
export function Example() {
const { count, increment } = useStore(counter)
return <button onClick={increment}>{count}</button>
}Vue
Use useStore() from exome/vue to get store value and re-render component on store change.
<script lang="ts" setup>
import { useStore } from "exome/vue";
import { counter } from "./store/counter.ts";
const { count, increment } = useStore(counter);
</script>
<template>
<button @click="increment()">{{ count }}</button>
</template>Svelte
Use useStore() from exome/svelte to get store value and re-render component on store change.
<script>
import { useStore } from "exome/svelte"
import { counter } from "./store/counter.js"
const { increment } = counter
const count = useStore(counter, s => s.count)
</script>
<main>
<button on:click={increment}>{$count}</button>
</main>Solid
Use useStore() from exome/solid to get store value and update signal selector on store change.
import { useStore } from "exome/solid"
import { counter } from "../stores/counter.ts"
export function Example() {
const count = useStore(counter, s => s.count)
return <button onClick={counter.increment}>{count}</button>
}Lit
Use StoreController from exome/lit to get store value and re-render component on store change.
import { StoreController } from "exome/lit"
import { counter } from "./store/counter.js"
@customElement("counter")
class extends LitElement {
private counter = new StoreController(this, counter);
render() {
const { count, increment } = this.counter.store;
return html`
<h1 @click=${increment}>${count}</h1>
`;
}
}Rxjs
Use observableFromExome from exome/rxjs to get store value as Observable and trigger it when it changes.
import { observableFromExome } from "exome/rxjs"
import { counter } from "./store/counter.js"
observableFromExome(countStore)
.pipe(
map(({ count }) => count),
distinctUntilChanged()
)
.subscribe((value) => {
console.log("Count changed to", value);
});
setInterval(counter.increment, 1000);Angular
signals (>=16)
Use useStore from exome/angular to get store value and update signal selector on store change.
import { useStore } from "exome/angular"
import { counter } from "./store/counter.ts"
@Component({
selector: 'my-app',
template: `
<h1 (click)="increment()">
{{count}}
</h1>
`,
})
export class App {
public count = useStore(counter, (s) => s.count);
public increment() {
counter.increment();
}
}observables (<=15)
Angular support is handled via rxjs async pipes!
Use observableFromExome from exome/rxjs to get store value as Observable and trigger it when it changes.
import { observableFromExome } from "exome/rxjs"
import { counter } from "./store/counter.ts"
@Component({
selector: 'my-app',
template: `
<h1 *ngIf="(counter$ | async) as counter" (click)="counter.increment()">
{{counter.count}}
</h1>
`,
})
export class App {
public counter$ = observableFromExome(counter)
}No framework
Use subscribe from exome to get store value in subscription callback event when it changes.
import { subscribe } from "exome"
import { counter } from "./store/counter.js"
const unsubscribe = subscribe(counter, ({ count }) => {
console.log("Count changed to", count)
})
setInterval(counter.increment, 1000)
setTimeout(unsubscribe, 5000)Redux devtools
You can use redux devtools extension to explore Exome store chunk by chunk.
Just add exomeReduxDevtools middleware via addMiddleware function exported by library before you start defining store.
import { addMiddleware } from 'exome'
import { exomeReduxDevtools } from 'exome/devtools'
addMiddleware(
exomeReduxDevtools({
name: 'Exome Playground'
})
)It all will look something like this:
API
Exome
A class with underlying logic that handles state changes. Every store must be extended from this class.
abstract class Exome {}useStore
Is function exported from "exome/react".
function useStore<T extends Exome>(store: T): Readonly<T>Arguments
store(Exome): State to watch changes from. Without Exome being passed in this function, react component will not be updated when particular Exome updates.
Returns
- Exome: Same store is returned.
Example
import { useStore } from "exome/react"
const counter = new Counter()
function App() {
const { count, increment } = useStore(counter)
return <button onClick={increment}>{count}</button>
}onAction
Function that calls callback whenever specific action on Exome is called.
function onAction(store: typeof Exome): UnsubscribeArguments
store(Exome constructor): Store that has desired action to listen to.action(string): method (action) name on store instance.callback(Function): Callback that will be triggered before or after action.
Argumentsinstance(Exome): Instance where action is taking place.action(String): Action name.payload(any[]): Array of arguments passed in action.
type("before" | "after"): when to run callback - before or after action, default is"after".
Returns
- Function: Unsubscribes this action listener
Example
import { onAction } from "exome"
const unsubscribe = onAction(
Person,
'rename',
(instance, action, payload) => {
console.log(`Person ${instance} was renamed to ${payload[0]}`);
// Unsubscribe is no longer needed
unsubscribe();
},
'before'
)saveState
Function that saves snapshot of current state for any Exome and returns string.
function saveState(store: Exome): stringArguments
store(Exome): State to save state from (will save full state tree with nested Exomes).
Returns
- String: Stringified Exome instance
Example
import { saveState } from "exome/state"
const saved = saveState(counter)loadState
Function that loads saved state in any Exome instance.
function loadState(
store: Exome,
state: string
): Record<string, any>Arguments
store(Exome): Store to load saved state to.state(String): Saved state string fromsaveStateoutput.
Returns
- Object: Data that is loaded into state, but without Exome instance (if for any reason you have to have this data).
Example
import { loadState, registerLoadable } from "exome/state"
registerLoadable({
Counter
})
const newCounter = new Counter()
const loaded = loadState(newCounter, saved)
loaded.count // e.g. = 15
loaded.increment // undefined
newCounter.count // new counter instance has all of the state applied so also = 15
newCounter.increment // [Function]registerLoadable
Function that registers Exomes that can be loaded from saved state via loadState.
function registerLoadable(
config: Record<string, typeof Exome>,
): voidArguments
config(Object): Saved state string fromsaveStateoutput.- key (String): Name of the Exome state class (e.g.
"Counter"). - value (Exome constructor): Class of named Exome (e.g.
Counter).
- key (String): Name of the Exome state class (e.g.
Returns
- void
Example
import { loadState, registerLoadable } from "exome/state"
registerLoadable({
Counter,
SampleStore
})addMiddleware
Function that adds middleware to Exome. It takes in callback that will be called every time before an action is called.
React hook integration is actually a middleware.
type Middleware = (instance: Exome, action: string, payload: any[]) => (void | Function)
function addMiddleware(fn: Middleware): voidArguments
callback(Function): Callback that will be triggeredBEFOREaction is started.
Argumentsinstance(Exome): Instance where action is taking place.action(String): Action name.payload(any[]): Array of arguments passed in action.
Returns
- (void | Function): Callback can return function that will be called
AFTERaction is completed.
Returns
- void: Nothingness...
Example
import { Exome, addMiddleware } from "exome"
addMiddleware((instance, name, payload) => {
if (!(instance instanceof Timer)) {
return;
}
console.log(`before action "${name}"`, instance.time);
return () => {
console.log(`after action "${name}"`, instance.time);
};
});
class Timer extends Exome {
public time = 0;
public increment() {
this.time += 1;
}
}
const timer = new Timer()
setInterval(timer.increment, 1000)
// > before action "increment", 0
// > after action "increment", 1
// ... after 1s
// > before action "increment", 1
// > after action "increment", 2
// ...FAQ
Q: Can I use Exome inside Exome?
YES! It was designed for that exact purpose.
Exome can have deeply nested Exomes inside itself. And whenever new Exome is used in child component, it has to be wrapped in useStore hook and that's the only rule.
For example:
class Todo extends Exome {
constructor(public message: string, public completed = false) {
super();
}
public toggle() {
this.completed = !this.completed;
}
}
class Store extends Exome {
constructor(public list: Todo[]) {
super();
}
}
const store = new Store([
new Todo("Code a new state library", true),
new Todo("Write documentation")
]);
function TodoView({ todo }: { todo: Todo }) {
const { message, completed, toggle } = useStore(todo);
return (
<li>
<strong
style={{
textDecoration: completed ? "line-through" : "initial"
}}
>
{message}
</strong>
<button onClick={toggle}>toggle</button>
</li>
);
}
function App() {
const { list } = useStore(store);
return (
<ul>
{list.map((todo) => (
<TodoView key={getExomeId(todo)} todo={todo} />
))}
</ul>
);
}Q: Can deep state structure be saved to string and then loaded back as an instance?
YES! This was also one of key requirements for this. We can save full state from any Exome with saveState, save it to file or database and the load that string up onto Exome instance with loadState.
For example:
const savedState = saveState(store)
const newStore = new Store()
loadState(newStore, savedState)Q: Can I update state outside of React component?
Absolutely. You can even share store across multiple React instances (or if we're looking into future - across multiple frameworks).
For example:
class Timer extends Exome {
public time = 0
public increment() {
this.time += 1
}
}
const timer = new Timer()
setInterval(timer.increment, 1000)
function App() {
const { time } = useStore(timer)
return <h1>{time}</h1>
}IE support
To run Exome on IE, you must have Symbol and Promise polyfills and down-transpile to ES5 as usual. And that's it!
Motivation
I stumbled upon a need to store deeply nested store and manage chunks of them individually and regular flux selector/action architecture just didn't make much sense anymore. So I started to prototype what would ideal deeply nested store interaction look like and I saw that we could simply use classes for this.
Goals I set for this project:
- <input checked="" disabled="" type="checkbox"> Easy usage with deeply nested state chunks (array in array)
- <input checked="" disabled="" type="checkbox"> Type safe with TypeScript
- <input checked="" disabled="" type="checkbox"> To have actions be only way of editing state
- <input checked="" disabled="" type="checkbox"> To have effects trigger extra actions
- <input checked="" disabled="" type="checkbox"> Redux devtool support