riux
v1.1.0
Published
📦 Fully typed and immutable store made on top of Immer with mutation, action, subscription and validation!
Downloads
4
Maintainers
Readme
Installation
pnpm add riux
Usage
Basic usage
import riux from 'riux';
const store = riux(42);
const reset = () => store.update(() => 0);
// 'draft' is automatically typed as 'number'
const increment = () => store.update((draft) => draft + 1);
const add = (value: number) => store.update((draft) => draft + value);
increment(); // 1
increment(); // 2
add(40); // 42
reset(); // 0
Ok, that's cool, but that's more or less what Immer already does! What next?
Add some mutations
This is the same example as above but using mutations.
const store = riux(42, {
// 'draft' is automatically typed as 'number' in each mutation
mutations: {
reset: () => 0,
increment: (draft) => draft + 1,
add: (draft, value: number) => draft + value,
},
});
store.mutation('increment'); // 1
store.mutation('increment'); // 2
store.mutation('add', 40); // 42
store.mutation('reset'); // 0
As you can see the code is a bit longer but better structured. All is centralized in the store (which allows for example to have autocompletions in the IDE). But this is not the only advantage and you will see it later with the actions.
Ok nice... But what next?
Add some subscriptions
You can register a function that will be called when the state is updated.
An update is raised each time the
update
,mutation
oraction
function is called.
const store = riux({ counter: 0 });
// 'state' is automatically typed as '{ counter: number }'
const subscription = store.subscribe((state) => {
console.log(state.counter);
});
subscription.disable(); // unsubscribe
subscription.enable(); // resubscribe
Well, that's a minimum, isn't it? What else is there?
Add some actions
The actions allow you to compose mutations that do not raise an event before the end of the action.
const store = riux(42, {
// 'draft' is automatically typed as 'number' in each mutation
mutations: {
reset: () => 0,
increment: (draft) => draft + 1,
add: (draft, value: number) => draft + value,
},
// 'mutation' is automatically typed in each action
actions: {
incrementTwice(mutation) {
mutation('increment');
mutation('increment');
},
addArray(mutation, values: number[]) {
for (const value of values) {
mutation('add', value);
}
},
},
});
store.subscribe((counter) => {
console.log(counter);
});
store.mutation('reset'); // 0
store.action('incrementTwice'); // 2
store.action('incrementTwice'); // 4
store.action('addArray', [5, 8, 10, 15]); // 42
// 'console.log' is called 4 times!
If an error is raised in an action, it will not be finalised and the state will remain unchanged, even if any mutations have been successfully completed.
Incredible, but I think I've seen this before! You talk about immutability at the beginning, and you haven't even mentioned it yet... say more!
Immutability
By default when you create a store, it becomes immutable as well as its source (as far as possible). This behaviour can be changed for the source but not for the state. In short, once created you will not be able to modify the state or any of is properties outside of the store!
const source = { life: 42 };
const store = riux(source);
source.life = 1337; // RUNTIME ERROR: Cannot assign to read only property 'life' of object...
const initialState = store.initial();
const currentState = store.current();
initialState.life = 1337; // TS ERROR + RUNTIME ERROR: Cannot assign to 'life' because it is a read-only property.
currentState.life = 1337; // TS ERROR + RUNTIME ERROR: Cannot assign to 'life' because it is a read-only property.
If you wish to avoid the first error you can set the freezeInitialState
option to false
.
Note that the state retrieved via
store.initial()
remains unchanged and immutable. Only the source outside the store will not be frozen.
const store = riux(source, { freezeInitialState: false });
source.life = 1337; // NO ERROR!
// ...
initialState.life = 1337; // TS ERROR + RUNTIME ERROR: Cannot assign to 'life' because it is a read-only property.
currentState.life = 1337; // TS ERROR + RUNTIME ERROR: Cannot assign to 'life' because it is a read-only property.
Ok that rocks, one source of truth I like that! But I want more!
Validation with custom parser
By default no data validation is done at runtime, only TypeScript protects you from input type errors at build time or in the IDE.
If you want to validate your data at runtime, you must provide a parse
function that validates/casts the state before finalizing the draft and either returns a strongly typed value (if valid) or throws an error (if invalid).
const store = riux(0, {
parse: (state) => {
if (typeof state === 'number') return state;
throw new Error(`expected 'number' got '${typeof state}'`);
},
mutations: {
add(draft, value: number) {
return draft + value;
},
},
});
store.mutation('add', 'prout'); // TS ERROR + RUNTIME ERROR: expected 'number' got 'string'
Another advantage of this method is the ability to specify multiple types (union). Imagine you have a single value that can be undefined or a string. How do you do this?
const store = riux(undefined, {
parse: (state) => {
if (state === undefined || typeof state === 'string') return state;
throw new Error(`expected 'number' got '${typeof state}'`);
},
mutations: {
set(_draft, value: string | undefined) {
return value;
},
},
});
store.current(); // string | undefined
store.mutation('set', undefined);
store.mutation('set', 'or string');
store.mutation('set', 42); // TS ERROR + RUNTIME ERROR: expected 'string' got 'number'
This is starting to be very interesting, but I'm sure we can do better! Right?
Validation with Zod, Superstruct, Yup, tson, ...
Zod is a TypeScript-first schema validation with static type inference which can be used to validate the state of the store on each mutation. This is very powerful when it comes to parse complex data structures.
const schema = z.object({
name: z.string().min(3),
life: z.number(),
});
const store = riux(
{ name: 'nyan', life: 42 },
{
parse: (state) => schema.parse(state),
mutations: {
setName(draft, name: string) {
draft.name = name;
},
setLife(draft, life: number) {
draft.life = life;
},
},
},
);
store.current(); // { readonly name: string; readonly life: number }
store.mutation('setName', 'bob'); // { name: 'bob', life: 42 }
store.mutation('setLife', 1337); // { name: 'bob', life: 1337 }
store.mutation('setLife', [true]); // TS ERROR + RUNTIME ZodError: Expected number, received array
store.mutation('setName', 'na'); // TS ERROR + RUNTIME ZodError: String must contain at least 3 character(s)
The Example above is with Zod, but it can work with any library that exposes a function/method with the right signature, like Superstruct, Yup, tson and more...
Need more?
Scaling
As your store grows you will probably want to split your code into several files. Here's how to do it.
// initial-state.ts
export const initialState = {
name: 'nyan',
life: 42,
items: [
{ id: 1, name: 'item-1', rare: true },
{ id: 2, name: 'item-2', rare: false },
{ id: 3, name: 'item-3', rare: false },
],
};
export type State = typeof initialState;
export type Item = State['items'][number];
// mutations.ts
import { createMutation, createMutations } from 'riux';
import { initialState, type Item } from './initial-state.js';
// This function could be in another file, for example 'mutations/add-item.ts.
const addItem = createMutation(initialState, (draft, item: Item) => {
draft.items.push(item);
});
export const mutations = createMutations(initialState, {
setName: (draft, name: string) => {
draft.name = name;
},
setLife(draft, life: number) {
draft.life = life;
},
addItem,
});
// actions/add-items.ts
import { createAction } from 'riux';
import { initialState, type Item } from '../initial-state.js';
import { mutations } from '../mutations.js';
export const addItems = createAction(initialState, mutations, (mutation, items: Item[]) => {
for (const item of items) {
mutation('addItem', item);
}
});
// actions.ts
import { createAction, createActions } from 'riux';
import { initialState, type Item } from './initial-state.js';
import { mutations } from './mutations.js';
import { addItems } from './actions/add-items.js';
export const actions = createActions(initialState, mutations, {
setName(mutation, name: string) {
mutation('setName', name);
},
addItems,
});
// store.ts
import { initialState, type Item } from './initial-state.js';
import { mutations } from './mutations.js';
import { actions } from './actions.js';
export const store = createStore(initialState, { mutations, actions });
Type inference
You can extract the TypeScript types of any store with InferState
, InferMutations
or InferActions
.
import riux, { type InferState, type InferMutations } from 'riux';
const store = riux(42, {
mutations: {
add: (state, value: number) => state + value,
},
});
type State = InferState<typeof store>; // number
type Mutations = InferMutations<typeof store>; // { add: (state: number, value: number) => number; }
Ok that's all for now, but if you think something is missing you can open an issue or even better make a pull request.
Scaffolded with @skarab/skaffold