@tabular-state/store

Tabular-State is a simple and reactive state mangement solution based on tables, rows and cells. Under the hood it uses observables from @legendapp/state which is a super fast and powerful state manager for JavaScript apps.

Tabular-State brings also the possibility to query and persist state.

Warning Tabular-State is in early stage and not yet ready for production

Install

1npm install @tabular-state/store

1pnpm install @tabular-state/store

1yarn add @tabular-state/store

Basic Usage

1import { createStore } from '@tabular-state/store';
2
3type Tables = {
4  users: {
5    idField: number; // could be string or number
6    item: {
7      id: string;
8      name: string;
9      age: number;
10    };
11  };
12  posts: {
13    idField: string;
14    item: {
15      id: string;
16      title: string;
17      content: string;
18      authorId: string;
19      createdAt: string;
20    };
21  };
22};
23
24const store = createStore<Tables>();

Set and Get Tables

1import { ObservableObject } from '@legendapp/state';
2
3// write
4store.setTable('users');
5
6// read
7/**
8 * @returns {ObservableObject<Tables['users']>}
9 */
10const users = store.getTable('users');
11console.log(users.peek());
12console.log(users.get());

Set and Get Rows

Note Rows are managed by the store and are not directly accessible. You can only get a row by its id.

For reactivity have a look into Legend-State Docs.

1import { ObservableObject } from '@legendapp/state';
2
3// write
4setRow('users', 1, {
5  id: 1,
6  name: 'John Doe',
7  age: 42,
8});
9
10// read
11/**
12 * @returns {ObservableObject<Tables['users']['item']>}
13 */
14const user = store.getRow('users', 1);
15console.log(user.peek());
16console.log(user.get());

Set and Get Cells

Note Cells are managed by the store and are not directly accessible. You can only get a cell by its key.

For reactivity have a look into Legend-State Docs.

1import { ObservableObject } from '@legendapp/state';
2
3// read
4/**
5 * @returns {ObservableObject<Tables['users']['item']['age']>}
6 */
7const userAge = store.getCell('users', 1, 'age');
8console.log(userAge.peek()); // 42
9console.log(userAge.get()); // 42
10
11// write
12setCell('users', 1, 'age', 43);
13console.log(userAge.peek()); // 43

Querying

Querying is based on sift which is a mongo-query like implementation for JavaScript.

1const [results, queryFn, queryMeta] = store.queryRows('posts', {
2  query: { authorId: user.peek().id },
3  limit: 5,
4  skip: 0,
5  sort: { createdAt: 1 }, // 1 = asc, -1 = desc
6  select: ['id', 'title', 'createdAt'],
7  style: 'paginated', // paginated | infinite
8});
9
10// read
11console.log(results.peek()); // [{ id: '1', title: 'Hello World', createdAt: '2021-01-01' }]
12console.log(results.get());

Query Pagination

Property style defines in which form the pagination works.

1/**
2 * paginated: The query will return the items from the current
3 * infinite: The query will get bigger on every page change.
4 * @default infinite
5 */
6type PaginationStyle = 'paginated' | 'infinite';
7
8type QueryFn = {
9  // if possible will open/load next page
10  next(): void;
11  // if possible will open previous page or unload items from the current page
12  prev(): void;
13};
14
15queryFn.next();
16queryFn.prev();

Query Meta

1type QueryMeta = {
2  // current page
3  page: Observable<number>;
4  // number of items per page
5  pageSize: ObservableComputed<number>;
6  // total number of items
7  total: Observable<number>;
8  // if there is a next page
9  canShowMore: ObservableComputed<boolean>;
10};
11
12// read
13console.log(queryMeta.page.peek());
14console.log(queryMeta.page.get());
15
16console.log(queryMeta.pageSize.peek());
17console.log(queryMeta.pageSize.get());
18
19console.log(queryMeta.total.peek());
20console.log(queryMeta.total.get());
21
22console.log(queryMeta.canShowMore.peek());
23console.log(queryMeta.canShowMore.get());

Mount hooks to listen to reads

You can listen to all reads by using hooks (before, after, error) on the methods getTable, getRow, getCell, setRow, setCell, delRow, delCell and queryRows.

1const store = createStore();
2
3const dispose = store.hook('before', 'getRow', (ctx) => {
4  // ctx.method = 'getRow'
5  // ctx.params.table = the table on which the method was called
6  // ctx.params.rowId = the id of the row
7});
8
9dispose(); // remove hook
10
11store.hook('before', 'getTable', (ctx) => {
12  // ctx.method = 'getRow'
13  // ctx.params.table = the table on which the method was called
14});
15
16store.hook('before', 'getCell', (ctx) => {
17  // ctx.method = 'getRow'
18  // ctx.params.table = the table on which the method was called
19  // ctx.params.rowId = the id of the row
20  // ctx.params.cellKey = the key of the cell
21});
22
23store.hook('before', 'queryRows', (ctx) => {
24  // ctx.method = 'queryRows'
25  // ctx.params.table = the table on which the method was called
26  // ctx.params.query = the query object
27});