A schema has two primary features:

A fully typed state shape
Reusable pieces of state management logic

A schema must be an object. It is composed of slices of state. Slices can represent any data type, however, we recommend keeping it as JSON serializable as possible. Slices not only hold a value, but with it comes some handy functions to:

Update the value
Query for data within the value

Our schema implementation was heavily inspired by zod.

Schema assumptions #

createSchema requires two slices by default in order for it and everything inside starfx to function properly: cache and loaders.

Why do we require those slices? Because if we can assume those exist, we can build a lot of useful middleware and supervisors on top of that assumption. It's a place for starfx and third-party functionality to hold their state.

1import { createSchema, slice } from "starfx";
2
3const [schema, initialState] = createSchema({
4  cache: slice.table(),
5  loaders: slice.loaders(),
6});

Built-in slices #

As a result, the following slices should cover the most common data types and associated logic.

`slice.any` #

This is essentially a basic getter and setter slice. You can provide the type it ought to be and it has a couple functions to manage and query the value stored inside of it.

1const [schema] = createSchema({
2  nav: slice.any<bool>(false),
3});
4
5function*() {
6  yield* schema.update(schema.nav.set(true)); // set the value
7  const nav = yield* select(schema.nav.select); // grab the value
8  yield* schema.update(schema.nav.reset()); // reset value back to inititial
9}

`num` #

This slice has some custom actions to manage a number value.

 1const [schema] = createSchema({
 2  views: slice.num(0),
 3});
 4
 5function*() {
 6  yield* schema.update(schema.views.increment());
 7  yield* schema.update(schema.views.decrement());
 8  yield* schema.update(schema.views.set(100));
 9  const views = yield* select(schema.views.select);
10  yield* schema.update(schema.views.reset()); // reset value back to inititial
11}

`str` #

This slice is probably not super useful since it is essentially the same as slice.any<string> but we could add more actions to it in the future.

1const [schema] = createSchema({
2  token: slice.str(""),
3});
4
5function*() {
6  yield* schema.update(schema.token.set("1234"));
7  const token = yield* select(schema.token.select);
8  yield* schema.update(schema.token.reset()); // reset value back to inititial
9}

`obj` #

This is a specialized slice with some custom actions to deal with javascript objects.

 1const [schema] = createSchema({
 2  settings: slice.obj({
 3    notifications: false,
 4    theme: "light",
 5  }),
 6});
 7
 8function*() {
 9  yield* schema.update(schema.settings.update(theme, "dark"));
10  yield* schema.update(schema.settings.update(notifications, true));
11  const settings = yield* select(schema.settings.select);
12  yield* schema.update(schema.token.reset()); // reset value back to inititial
13  yield* schema.update(
14    schema.token.set({ notifications: true, theme: "dark" }),
15  );
16}

`table` #

This is the more powerful and specialized slice we created. It attempts to mimick a database table where it holds an object:

1type Table<Entity = any> = Record<string | number, Entity>;

The key is the entity's primary id and the value is the entity itself.

 1const [schema] = createSchema({
 2  users: slice.table({ empty: { id: "", name: "" } }),
 3});
 4
 5function*() {
 6  const user1 = { id: "1", name: "bbob" };
 7  const user2 = { id: "2", name: "tony" };
 8  const user3 = { id: "3", name: "jessica" };
 9  yield* schema.update(
10    schema.users.add({
11      [user1.id]: user1,
12      [user2.id]: user2,
13      [user3.id]: user3,
14    }),
15  );
16  yield* schema.update(
17    schema.users.patch({ [user1.id]: { name: "bob" } }),
18  );
19  yield* schema.update(
20    schema.users.remove([user3.id]),
21  );
22  
23  // selectors
24  yield* select(schema.users.selectTable());
25  yield* select(schema.users.selectTableAsList());
26  yield* select(schema.users.selectById({ id: user1.id }));
27  yield* select(schema.users.selectByIds({ ids: [user1.id, user2.id] }));
28
29  yield* schema.update(schema.users.reset());
30}

empty #

When empty is provided to slice.table and we use a selector like selectById to find an entity that does not exist, we will return the empty value.

This mimicks golang's empty values but catered towards entities. When empty is provided, we guarentee that selectById will return the correct state shape, with all the empty values that the end-developer provides.

By providing a "default" entity when none exists, it promotes safer code because it creates stable assumptions about the data we have when performing lookups. The last thing we want to do is litter our view layer with optional chaining, because it sets up poor assumptions about the data we have.

Read more about this design philosophy in my blog post: Death by a thousand existential checks.

When creating table slices, we highly recommend providing an empty value.

Further, we also recommend creating entity factories for each entity that exists in your system.

`loaders` #

This is a specialized database table specific to managing loaders in starfx. Read more about loaders here.

 1const [schema] = createSchema({
 2  loaders: slice.loaders(),
 3});
 4
 5function*() {
 6  yield* schema.update(schema.loaders.start({ id: "my-id" }));
 7  yield* schema.update(schema.loaders.success({ id: "my-id" }));
 8  const loader = yield* select(schema.loaders.selectById({ id: "my-id" }));
 9  console.log(loader);
10}

Build your own slice #

We will build a counter slice to demonstrate how to build your own slices.

 1import type { AnyState } from "starfx";
 2import { BaseSchema, select } from "starfx/store";
 3
 4export interface CounterOutput<S extends AnyState> extends BaseSchema<number> {
 5  schema: "counter";
 6  initialState: number;
 7  increment: (by?: number) => (s: S) => void;
 8  decrement: (by?: number) => (s: S) => void;
 9  reset: () => (s: S) => void;
10  select: (s: S) => number;
11}
12
13export function createCounter<S extends AnyState = AnyState>(
14  { name, initialState = 0 }: { name: keyof S; initialState?: number },
15): CounterOutput<S> {
16  return {
17    name: name as string,
18    schema: "counter",
19    initialState,
20    increment: (by = 1) => (state) => {
21      (state as any)[name] += by;
22    },
23    decrement: (by = 1) => (state) => {
24      (state as any)[name] -= by;
25    },
26    reset: () => (state) => {
27      (state as any)[name] = initialState;
28    },
29    select: (state) => {
30      return (state as any)[name];
31    },
32  };
33}
34
35export function counter(initialState?: number) {
36  return (name: string) => createCounter<AnyState>({ name, initialState });
37}
38
39const [schema, initialState] = createSchema({
40  counter: counter(100),
41});
42const store = createStore(initialState);
43
44store.run(function* () {
45  yield* schema.update([
46    schema.counter.increment(),
47    schema.counter.increment(),
48  ]);
49  const result = yield* select(schema.counter.select);
50  console.log(result); // 102
51});

Schema

Schema assumptions #

Built-in slices #

slice.any #

num #

str #

obj #

table #