DEV Community: Yuriy Yakym

Implementing State management library - Awai Scenario

Yuriy Yakym — Wed, 27 Dec 2023 00:50:03 +0000

Hi there devs! 👋

Today we will create one of the most helpful tools for our state management library - Scenario. In this part we will only cover basic, yet most useful strategy - fork.

Fork strategy means that every trigger is handled, thus at the same point of time, few async callbacks may be running, which can lead to potential race conditions, so be careful.

If you're curious about all the capabilities of scenario, head straight to Awai docs.

The scenario we will implement should receive a trigger and a callback. Callback will be executed each time scenario is triggered.

Similarly to the tools we created in previous parts, scenario will emit events. Its events will be started, fulfilled and rejected.

Things are getting way more interesting at this point, aren't they?

Scaffold of our tool:

const scenario = (trigger, callback) => {
  const events = {
    started: new AwaiEvent(),
    fulfilled: new AwaiEvent(),
    rejected: new AwaiEvent(),
  };

  const run = () => {
    // to be implemented
  };

  run();

  return { events };
};

In order to implement the run function we can re-use and modify the code we implemented in previous part, where we were listening to dependencies changes in selector.

Wait, wait, wait! 🤔 This all sounds great, but what can be a trigger? It can be at least our thennable AwaiEvent. But let's make the tool even more powerful, so that trigger can be any Promise! Do you already see where is it going? 😎

At this point our scenario will have two overloads, which will be enough for implementing most of other utils up until the end of this series.

// AwaiEvent trigger (from previous chapters)
scenario(awaiEvent, callback);

// factory that returns a Promise, which will trigger a scenario
scenario(() => promise, callback);

As you can see, trigger can be a function returning a promise. Once promise is resolved, the scenario callback will start.

No more words, let's implement.

const getTriggerPromise = (trigger) => typeof trigger === 'function' ? trigger() : trigger;

const run = () => {
  getTriggerPromise(trigger).then((event) => {
    events.started.emit({ config, event });

    Promise.resolve(callback(event))
      .then((result) => {
        events.fulfilled.emit({ event, result });
      })
      .catch((error) => {
        events.rejected.emit(error);
      });

    run();
  });
};

In getTriggerPromise helper function we check the trigger - if it is a function, we call it and expect it to return a promise, otherwise we just return a trigger (which is, according to our overloads, an AwaiEvent).

It is quite remarkable that we pass the result of a trigger to callback as an argument. Now scenario can play the role of event listener! 🧐

Notice how we wrapped callback call with Promise.resolve. Since our callback may be both sync and async, this Promise.resolve is used to ensure that we have a promise at this place.
If this promise is resolved, it means the callback has successfully returned a value, which we then emit in fulfilled event. If it rejects, we emit rejected error.

I hope you understand everything so far. If not, feel free to ask questions.

Full util code:

const getTriggerPromise = (trigger) => {
  return typeof trigger === 'function' ? trigger() : trigger;
};

const scenario = (trigger, callback) => {
  const events = {
    started: new AwaiEvent(),
    fulfilled: new AwaiEvent(),
    rejected: new AwaiEvent(),
  };

  const run = () => {
    getTriggerPromise(trigger).then((event) => {
      events.started.emit({ config, event });

      Promise.resolve(callback(event))
        .then((result) => {
          events.fulfilled.emit({ event, result });
        })
        .catch((error) => {
          events.rejected.emit(error);
        });

      run();
    });
  };

  run();

  return { events };
};

Now we can use this tool to listen to any state changes

const nameState = state('John');

setTimeout(() => nameState.set('Andrew'), 1000);

scenario(nameState.events.changed, (name) => {
  console.log(`New user name: ${name}`);
});

But our tool is so powerful, let's write a bit more advanced example. We can notify the API as soon as user name is changed, and let's also add some logging without polluting callback code.

const nameChangeScenario = scenario(nameState.events.changed, async (name) => {
  await fetch('/api/user-name', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name })
  });
});

scenario(nameChangeScenario.events.started, () => {
  console.log('User name changed. We have started API notifying process.');
});

scenario(nameChangeScenario.events.fulfilled, () => {
  console.log('Server has been notified about user name change');
});

scenario(nameChangeScenario.events.rejected, (error) => {
  console.log(`There were problems while updating user name. Error: ${String(error)}`);
});

