@betomorrow/micro-stores

Micro-stores

A light state management library featuring observables and immutability

Usage

import { Store } from "micro-stores";

const bookStore = new Store((id) => fetch(`https://myApi.com/books/${id}`));
const myFavoriteBook = bookStore.getObservable("dracula");

console.log(myFavoriteBook.get()); // null
bookStore.fetch("dracula");
console.log(myFavoriteBook.get()); // { id: "Dracula", ... }

⚠️ Usage with React Native ⚠️

This library depends on uuid. To use uuid, and therefore micro-stores with React Native, you need to follow the steps described at https://github.com/uuidjs/uuid#react-native--expo:

• Install react-native-get-random-values
• Run a pod install
• Import it at the root of your app:
  import 'react-native-get-random-values';

Micro-observables

This library is quite heavily based on micro-observables. You may want to take a look at the Observable signature there.

Api

Micro-stores exposes 3 main Stores that can be used to easily manage your application state.

Store

A simple Store retrieving items using a primary key.

import { Store } from "micro-stores";

const bookStore = new Store((id) => fetchBook(id));
bookStore.fetch();

To create a Store, you have to provide a fetcher function retrieving objects using an unique identifier. By default, your store will use the id property of the object (if it exists).
If your object doesn't have an id property, you will need to use one, or specify another unique property to be used.

Constructor parameters

Parameter	Type	Default Value	Description
fetch	(key: string) => T | Promise<T>	/	The function retrieving item by its key
primaryKey	string	"id"	The primary key to use to map your objects

Builder Methods

bindProperty

You can enrich your Store by binding a property to another Store using the bindProperty method.
This is useful if you want to ensure yours objects are up to date when making changes to its referenced property. The Store will use the referenced property unless it is removed from its own Store

Usage

import { Store } from "micro-stores";

const userStore = new Store(fetchUser);
const bookStore = new Store(fetchBook).bindProperty("infos.author", userStore);

bookStore.fetch("dracula");
console.log(userStore.getObservable("bram-staker").get());
// { id: bram-stoker, name: "Bram Stoker" }
userStore.save({ id: "bram-staker", name: "Bram" });
console.log(bookStore.getObservable("dracula").get().infos.author);
// { id: "bram-staker", name: "Bram" }
userStore.remove("bram-staker");
console.log(bookStore.getObservable("dracula").get().infos.author);
// { id: "bram-staker", name: "Bram Staker" }

presentProperty

It has the same purpose as bindProperty, but can be used with lighter objects. This means that when fetching items from your store, it will not populate the presented Store with light values. However, it will update the presented store with updated value if they already exist.

Method	Type	Description
bindProperty	(path: string, referenceStore: Store<U>) => Store<T>	Binds your item property to another Store
presentProperty	(path: string, referenceStore: Store<Partial<U>>) => Store<T>	Presents your item property to another Store

Methods and properties

Main methods and properties:

Property	Type	Description
primaryKey	string	The primary key to use to map your objects
items	Observable<Map<string, T>>	The observable of the items mapped by their key
getObservable	(key: string) => Observable<T>	Retrieve an observable using its key
fetch	(key: string) => Promise	Call the Store fetch function and saves the received item
save	(item: T) => void	Save an item to the Store. If an items exists will the same key, it will be erased
merge	(items: T[]) => void	Save several items at once
remove	(key: string) => void	Remove an item from the Store
update	(key: string, updater: (current: T) => T) => void	Update an item using an update callback, if it exists
updateProperties	(item: Partial) => void	Update an items with specified properties, if it exists
batchUpdateProperties	(items: Partial[]) => void	Update several items with specific properties, if they exists
clear	() => void	Clears the store
onDelete	Signal	Called when an item is removed from the Store

PaginatedStore

A PaginatedStore stores items in an Array and handles pagination for you using Pages.

import { PaginatedStore } from "micro-stores";

const bookStore = new PaginatedStore((page) => fetchBooks(page));
bookStore.list();
bookStore.listMore();
bookStore.listMore();

To create a PaginatedStore, you have to provide a fetcher function retrieving a page of objects using an page number.

A Page is an interface defined by this properties:

interface Page {
	content: T[];
	page: number;
	totalPages: number;
	totalSize: number;
}

Constructor parameters

Parameter	Type	Description
fetchList	(page: number) => Promise<Page> | Page)	The function retrieving Page by its index

Builder Methods

bind

You can bind your PaginatedStore to another Store using the bind method.
This will allow you to show in your list of items the actual items from the binded Store, thus ensuring them to be up to date. The binded Store will also be automatically updated with the values retrieved when listing objects from the PaginatedStore You can only bind a PaginatedStore to a Store that stores the exact same interface of objects. Meaning that your PaginatedStore will have to use the same unique identifier property as your simple Store.
You can only bind your PaginatedStore to a single Store.

Usage

import { Store, PaginatedStore } from "micro-stores";

const bookStore = new Store(fetchBook);
const favoriteBookStore = new PaginatedStore(fetchBook).bind(bookStore);

