valtio-factory - create "stores" using the factory pattern

[mfellner]

I'd like to share a package I created, valtio-factory (CodeSandbox). It provides a somewhat opinionated solution on top of valtio to create "stores" (state, derived state, actions, subscriptions) using the factory pattern:

// declare first
const factory = createFactory({ count: 0 })
  .derived({
    // it's a bit simpler than vanilla derive/get
    doubled(state) {
      return state.count * 2;
    },
  })
  .actions({
    increment() {
      this.count += 1;
    },
    double() {
      // actions can also use derived state
      this.count = this.doubled;
    },
    async fetchCount() {
      // actions can access the transitive context object (it's a "ref")
      this.count = await this.$context.myApiClient.fetchCount();
    },
  })
  .subscribe((state) => {
    // you can subscribe to the whole state
    console.log("state:", state);
  })
  .onCreate((state) => {
    // or do anything with the proxy state object
    subscribeKey(state, "count", (n) => {
      console.log("count:", n);
    });
  });

// initialise later to create the state proxy object
const state = factory.create();

// call actions
state.increment();

// you can supply context and initial state
const context = { myApiClient: new Api() };
const initialState = JSON.parse(localStorage.getItem("APP_STATE"));
const state = factory.create(context, initialState);

In general, it simplifies and reduces the boilerplate for doing the following things:

• Separation of store declaration and initialization
• Initializing stores from external data sources (e.g. local storage, async storage)
• Declaring actions and binding them to state
• Declaring derived state and subscriptions
• Injecting dependencies into actions and other state-dependent logic with context
• Composing multiple stores

I had the idea to create valtio-factory when I was working on a react-native app that was previously using MobX-State-Tree. In that project I needed to achieve several objectives:

Declare the app's state model and its actions

Using the factory pattern, declaring state, derived state, and actions all together in a concise way is straightforward.
At the same time, the state does not need to be initialised until later, when the create method is called.

"Inject" dependencies into state-dependent logic

A pitfall of simple state management libraries has often been that external dependencies of the business logic (e.g. API clients) must be initialised inside the business logic itself or be imported as "singleton" instances.

With the context object, valtio-factory stores can declare an abstract interface that will be satisfied with a concrete implementation on initialisation. This can also be useful for testing, as the external dependencies can be easily mocked.

Initialise stores with persisted state

Because stores can be declared and created later, it's easy to come up with a pattern of serialising state to, e.g., async storage and initialising them when the app is started (i.e. when the React component tree is first rendered).

Compose stores

valtio-factory can also compose stores (factories) into objects. That way it's possible to declare a single "root store" that will be passed to the application.

valtio-factory is designed as a complement to valtio. The result of the create method is a proxy object that can be used with all existing valtio utilities. While vanilla valtio is simpler and more flexible, I believe valtio-factory can be a great option for more complex applications that might otherwise use solutions like Redux+Saga or MobX-State-Tree.

Keen to read your thoughts and feedback!

[lveillard]

Epic package!
I have a use case with two rare constraints, iIm wondering if valtio and valtio-factory can solve them.

1) I have variables depending on other variables, that migth depend on other variables...

For example, lets say we have:
Birthday: Just a date
Age: A computed number => Today() - Birthday
IsAdult: A computed boolean => if(Age) >= 18

Right now i'm checking this package: https://github.com/datavis-tech/topologica
But maybe i can do this graph of dependencies in Valtio?

2) My store definition is dynamic

I store those formulas on the DB, kind of google sheet / excel. This means i CAN'T create the store directly in my code, I need to read the DB, interpret it and create the store and its formulas after reading the DB. This is where valtio-factory might help?

What do you think?

[targetlucked69]

Cool! Love this.

Even cooler if it uses the valtio/vanilla package so any lib outside react can use it too!