@vouchington/utils 0.4.1 → 0.5.0

package/README.md

@@ -9,6 +9,7 @@ import { createMoneyCatalog } from '@vouchington/utils/money'
 import { serializeCookie } from '@vouchington/utils/cookies'
 import { bestAcceptLanguageMatch } from '@vouchington/utils/language-tags'
 import { createMessageTranslator } from '@vouchington/utils/message-catalog'
+import { createReportInputParser } from '@vouchington/utils/moderation'
 ```
 
 ## Subpaths
@@ -35,6 +36,8 @@ import { createMessageTranslator } from '@vouchington/utils/message-catalog'
   formatting, text normalization, title casing, and word/sentence helpers.
 - `gtin`, `bigint-ids`, and `validation`: GTIN predicates, canonical positive PostgreSQL bigint IDs,
   and basic email/UUID predicates.
+- `moderation`: caller-configured report target, reason, identifier, note, and cross-field input
+  validation. Applications own catalogs, policy, error mapping, persistence, and HTTP behavior.
 - `query` and `query-string`: generic array/boolean/number parsing, bounded integer parsing, and
   query-string serialization. Cursor parsing intentionally belongs to `@vouchington/pagination`.
 - `slugs` and `urls`: ASCII-only slugification and URL/hostname primitives. URL hostname helpers

package/dist/moderation.d.mts

@@ -0,0 +1,34 @@
+interface ReportTarget<TType extends string, TId> {
+    type: TType;
+    id: TId;
+}
+interface ReportDraft<TType extends string, TId, TReason extends string> {
+    target: ReportTarget<TType, TId>;
+    reason: TReason;
+    note: string | null;
+}
+export interface ReportInputConfig<TType extends string, TId, TReason extends string> {
+    targetTypes: readonly TType[];
+    reasons: readonly TReason[];
+    parseTargetId(value: string): TId | null;
+    maxNoteLength: number;
+    validate?(draft: ReportDraft<TType, TId, TReason>): void;
+}
+interface RawReportInput {
+    targetType?: unknown;
+    targetId?: unknown;
+    reason?: unknown;
+    note?: unknown;
+}
+export interface ReportInputParser<TType extends string, TId, TReason extends string> {
+    parse(raw: RawReportInput): ReportDraft<TType, TId, TReason>;
+    readonly targetTypes: readonly TType[];
+    readonly reasons: readonly TReason[];
+}
+export type ReportValidationCode = 'invalid_target_type' | 'invalid_target_identifier' | 'invalid_reason' | 'invalid_note' | 'note_too_long';
+export declare class ReportValidationError extends Error {
+    readonly code: ReportValidationCode;
+    constructor(code: ReportValidationCode, message: string);
+}
+export declare function createReportInputParser<TType extends string, TId, TReason extends string>(config: ReportInputConfig<TType, TId, TReason>): ReportInputParser<TType, TId, TReason>;
+export {};

package/dist/moderation.mjs

@@ -0,0 +1,49 @@
+export class ReportValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ReportValidationError';
+        this.code = code;
+    }
+}
+export function createReportInputParser(config) {
+    const targetTypes = readonlyCatalog(config.targetTypes, 'targetTypes');
+    const reasons = readonlyCatalog(config.reasons, 'reasons');
+    if (!Number.isSafeInteger(config.maxNoteLength) || config.maxNoteLength < 0)
+        throw new TypeError('maxNoteLength must be a non-negative safe integer');
+    return {
+        targetTypes,
+        reasons,
+        parse(raw) {
+            const targetType = enumValue(raw.targetType, targetTypes, 'invalid_target_type', 'target type');
+            if (typeof raw.targetId !== 'string')
+                invalid('invalid_target_identifier', 'target identifier');
+            const targetId = config.parseTargetId(raw.targetId);
+            if (targetId === null)
+                invalid('invalid_target_identifier', 'target identifier');
+            const reason = enumValue(raw.reason, reasons, 'invalid_reason', 'reason');
+            if (raw.note !== undefined && raw.note !== null && typeof raw.note !== 'string')
+                invalid('invalid_note', 'note');
+            if (typeof raw.note === 'string' && raw.note.length > config.maxNoteLength)
+                throw new ReportValidationError('note_too_long', 'Note is too long');
+            const note = typeof raw.note === 'string' ? raw.note.trim() || null : null;
+            const draft = { target: { type: targetType, id: targetId }, reason, note };
+            config.validate?.(draft);
+            return draft;
+        },
+    };
+}
+function readonlyCatalog(values, name) {
+    if (values.length === 0 ||
+        values.some((value) => typeof value !== 'string' || value.length === 0))
+        throw new TypeError(`${name} must contain non-empty strings`);
+    return Object.freeze([...new Set(values)]);
+}
+function enumValue(value, catalog, code, name) {
+    if (typeof value !== 'string' || !catalog.includes(value))
+        invalid(code, name);
+    return value;
+}
+function invalid(code, name) {
+    throw new ReportValidationError(code, `Invalid ${name}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -130,6 +130,11 @@
       "import": "./dist/validation.mjs",
       "default": "./dist/validation.mjs"
     },
+    "./moderation": {
+      "types": "./dist/moderation.d.mts",
+      "import": "./dist/moderation.mjs",
+      "default": "./dist/moderation.mjs"
+    },
     "./async": {
       "types": "./dist/async.d.mts",
       "import": "./dist/async.mjs",