Use operation history and undo/redo in React
The @cratis/choreography package is the frontend companion to the operation history and undo/redo engine. It has no dependency on a particular application: you give it a transport, and build whatever history or undo controls you need on top.
The backend is authoritative. The history shows which operation an undo would reverse and whether it is currently safe, but undo and redo are still validated on the server when they are requested, and a conflicting change comes back as a blocked outcome rather than an error.
Map the engine to HTTP
Section titled “Map the engine to HTTP”The package ships an HTTP transport for a host that exposes IOperationEngine on three routes. Choreography does not map them for you, because authorization and the actor’s identity are the host’s to decide.
| Route | Calls | Returns |
|---|---|---|
GET {baseUrl}/history?scope=&actor= |
GetHistory(scope, actor) |
the OperationHistoryItem list, oldest first |
POST {baseUrl}/undo with { scope, actor } |
Undo(scope, actor) |
an OperationOutcome |
POST {baseUrl}/redo with { scope, actor } |
Redo(scope, actor) |
an OperationOutcome |
Write JSON with camelCase names and enums as strings. A Blocked, NothingToUndo or NothingToRedo outcome is a normal 200 answer. Take the actor from the authenticated user rather than trusting the request body.
Create the client
Section titled “Create the client”import { OperationHistoryClient, createHttpTransport } from '@cratis/choreography';
const client = new OperationHistoryClient(createHttpTransport({ baseUrl: '/api/operations', headers: () => ({ Authorization: `Bearer ${getToken()}` })}));Any object that implements OperationHistoryTransport works in place of the HTTP one. If your application has a push channel, implement the optional subscribe method and the hooks re-read when it fires.
Show the history and undo
Section titled “Show the history and undo”import { useOperationHistory, useRedo, useUndo } from '@cratis/choreography/react';
export const HistoryControls = ({ scope, actor }: { scope: string; actor: string }) => { const history = useOperationHistory({ client, scope, actor }); const undo = useUndo({ client, scope, actor }); const redo = useRedo({ client, scope, actor });
return ( <> <button disabled={!history.canUndo || undo.isPending} onClick={undo.execute}>Undo</button> <button disabled={!history.canRedo || redo.isPending} onClick={redo.execute}>Redo</button> {history.nextUndo?.blockedReason && <p>{history.nextUndo.blockedReason}</p>} {undo.outcome?.kind === 'Blocked' && <p>{undo.outcome.reason}</p>} {undo.error && <p>Undo could not be completed: {undo.error.message}</p>} </> );};useOperationHistoryreturns the items,isLoading,error, and thenextUndoandnextRedoitems with their blocked reasons. A failed refresh keeps the previous items. A response that arrives after the scope or actor changed is ignored.useUndoanduseRedoreturnexecute,isPending,outcome,errorandreset. A blocked request is anoutcome;erroris only for a request that could not be completed. A request already in flight is not sent twice.- After an undo or redo through the same client, mounted history hooks for that scope and actor re-read. After a forward operation made through your own commands, call
client.notifyChanged(scope, actor), or passpollIntervalInMillisecondstouseOperationHistory.
Operations are the backend’s grouping, not something to rebuild from events: eventSequenceNumbers on an item are references for display and linking only.