defineFlow
Declare a record’s lifecycle once: which status may move where, and which roles may move it. The server blocks illegal moves, the UI shows only legal buttons.
Usage
app/shared/order.ts
import { defineFlow } from "manh/flow";
import { OrderStatus } from "./order-status"; // defineEnum
export const OrderFlow = defineFlow({
new: { confirmed: ["sales", "admin"], cancelled: ["sales", "admin"] },
confirmed: { shipping: ["warehouse", "admin"], cancelled: ["admin"] },
shipping: { done: ["warehouse", "admin"] },
done: {},
cancelled: {},
}, OrderStatus);app/orders/repository.ts
import { fail } from "manh/errors";
import { OrderFlow } from "app/shared/order";
export async function moveOrder(user, id: number, to: string) {
const [row] = await db.select().from(orders).where(eq(orders.id, id));
if (!row) fail(404, "Order not found", "NOT_FOUND");
OrderFlow.assert(user, row.status, to); // illegal move: 409, wrong role: 403
const [updated] = await db.update(orders).set({ status: to }).where(eq(orders.id, id)).returning();
return updated;
}Signature
manh/flow
function defineFlow<const T extends Record<string, Record<string, readonly string[] | true>>>(
def: T,
labels?: { label(v: string): string },
): {
readonly states: S[];
next(from: string, role?: string | null): S[];
can(role: string | null | undefined, from: string, to: string): boolean;
isFinal(status: string): boolean;
assert(user: { role?: string } | null | undefined, from: string, to: string): void;
move(user: { id?: number | string; name?: string; role?: string } | null | undefined, from: string, to: string, note?: string | null):
{ from: string; to: S; actorId: number | string | null; actorName: string | null; note: string | null; at: number };
};
// S = the keys of defParameters
def: an object with one key per status. Each value lists the next moves: target status → the roles allowed to make that move, ortruefor any signed-in user. A final status has{}.labels: the status enum made with defineEnum. With it, an illegal-move error names the statuses, such as: Không thể chuyển từ “Mới” sang “Đã giao”, instead of the keysnew,done.
Returns
states: every status.next(from, role?): the statuses reachable fromfrom. With arole, only the moves that role may make; anullrole (signed out) gets no moves.can(role, from, to): whether this role may movefrom→to.isFinal(status):truewhen the status has no moves.assert(user, from, to): throws 409 with codeFLOW_ILLEGALwhen the move doesn’t exist, 403 with codeFORBIDDENfor the wrong role. The error body matchesfail:{ error, message, code }.move(user, from, to, note?): runsassert, then returns the history row{ from, to, actorId, actorName, note, at }for you to insert into your own history table.
Examples
Show only the buttons this user may press:
app/orders/[id]/page.tsx
const { user } = useSession();
const moves = OrderFlow.next(order.status, user?.role ?? null);
return moves.map((to) => <Button key={to} onClick={() => move(order.id, { to })}>{OrderStatus.label(to)}</Button>);Record history together with the status change:
app/orders/repository.ts
const event = OrderFlow.move(user, row.status, to, note);
await db.insert(orderEvents).values({ orderId: id, ...event });Don’t keep a second copy of the move table in a page or a handler.
Next steps
- defineEnum: labels and colours for each status.
- Sign-in and permissions: user roles.
Last updated