Yes, we can use scenario to listen to another scenario events! 🤫

You probably think I forgot about promise factory overload? No way, that's my favorite part.

For better demonstration we need a wait util which just resolves a promise after specified amount of time.

const wait = (delay) => new Promise((resolve) => setTimeout(resolve, delay));

Here we go, the easiest fancy scenario, which runs every second:

scenario(() => wait(1000), () => {
  console.log('One more second passed');
});

Under the hood, we run a trigger function that returns a Promise which will be resolved after one second. Right after that, scenario callback will run (logs text to console), and start scenario listener again, so that we will get a new promise which will be resolved after one second, and so forth.

As the last example, we will combine some promises. So that scenario is triggered either every second, or when name is changed.

scenario(
  () => Promise.race([
    wait(1000),
    nameState.events.changed
  ]),
  () => {
    console.log('This callback is called every second, but also when nameState is changed');
  }
);

Summary

Enjoyed this tutorial? Stay tuned for further parts.
Do you see the potential of this tool? Any ideas how you can use Scenario in your projects? Share your thoughts in comments.

As usual, here is the playground where you can play with the tool we created together.

See you in next chapters!

Implementing State management library - Awai Selector

Yuriy Yakym — Mon, 25 Dec 2023 21:57:01 +0000

In previous chapter we have implemented a basic synchronous state node, which can emit events using thennable object.
It would be nice if our state management library provides some solution for combining multiple state nodes into a single value, which would be especially helpful with decoupled data. In many libraries this tool is called selector, thus let's just go with this name.

Reminder: this tutorial series describe how to create Awai state management library from scratch.

This part will be quite easy and understandable, so grab your coffee and relax before we dive into an async state management in further parts.

Selector will accept an array of state nodes and predicate function, which will be used to combine a result. Selector should react to any state changes, and determine new value each time changed event is emitted. All the state nodes' values will be passed to predicate as arguments preserving their order in an array.

Let's write selector function scaffold, and try to stick to our sync state node interface.

const selector = (states, predicate) => {
  const initialValue = predicate(...states.map(state => state.get()));
  let value = initialValue;

  const events = {
    changed: new AwaiEvent()
  };

  const get = () => value;

  return { events, get };
};

It looks nice already. We're calling predicate in order to determine an initialValue, and we even expose events. But we do not react to any dependency changes. Let's assume we're in The Stone Age, and Scenario has not yet been discovered. What can we do? As you remember, all our events are thennable (promise-like). So let's use this fact to create an async loop, which will watch these events.

const listenToChanges = async () => {
  await Promise.any(states.map(state => state.events.changed));
  const statesValues = states.map(state => state.get());
  value = predicate(...statesValues);
  events.changed.emit(value);
  listenToChanges();
};

That's the hardest piece of code in this part. Here we await a promise which is a combination of all of nodes' changed events - as soon as any of them is emitted (resolved), we call the predicate function to determine new result and store it in value variable. Right after that we emit changed event from the selector. And finally call the same function to start watching changes again.

Complete util code:

const selector = (states, predicate) => {
  const initialValue = predicate(...states.map(state => state.get()));
  let value = initialValue;

  const events = {
    changed: new AwaiEvent()
  };

  const get = () => value;

  const listenToChanges = async () => {
    await Promise.any(states.map(state => state.events.changed));
    const statesValues = states.map(state => state.get());
    value = predicate(...statesValues);
    events.changed.emit(value);
    listenToChanges();
  };

  listenToChanges();

  return { events, get };
};

Now we can use this helper like this:

const nameState = state('John');
const ageState = state(30);

const userDetailsState = selector(
  [nameState, ageState],
  (name, age) => ({ name, age })
);

console.log(userDetailsState.get()); // { name: 'John', age: 30 }

Summary

We have created a very useful helper - Selector, which allows to combine multiple state nodes into a single value. So far it only works with sync states, but as we proceed with this tutorial, we would have to support async as well.

You can check our selector in action at the playground.

See you in next chapters!

Implementing State management library - Introduction to Awai

Yuriy Yakym — Sat, 23 Dec 2023 14:37:22 +0000

Hey JavaScript community 👋 It's been 7 months of intense thinking and tinkering, and Awai has finally reached release candidate stage.
In this tutorial, which will consist of multiple parts, I am going to show you how I came to certain ideas and how I implemented Awai state management library, which is designed to extract business logics from UI layer, handle side effects and race conditions with ease, and declaratively describe application flow using async functions.