favoriteBookStore.list();
console.log(bookStore.getObservable("dracula").get());
// { id: "dracula", name: "Dracula" }
bookStore.save({ id: "dracula", name: "Dracula 2" });
console.log(favoriteBookStore.paginatedItems.get().content[0]);
// { id: "dracula", name: "Dracula 2" }
bookStore.remove("dracula");
console.log(favoriteBookStore.paginatedItems.get().content[0]);
// null

present

present is very similar to the bind building method. The difference being it allows you to present from a Store items that are partials objects stored in a PaginatedStore.
For performance purpose, prefer using bind over present if your Store and your PaginatedStore use the exact same objects.

Your can only bind or present one single Store

Method	Type	Description
bind	(referenceStore: Store<T>) => Store<T>	Binds your Paginated Store to another Store
present	(referenceStore: Store<U extends T>) => Store<T>	Binds your Paginated Store to another Store

Methods and properties

Main methods and properties:

Property	Type	Description
fetching	Observable<boolean>	Is the store fetching initial items ?
fetchingMore	Observable<boolean>	Is the store fetching more items ?
paginatedItems	Observable<Page<T> | null>	The observable page of the items
list	() => void	Call the Store fetchList function for the first page and erases the existing items
listMore	() => void	Call the Store fetchList function and merge the new items

MappedStore

A MappedStore stores paginated arrays of items in an Map.
It is quite similar to PaginatedStore, also allowing you to store your paginated items according to specified keys.

import { MappedStore } from "micro-stores";

const bookStore = new MappedStore((userId, page) => fetchFavoriteBooksForUser(userId, page));
bookStore.list("user-1");
bookStore.listMore("user-1");
bookStore.list("user-2");

To create a MappedStore, you have to provide a fetcher function retrieving a page of objects using a mapping key and page number.

Constructor parameters

Parameter	Type	Description
fetchList	(id: string, page: number) => Promise<Page> | Page)	The function retrieving Page by its index

Builder Methods

bind and present

Just like a PaginatedStore, a MappedStore allows you to bind/present another Store.

Methods and properties

Main methods and properties:

Property	Type	Description
getFetching	(key:string) => Observable<boolean>	Is the store fetching initial items for this key?
getFetchingMore	(key:string) => Observable<boolean>	Is the store fetching more items for this key?
getObservableItems	(key:string) => Observable<Page<T> | null>	The observable page of the items
list	(key: string) => void	Call the Store fetchList function for this key for the first page and erases the existing items
listMore	(key: string) => void	Call the Store fetchList function for this key and merge the new items
clear	() => void	Clears the store

Usage with React

This library makes State Management easier for any nodeJS or browser application, and has been especially thought to be used with React.
This is why Micro-stores also gives you hooks to help you manage and retrieve the state of your React project:

useStore(key, store, fetchStrategy?, additionalDeps?)

Return the value of the matching the given key, the loading state and the current error. Triggers a re-render when the value changes.

import { Store, useStore } from "micro-stores";

const bookStore = new Store(fetchBook);

const DraculaBookView = () => {
	const { result: book, loading, error } = useStore("dracula", bookStore);

	if (book) {
		return (
			<div>
				{book.title} from {book.author}
			</div>
		);
	}
	if (loading) {
		return <div>Loading...</div>;
	}
	return null;
};

usePaginatedStore(paginatedStore, fetchStrategy?, additionalDeps?)

Returns a PaginatedDataResult of the given paginated store. Triggers a rerender when these properties change.

import { PaginatedStore, usePaginatedStore } from "micro-stores";

const bookStore = new PaginatedStore(fetchBooks);

const BookView = () => {
	const { result: books, listMore, lastPage, loading, moreLoading } = usePaginatedStore(bookStore);

	if (loading) {
		return <div>Loading...</div>;
	}
	return <div>
		<h2>Books</h2>
		{books.map(book => <BookView book={book}/>}
		{moreLoading && <div>Loading...</div>}
		{!lastPage && <button onClick={() => listMore()}>Load More</button>}
	</div>
};

useMappedStore(key, mappedStore, fetchStrategy?, additionalDeps?)

Similar to usePaginatedStore, only difference being you need to pass in the key you want to fetch.

PaginatedDataResult

The PaginatedDataResult is defined like this:

Property	Type	Description
result	T[]	The current array of results
loading	boolean	Is the first page being loaded
moreLoading	boolean	Are more items beeing loaded
error	Error |null	Fetching error
lastPage	boolean	Are all the pages fetched
totalPages?	number | undefined	The number of pages
totalSize?	number | undefined	The total size of the elements
list	() => void	Function to fetch the first page
listMore	() => void	Function to fetch the next page
clear	() => void	Clears the store

Fetch Strategy

The hooks above allow you to define a Fetch Strategy to decide how often the data should be fetch:

• FetchStrategy.Always (default): The fetch function is called every time the component mounts or a dependency changes
• FetchStrategy.Never: The fetch function is never called from the hook, you want to handle it yourself
• FetchStrategy.First: The fetch function is only called if there is still no result associated with the data (useful if you already fetched the result in a parent component)
• FetchStrategy.Once: The fetch function is called every time the component mounts.

Typescript

This library is entirely written in Typescript, meaning you can benefit from its typings without installing other packages.