import { CatalogError, type CatalogErrorDefinition, type JsonValue } from "./errors.js"; /** * Mass-action guard (M005 / Pflichtenheft A.10.1). * * A bulk action that touches many records is "never armed directly": the user * first sees a preview with the concrete impact ("würde 1.400 Personen betreffen, * hier die ersten 5: …") and must explicitly confirm. This module is the generic, * pure cross-cutting guard for that handshake; the caller computes the affected * count + sample (a query) and threads the decision into its action. */ export type MassActionPolicy = { /** Above this affected count, explicit user confirmation is required (A.10.1). */ confirmThreshold: number; /** Above this affected count the action is blocked entirely. Omit for no hard cap. */ hardLimit?: number; }; export type MassActionPreview = { readonly affected: number; readonly sample: readonly T[]; readonly requiresConfirmation: boolean; readonly exceedsHardLimit: boolean; }; export type MassActionInput = { /** Number of records the action would affect right now. */ affected: number; policy: MassActionPolicy; /** * The affected count the user saw and confirmed. Must equal the current * `affected` to proceed past the confirmation threshold — this rejects * scope-drift (confirming a small preview, then applying to a larger set). */ confirmedAffected?: number; }; export type MassActionDecision = | { readonly status: "allowed"; readonly affected: number; readonly confirmed: boolean } | { readonly status: "requires_confirmation"; readonly affected: number; readonly confirmThreshold: number } | { readonly status: "blocked"; readonly reason: "exceeds_hard_limit"; readonly affected: number; readonly hardLimit: number }; export const massActionErrors = { confirmationRequired: { code: "foundation.mass_action_confirmation_required", status: 409, i18nKey: "foundation.errors.massActionConfirmationRequired", }, exceedsLimit: { code: "foundation.mass_action_exceeds_limit", status: 422, i18nKey: "foundation.errors.massActionExceedsLimit", }, } satisfies Record; const DEFAULT_SAMPLE_SIZE = 5; /** * Build the preview shown to the user before a mass action: the affected count, * a bounded sample of the affected items, and whether confirmation / a hard cap * applies. The caller supplies the already-fetched `items`. */ export function previewMassAction(input: { affected: number; items?: readonly T[]; sampleSize?: number; policy: MassActionPolicy; }): MassActionPreview { const sampleSize = input.sampleSize ?? DEFAULT_SAMPLE_SIZE; const sample = (input.items ?? []).slice(0, Math.max(0, sampleSize)); const exceedsHardLimit = typeof input.policy.hardLimit === "number" && input.affected > input.policy.hardLimit; const requiresConfirmation = !exceedsHardLimit && input.affected > input.policy.confirmThreshold; return { affected: input.affected, sample, requiresConfirmation, exceedsHardLimit }; } /** Pure policy decision for a mass action. */ export function evaluateMassAction(input: MassActionInput): MassActionDecision { const { affected, policy, confirmedAffected } = input; if (typeof policy.hardLimit === "number" && affected > policy.hardLimit) { return { status: "blocked", reason: "exceeds_hard_limit", affected, hardLimit: policy.hardLimit }; } if (affected <= policy.confirmThreshold) { return { status: "allowed", affected, confirmed: false }; } if (confirmedAffected === affected) { return { status: "allowed", affected, confirmed: true }; } return { status: "requires_confirmation", affected, confirmThreshold: policy.confirmThreshold }; } /** * Assert a mass action may proceed, throwing a `CatalogError` otherwise: * `exceedsLimit` (422) when over the hard cap, `confirmationRequired` (409) when * the user has not confirmed the current affected count. Returns the decision on * success. */ export function assertMassActionAllowed(input: MassActionInput, details?: Record): MassActionDecision { const decision = evaluateMassAction(input); if (decision.status === "blocked") { throw new CatalogError(massActionErrors.exceedsLimit, { affected: decision.affected, hardLimit: decision.hardLimit, ...details }); } if (decision.status === "requires_confirmation") { throw new CatalogError(massActionErrors.confirmationRequired, { affected: decision.affected, confirmThreshold: decision.confirmThreshold, ...details, }); } return decision; }