What's the goal?

Throughout my career I've worked with many React projects and saw different approaches to state management. The worst, IMO is handling logics with React hooks, since it breaks separation of concerns principle by mixing business logics with UI layer. Another problem is that all those hooks are dependant on each other, leading to redundant re-renders and stale props, which you have to solve with useRef, etc. I am pretty sure most of you faced these problems. But why do those problems exist at all?
I hope, after reading all the parts which I plan to write here, you will see that state management can actually be very simple.

How it works?

Fundamental part of Awai is thennable object, which plays role of event emitter. Thennable is an object which implements then method and can be used as a Promise.

const thennable = {
  awaiters: [],

  then(onfulfilled) {
    this.awaiters.push(onfulfilled);
  },

  emit(value) {
    for (const resolve of awaiters) {
      resolve(value);
    }
  }
};

As soon as it is used as a promise, then method is called receiving resolving callback as an argument. The callback should be called when thennable resolves.

For example, if you write await thennable, the callback resolving this await will land in awaiters array of our object, and it's up to us when to call it.

Same as we can await promise multiple times, I've tried to do it with custom thennable, and this is how I came to an idea of re-resolving the same thennable object multiple times.

Once classic JS promise is settled, it resolves with the settled value as soon as you await it again. With custom implementation we resolve all the awaiters, and cleanup the array, making further subscriptions to thennable possible without resolving them right away.

Now let's create a class that creates thennable re-resolvable event. It will be named AwaiEvent to be aligned with naming inside of the library.

class AwaiEvent {
  #awaiters = [];

  then(onfulfilled) {
    this.#awaiters.push(onfulfilled);
  }

  emit(value) {
    const awaiters = this.#awaiters;
    this.#awaiters = [];

    for (const resolve of awaiters) {
      resolve(value);
    }
  }
}

This is how thennable can resolve with different values:

const event = new AwaiEvent();

setTimeout(() => event.emit('hello'), 100);
setTimeout(() => event.emit('awai'), 200);

const value1 = await event;
const value2 = await event;

console.log(`${value1} ${value2}`); // hello awai

So exciting! We can now use this event in order to replace classical event emitters. How? Just await it in the loop 😎. You can also combine this event with other promises using Promise.race, Promise.all, etc.

const event = new AwaiEvent();

while(true) {
  const value = await event;
  console.log(event);  
}

Any time you call event.emit(...) the emitted value will be logged.

By the way, this is exactly how event listening was implemented in the early versions of Awai: GitHub commit 😄.
Right now this util is called scenario, which has drastically evolved, and can be used in a variety of different ways. But let's not cover its functionality in this part. Nevertheless, feel free to check the docs.

How is state node implemented?

State is a very simple object, which has get. & set methods, and events property. get method returns a current value. set method updates the value inside of the object and emits the thennable event we created above. Have a look at the basic state node implementation:

const state = (initialValue) => {
  let value = initialValue;

  const events = {
    changed: new AwaiEvent()
  };

  const get = () => value;

  const set = (newValue) => {
    value = newValue;
    events.changed.emit(newValue);
  };

  return { events, get, set };
};

Easy, right? Now, if we create a state node, we can react to its events, and this is a great start for a state management library.

How to connect this weirdo to React?

Let's write a very simple React hook, which listens to every emit and updates React state once our event is emitted.

const useStateValue = (stateNode) => {
  const initialValue = stateNode.get();
  const [value, setValue] = useState(initialValue);

  useEffect(() => {
    let mounted = true;

    const listen = async () => {
      while (mounted) {
        const newValue = await stateNode.events.changed;

        if (mounted) {
          setValue(newValue);
        }
      }
    };

    listen();

    return () => {
      mounted = false;
    };
  }, [stateNode]);

  return value;
};

Finally we can use our so far primitive state manager library with React:

const counterState = state(0);

const increment = () => {
  counterState.set(counterState.get() + 1);
};

const Counter = () => {
  const counter = useStateValue(counterState);

  return (
    <div>
      <p>{counter}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
};

Summary

I hope you enjoyed the reading. Happy to answer your questions. See you in the next parts.

Here you can find a playground with the example we have created together: CodeSandbox.