Implementing JavaScript state machines using React Hooks.
npm install loxia> Implementing JavaScript state machines using React Hooks.
``
npm install loxia
I consider React Hooks to be particularly suitable for implementing state
machines. Based on this idea, I developed a
bookmark manager. It's UI makes
intensive use of the Hooks and patterns developed here and serves as a real
world test.
In general, all Hooks in this library are built to be used with any React Hooks
compliant implementation. That would be, for example,
Batis, Preact, and of course React. In the
usage examples, Batis is always used, but as an alternative, the analogous usage
with React is shown as a comment.
A transition is a function with special runtime behavior that can be used to
implement the correct behavior of the transition methods of a state machine. A
transition executes the passed callback once and returns true if its
dependencies have not changed, so it should depend on the state of the
associated state machine.
Usage example
`ts
import {Host} from 'batis'; // import * as React from 'react';
import {createTransitionHook} from 'loxia';
const useTransition = createTransitionHook(Host / React /);
function useLock(): Lock {
const [locked, setLocked] = Host / React /.useState(false);
const transition = useTransition(locked);
const lock = Host / React /.useCallback(
() => transition(() => setLocked(true)),
[transition],
);
const unlock = Host / React /.useCallback(
() => transition(() => setLocked(false)),
[transition],
);
return Host / React /.useMemo(
() => (locked ? {locked, unlock} : {locked, lock}),
[locked],
);
}
`
Type definitions
`ts`
function createTransitionHook(hooks: BatisHooks): UseTransition;
`ts`
type UseTransition = (
...dependencies: readonly [unknown, ...unknown[]]
) => Transition;
`ts`
type Transition = (callback?: () => void) => boolean;
A binding is a function that is tied to the life cycle of the Hook or component
it surrounds. Often React components are already unmounted and an associated
asynchronous operation should no longer have any effect. It is therefore useful
to bind the callback functions of Promise.then, Promise.catch, and alsosetTimeout.
Usage example
`ts
import {Host} from 'batis'; // import * as React from 'react';
import {createBinderHook} from 'loxia';
const useBinder = createBinderHook(Host / React /);
function useExample() {
const bind = useBinder();
Host / React /.useEffect(() => {
setTimeout(
bind(() => {
// ...
}),
);
});
}
`
Type definitions
`ts`
function createBinderHook(hooks: BatisHooks): UseBinder;
`ts`
type UseBinder = () => Bind;
`ts`
type Bind =
callback: TCallback,
) => Binding
`ts`
type Binding
...args: Parameters
) => boolean;
A receiver is a state machine which allows the reception of a signal in the form
of a promise passed as an argument. A receiver is always in one of the following
states receiving, successful, or failed. As long as the reference to the
passed promise remains the same, a receiver represents the state of the promise.
When a reference to a new promise is passed, the old promise no longer affects
the receiver state.
It makes sense to use a receiver if an asynchronous operation is based on user
input. If the user input changes in the meantime and a new asynchronous
operation overwrites the old one, the old one should no longer have any effect.
Usage example
`ts
import {Host} from 'batis'; // import * as React from 'react';
import {createReceiverHook} from 'loxia';
const useReceiver = createReceiverHook(Host / React /);
function useAsyncJsonData(url) {
const signal = Host / React /.useMemo(
() => fetch(url).then((response) => response.json()),
[url],
);
return useReceiver(signal);
}
`
Type definitions
`ts`
function createReceiverHook(hooks: BatisHooks): UseReceiver;
`ts`
type UseReceiver =
`ts
type Receiver
| ReceivingReceiver
| SuccessfulReceiver
| FailedReceiver;
interface ReceivingReceiver {
readonly state: 'receiving';
}
interface SuccessfulReceiver
readonly state: 'successful';
readonly value: TValue;
}
interface FailedReceiver {
readonly state: 'failed';
readonly error: unknown;
}
`
A sender is a state machine which allows to send exactly one signal at a time.
Type definitions
`ts`
function createSenderHook(hooks: BatisHooks): UseSender;
`ts`
type UseSender = () => Sender;
`ts
type Sender = IdleSender | SendingSender | FailedSender;
interface IdleSender {
readonly state: 'idle';
send(signal: Promise
}
interface SendingSender {
readonly state: 'sending';
}
interface FailedSender {
readonly state: 'failed';
readonly error: unknown;
send(signal: Promise
}
``