API Reference
Complete API surface of AuthRail.
This section documents the public API of AuthRail.
createRail
createRail<Ctx>(
name: string,
middleware: Middleware<Ctx>[],
options?: {
debug?: boolean;
}
): Rail<Ctx>Creates a new rail instance.
Parameters:
name— identifier used for debuggingmiddleware— ordered array of middlewareoptions.debug— enables console logging during evaluation
Returns:
{
name: string;
evaluate(ctx: Ctx): Promise<RailResult<Ctx>>;
}Rail.evaluate
rail.evaluate(context: Ctx): Promise<RailResult<Ctx>>Evaluates middleware sequentially and returns:
type RailResult<Ctx> = {
decision: {
type: "allow" | "deny" | "redirect";
to?: string;
reason?: string;
};
context: Ctx;
};Evaluation is always asynchronous.
Middleware
type Middleware<Ctx> =
| ((ctx: Readonly<Ctx>) =>
| MiddlewareResult<Ctx>
| void
| Promise<MiddlewareResult<Ctx> | void>);type MiddlewareResult<Ctx> = {
decision?: {
type: "allow" | "deny" | "redirect";
to?: string;
reason?: string;
};
context?: Partial<Ctx>;
};Rules:
- Returning
voidcontinues execution. - Returning
decisionshort-circuits execution. - Returning
contextenriches the working context.
requireAuth
ts requireAuth(redirectTo: string): Middleware
Redirects if ctx.user is falsy.
requireRole
ts requireRole(role: string): Middleware
Denies if ctx.user.role does not match.
allowIf
allowIf(predicate: (ctx: Ctx) => boolean): MiddlewareDenies if predicate returns false.
blockIf
blockIf(predicate: (ctx: Ctx) => boolean): MiddlewareDenies if predicate returns true.
React Utilities
These are optional helpers for React environments.
RailBoundary
<RailBoundary
rail={rail}
context={ctx}
fallback={ReactNode}
denied={ReactNode}
onRedirect={(to) => void}
>
{children}
</RailBoundary>Evaluates a rail and renders based on decision.
useRail
useRail<Ctx>(rail: Rail<Ctx>, context: Ctx): {
status: "idle" | "loading" | "done";
decision: Decision | null;
context: Ctx | null;
}Hook for imperative evaluation inside React components.
protect
protect<P>(
rail: Rail<any>,
getContext: (props: P) => any,
onRedirect?: (to: string) => void,
fallback?: ReactNode,
denied?: ReactNode
): (Component: ComponentType<P>) => ComponentType<P>Higher-order component wrapper for declarative route-level or component-level protection.