Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/foundation/src/mass-action.ts
T

112 lines
4.5 KiB
TypeScript

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<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;
}