@vouchington/request-contract-validation 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @vouchington/request-contract-validation
+
+Compile a caller supplied JSON Schema request bundle once, then validate body, header, path, and
+query carriers with Ajv and standard formats. Unknown operations throw; a known operation without
+a schema for a carrier accepts that carrier unchanged. Only supplied carriers are checked by
+`validateOperation`.
+The API is synchronous; asynchronous Ajv validators are rejected during construction.
+
+```ts
+import { RequestContractValidatorRegistry } from '@vouchington/request-contract-validation'
+
+const registry = new RequestContractValidatorRegistry({
+  components: {},
+  operations: { 'POST:/items': { body: { type: 'object', required: ['name'] } } },
+})
+const error = registry.validateOperation('POST:/items', { body: { name: 'example' } })
+```
+
+Applications supply generated or hand-written contracts and decide authentication, authorization,
+rate limits, request lifecycle, HTTP status, and error mapping. Header names in object inputs are
+lowercased before validation; case-insensitive duplicates are rejected when a header contract is
+present. This package has no generated bundle or shared registry.

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+export type RequestCarrier = 'body' | 'header' | 'path' | 'query';
+export type RequestContract = Partial<Record<RequestCarrier, unknown>>;
+export type RequestContractsBundle = {
+    components: Record<string, unknown>;
+    operations: Record<string, RequestContract>;
+};
+export type RequestValidationError = {
+    message: string;
+};
+/** Compiles caller-owned request contracts once; callers choose the request boundary and error policy. */
+export declare class RequestContractValidatorRegistry {
+    private readonly validators;
+    constructor(bundle: RequestContractsBundle);
+    hasOperation(operation: string): boolean;
+    validateBody(operation: string, value: unknown): RequestValidationError | null;
+    validate(operation: string, carrier: RequestCarrier, value: unknown): RequestValidationError | null;
+    validateOperation(operation: string, input: Partial<Record<RequestCarrier, unknown>>): RequestValidationError | null;
+}

package/dist/index.mjs

@@ -0,0 +1,80 @@
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+const AjvCtor = Ajv;
+const installFormats = addFormats;
+const requestCarriers = ['body', 'header', 'path', 'query'];
+const duplicateHeaderNames = Symbol('duplicate header names');
+/** Compiles caller-owned request contracts once; callers choose the request boundary and error policy. */
+export class RequestContractValidatorRegistry {
+    validators = new Map();
+    constructor(bundle) {
+        if (!bundle || !isRecord(bundle.components) || !isRecord(bundle.operations)) {
+            throw new TypeError('Request contract bundle needs components and operations maps');
+        }
+        const ajv = new AjvCtor({ allErrors: false, strict: false, strictSchema: true });
+        installFormats(ajv);
+        for (const [name, schema] of Object.entries(bundle.components)) {
+            ajv.addSchema(schema, `#/components/schemas/${name}`);
+        }
+        for (const [operation, contract] of Object.entries(bundle.operations)) {
+            if (!isRecord(contract))
+                throw new TypeError(`Invalid request contract for ${operation}`);
+            const carriers = {};
+            for (const carrier of requestCarriers) {
+                if (Object.hasOwn(contract, carrier)) {
+                    const validator = ajv.compile(contract[carrier]);
+                    if ('$async' in validator && validator.$async) {
+                        throw new TypeError('Asynchronous request contracts are not supported');
+                    }
+                    carriers[carrier] = validator;
+                }
+            }
+            this.validators.set(operation, carriers);
+        }
+    }
+    hasOperation(operation) {
+        return this.validators.has(operation);
+    }
+    validateBody(operation, value) {
+        return this.validate(operation, 'body', value);
+    }
+    validate(operation, carrier, value) {
+        const validators = this.validators.get(operation);
+        if (!validators)
+            throw new Error(`No request contract for ${operation}`);
+        const validator = validators[carrier];
+        if (!validator)
+            return null;
+        const normalized = normalizeCarrierValue(carrier, value);
+        if (normalized !== duplicateHeaderNames && validator(normalized))
+            return null;
+        return { message: `Invalid request ${carrier}` };
+    }
+    validateOperation(operation, input) {
+        if (!this.hasOperation(operation))
+            throw new Error(`No request contract for ${operation}`);
+        for (const carrier of requestCarriers) {
+            if (!Object.hasOwn(input, carrier))
+                continue;
+            const error = this.validate(operation, carrier, input[carrier]);
+            if (error)
+                return error;
+        }
+        return null;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeCarrierValue(carrier, value) {
+    if (carrier !== 'header' || !isRecord(value))
+        return value;
+    const normalized = new Map();
+    for (const [name, headerValue] of Object.entries(value)) {
+        const key = name.toLowerCase();
+        if (normalized.has(key))
+            return duplicateHeaderNames;
+        normalized.set(key, headerValue);
+    }
+    return Object.fromEntries(normalized);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vouchington/request-contract-validation",
+  "version": "0.0.1",
+  "description": "Bundle-injected runtime validation of request contract carriers.",
+  "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/request-contract-validation#readme",
+  "bugs": {
+    "url": "https://github.com/vouchington/vouchington-platform/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/request-contract-validation"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}