Skip to Content

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 def

Parameters

  • def: an object with one key per status. Each value lists the next moves: target status → the roles allowed to make that move, or true for 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 keys new, done.

Returns

  • states: every status.
  • next(from, role?): the statuses reachable from from. With a role, only the moves that role may make; a null role (signed out) gets no moves.
  • can(role, from, to): whether this role may move from → to.
  • isFinal(status): true when the status has no moves.
  • assert(user, from, to): throws 409 with code FLOW_ILLEGAL when the move doesn’t exist, 403 with code FORBIDDEN for the wrong role. The error body matches fail: { error, message, code }.
  • move(user, from, to, note?): runs assert, 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

Last updated