112 lines
4.5 KiB
TypeScript
112 lines
4.5 KiB
TypeScript
import { CatalogError, type CatalogErrorDefinition, type JsonValue } from "./errors.js";
|
|
|
|
/**
|
|
* Mass-action guard (M005 contract).
|
|
*
|
|
* 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<T = unknown> = {
|
|
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<string, CatalogErrorDefinition>;
|
|
|
|
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<T>(input: {
|
|
affected: number;
|
|
items?: readonly T[];
|
|
sampleSize?: number;
|
|
policy: MassActionPolicy;
|
|
}): MassActionPreview<T> {
|
|
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<string, JsonValue>): 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;
|
|
}
|