Types

Type definitions for contexts, rules, policies, and results in Bantai.

ContextDefinition

Type representing a context definition.

type ContextDefinition<
  T extends z.ZodRawShape,
  TTools extends Record<string, unknown> = {}
> = {
  schema: z.ZodObject<T>;
  defaultValues: Partial<z.infer<z.ZodObject<T>>>;
  tools: TTools;
}

Properties:

• schema: Zod object schema
• defaultValues: Partial default values for context fields
• tools: Tools object available to rules

RuleDefinition

Type representing a rule definition.

type RuleDefinition<
  TContext extends ContextDefinition<z.ZodRawShape, Record<string, unknown>>,
  TName extends string = string
> = {
  name: TName;
  evaluate: (input: z.infer<z.ZodObject<ExtractShape<TContext['schema']>>>) => Promise<RuleResult>;
  hooks: {
    onAllow?: RuleHookFnAsync<ExtractShape<TContext['schema']>, ExtractTools<TContext>>;
    onDeny?: RuleHookFnAsync<ExtractShape<TContext['schema']>, ExtractTools<TContext>>;
  };
}

Properties:

• name: Rule identifier
• evaluate: Async function that evaluates the rule
• hooks: Optional hooks for side effects

PolicyDefinition

Type representing a policy definition.

type PolicyDefinition<
  TContext extends ContextDefinition<z.ZodRawShape, Record<string, unknown>>,
  TName extends string,
  TRules extends readonly RuleDefinition<TContext, string>[]
> = {
  name: TName;
  rules: Map<string, TRules[number]> & {
    get<K extends ExtractRuleName<TRules[number]>>(key: K): RulesMap<TRules>[K] | undefined;
    has<K extends ExtractRuleName<TRules[number]>>(key: K): boolean;
  };
  context: TContext;
  options: {
    defaultStrategy: PolicyStrategy;
  };
}

Properties:

• name: Policy identifier
• rules: Map of rules with type-safe accessors
• context: Context used by the policy
• options: Policy configuration including default strategy

RuleResult

Type representing the result of a rule evaluation.

type RuleResult = {
  allowed: boolean;
  reason: string | null;
  skipped: boolean;
  meta?: Record<string, unknown>;
}

Properties:

• allowed: true if rule allows, false if rule denies
• reason: Optional reason message
• skipped: true if rule was skipped, false otherwise
• meta?: Optional metadata record for additional context

PolicyResult

Type representing the result of a policy evaluation.

type PolicyResult = {
  decision: 'allow' | 'deny';
  isAllowed: boolean;
  reason: 'policy_violated' | 'policy_enforced';
  violatedRules: ViolatedRule[];
  evaluatedRules: EvaluatedRule[];
  strategy: 'preemptive' | 'exhaustive';
}

Properties:

• decision: Final decision ('allow' or 'deny')
• isAllowed: Boolean convenience property (true when decision === 'allow')
• reason: Reason for the decision
  • 'policy_enforced': All rules passed
  • 'policy_violated': One or more rules failed
• violatedRules: Array of violated rules
• evaluatedRules: Array of all evaluated rules (both passed and failed)
• strategy: Strategy used for evaluation

ViolatedRule

Type representing a violated rule.

type ViolatedRule = {
  name: string;
  result: RuleResult;
}

Properties:

• name: Name of the violated rule
• result: Rule result that caused the violation

EvaluatedRule

Type representing an evaluated rule (both passed and failed).

type EvaluatedRule = {
  rule: RuleDefinition;
  result: RuleResult;
}

Properties:

• rule: The rule definition that was evaluated
• result: The result of the rule evaluation

PolicyStrategy

Type representing evaluation strategy.

type PolicyStrategy = 'preemptive' | 'exhaustive'

Values:

• 'preemptive': Stops at first violation (fail-fast)
• 'exhaustive': Collects all violations

Related Documentation

• Functions - Functions that use these types
• Utility Types - Helper types for working with contexts