@theshelf/validation 0.0.1

package/README.md

@@ -0,0 +1,102 @@
+
+# Validation | The Shelf
+
+The validation package provides a universal interaction layer with an actual data validation solution.
+
+## Installation
+
+```bash
+npm install @theshelf/validation
+```
+
+## Implementations
+
+Currently, there is only one implementation:
+
+* **Zod** - implementation for the currently popular Zod library.
+
+## Configuration
+
+The used implementation needs to be configured in the `.env` file.
+
+```env
+VALIDATION_IMPLEMENTATION="zod"
+```
+
+## How to use
+
+An instance of the configured validator implementation can be imported for performing validation operations.
+
+```ts
+import validator from '@theshelf/validation';
+
+// Perform operations with the validator instance
+```
+
+### Operations
+
+```ts
+import validator, { ValidationSchema, ValidationResult } from '@theshelf/validation';
+
+const data = {
+    name: 'John Doe',
+    age: '42'
+};
+
+const schema: ValidationSchema = {
+    name: { message: 'Invalid name', STRING: { required: true, minLength: 4, maxLength: 40 } },
+    nickname: { message: 'Invalid nickname', STRING: { required: false, , pattern: '^[a-z]+$' } },
+    age: { message: 'Invalid age', NUMBER: { required: true, minValue: 18, maxValue: 99 } }
+};
+
+// Validate data
+const result: ValidationResult = validator.validate(data, schema);
+```
+
+### Validation scheme options
+
+A basic validation scheme has the following structure.
+
+```ts
+const schema: ValidationSchema = {
+    fieldName1: { TYPE: { /* type options */ } },
+    fieldName2: { TYPE: { /* type options */ } },
+    ...
+}
+```
+
+**Note** that a custom validation error `message` can optionally be set per field.
+
+The following types are supported:
+
+* **STRING**
+  * `required: boolean`
+  * `minLength?: number`
+  * `maxLength?: number`
+  * `pattern?: string`
+* **NUMBER**
+  * `required: boolean`
+  * `minValue?: number`
+  * `maxValue?: number`
+* **ARRAY**
+  * `required: boolean`
+  * `minLength?: number`
+  * `maxLength?: number`
+  * `validations?: Partial<Validation>`
+* **BOOLEAN**
+  * `required: boolean`
+* **DATE**
+  * `required: boolean`
+* **UUID**
+  * `required: boolean`
+* **EMAIL**
+  * `required: boolean`
+* **URL**
+  * `required: boolean`
+
+### Validation result structure
+
+The validation result has two fields:
+
+* **invalid** - boolean indicating if at least one of the fields is invalid.
+* **messages** - map containing the validation error messages per field.

package/dist/definitions/ValidationResult.d.ts

@@ -0,0 +1,6 @@
+export default class ValidationResult {
+    #private;
+    constructor(invalid: boolean, messages?: Map<string, string>);
+    get invalid(): boolean;
+    get messages(): Map<string, string>;
+}

package/dist/definitions/ValidationResult.js

@@ -0,0 +1,10 @@
+export default class ValidationResult {
+    #invalid;
+    #messages;
+    constructor(invalid, messages = new Map()) {
+        this.#invalid = invalid;
+        this.#messages = messages;
+    }
+    get invalid() { return this.#invalid; }
+    get messages() { return this.#messages; }
+}

package/dist/definitions/constants.d.ts

@@ -0,0 +1,13 @@
+declare const FieldTypes: {
+    STRING: string;
+    NUMBER: string;
+    BOOLEAN: string;
+    DATE: string;
+    UUID: string;
+    EMAIL: string;
+    ARRAY: string;
+    URL: string;
+};
+declare const MAX_EMAIL_LENGTH = 320;
+declare const MAX_URL_LENGTH = 2083;
+export { FieldTypes, MAX_EMAIL_LENGTH, MAX_URL_LENGTH };

package/dist/definitions/constants.js

@@ -0,0 +1,14 @@
+const FieldTypes = {
+    STRING: 'string',
+    NUMBER: 'number',
+    BOOLEAN: 'boolean',
+    DATE: 'date',
+    UUID: 'uuid',
+    EMAIL: 'email',
+    ARRAY: 'array',
+    URL: 'url'
+};
+Object.freeze(FieldTypes);
+const MAX_EMAIL_LENGTH = 320;
+const MAX_URL_LENGTH = 2083;
+export { FieldTypes, MAX_EMAIL_LENGTH, MAX_URL_LENGTH };

package/dist/definitions/interfaces.d.ts

@@ -0,0 +1,5 @@
+import type ValidationResult from './ValidationResult';
+import type { ValidationSchema } from './types';
+export interface Validator {
+    validate(data: unknown, schema: ValidationSchema): ValidationResult;
+}

package/dist/definitions/interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/definitions/types.d.ts

@@ -0,0 +1,42 @@
+import type { FieldTypes } from './constants';
+export type ValidationType = keyof typeof FieldTypes;
+type DefaultProperties = {
+    required: boolean;
+};
+export type StringProperties = DefaultProperties & {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+};
+export type NumberProperties = DefaultProperties & {
+    minValue?: number;
+    maxValue?: number;
+};
+export type ArrayProperties = DefaultProperties & {
+    minLength?: number;
+    maxLength?: number;
+    validations?: Partial<Validation>;
+};
+export type BooleanProperties = DefaultProperties;
+export type DateProperties = DefaultProperties;
+export type UUIDProperties = DefaultProperties;
+export type EmailProperties = DefaultProperties;
+export type URLProperties = DefaultProperties & {
+    protocols?: string[];
+};
+export type Message = {
+    message: string;
+};
+export type ValidationTypes = {
+    STRING: StringProperties;
+    NUMBER: NumberProperties;
+    BOOLEAN: BooleanProperties;
+    DATE: DateProperties;
+    UUID: UUIDProperties;
+    EMAIL: EmailProperties;
+    ARRAY: ArrayProperties;
+    URL: URLProperties;
+};
+export type Validation = Partial<ValidationTypes | Message>;
+export type ValidationSchema = Record<string, Validation>;
+export {};

package/dist/definitions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/errors/UnknownImplementation.d.ts

@@ -0,0 +1,4 @@
+import ValidationError from './ValidationError';
+export default class UnknownImplementation extends ValidationError {
+    constructor(name: string);
+}

package/dist/errors/UnknownImplementation.js

@@ -0,0 +1,6 @@
+import ValidationError from './ValidationError';
+export default class UnknownImplementation extends ValidationError {
+    constructor(name) {
+        super(`Unknown validation implementation: ${name}`);
+    }
+}

package/dist/errors/UnknownValidator.d.ts

@@ -0,0 +1,4 @@
+import ValidationError from './ValidationError';
+export default class UnknownValidator extends ValidationError {
+    constructor(name: string);
+}

package/dist/errors/UnknownValidator.js

@@ -0,0 +1,6 @@
+import ValidationError from './ValidationError';
+export default class UnknownValidator extends ValidationError {
+    constructor(name) {
+        super(`Unknown validator: ${name}`);
+    }
+}

package/dist/errors/ValidationError.d.ts

@@ -0,0 +1,3 @@
+export default class ValidationError extends Error {
+    constructor(message?: string);
+}

package/dist/errors/ValidationError.js

@@ -0,0 +1,5 @@
+export default class ValidationError extends Error {
+    constructor(message) {
+        super(message ?? 'Validation error');
+    }
+}

package/dist/implementation.d.ts

@@ -0,0 +1,3 @@
+import type { Validator } from './definitions/interfaces';
+declare const _default: Validator;
+export default _default;

package/dist/implementation.js

@@ -0,0 +1,12 @@
+import UnknownImplementation from './errors/UnknownImplementation';
+import createZod from './implementations/zod/create';
+const implementations = new Map([
+    ['zod', createZod]
+]);
+const DEFAULT_VALIDATION_IMPLEMENTATION = 'zod';
+const implementationName = process.env.VALIDATION_IMPLEMENTATION ?? DEFAULT_VALIDATION_IMPLEMENTATION;
+const creator = implementations.get(implementationName.toLowerCase());
+if (creator === undefined) {
+    throw new UnknownImplementation(implementationName);
+}
+export default creator();

package/dist/implementations/zod/Zod.d.ts

@@ -0,0 +1,8 @@
+import ValidationResult from '../../definitions/ValidationResult';
+import type { Validator } from '../../definitions/interfaces';
+import type { ValidationSchema } from '../../definitions/types';
+export default class Zod implements Validator {
+    #private;
+    constructor();
+    validate(data: unknown, schema: ValidationSchema): ValidationResult;
+}

package/dist/implementations/zod/Zod.js

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import ValidationResult from '../../definitions/ValidationResult';
+import { FieldTypes, MAX_EMAIL_LENGTH, MAX_URL_LENGTH } from '../../definitions/constants';
+import UnknownValidator from '../../errors/UnknownValidator';
+// Zod is so type heavy that we've chosen for inferred types to be used.
+// This is a trade-off between readability and verbosity.
+export default class Zod {
+    #validations = new Map();
+    constructor() {
+        this.#validations.set(FieldTypes.STRING, (value) => this.#validateString(value));
+        this.#validations.set(FieldTypes.NUMBER, (value) => this.#validateNumber(value));
+        this.#validations.set(FieldTypes.BOOLEAN, (value) => this.#validateBoolean(value));
+        this.#validations.set(FieldTypes.DATE, (value) => this.#validateDate(value));
+        this.#validations.set(FieldTypes.UUID, (value) => this.#validateUuid(value));
+        this.#validations.set(FieldTypes.EMAIL, (value) => this.#validateEmail(value));
+        this.#validations.set(FieldTypes.ARRAY, (value) => this.#validateArray(value));
+        this.#validations.set(FieldTypes.URL, (value) => this.#validateUrl(value));
+    }
+    validate(data, schema) {
+        const validator = this.#buildValidator(schema);
+        const result = validator.safeParse(data);
+        if (result.success === false) {
+            const issues = result.error.issues;
+            const messages = this.#getMessages(issues, schema);
+            return new ValidationResult(true, messages);
+        }
+        return new ValidationResult(false);
+    }
+    #buildValidator(schema) {
+        return Object.entries(schema)
+            .reduce((partialSchema, [key, value]) => {
+            const fieldValidation = this.#getValidation(value);
+            return partialSchema.extend({ [key]: fieldValidation });
+        }, z.object({})).strict();
+    }
+    #getValidation(schema) {
+        for (const [key, validation] of Object.entries(schema)) {
+            if (key === 'message')
+                continue;
+            const validator = this.#validations.get(key.toLocaleLowerCase());
+            if (validator === undefined) {
+                throw new UnknownValidator(key);
+            }
+            return validator(validation);
+        }
+        return z.never();
+    }
+    #validateString(value) {
+        let validation = z.string();
+        if (value.minLength !== undefined)
+            validation = validation.min(value.minLength);
+        if (value.maxLength !== undefined)
+            validation = validation.max(value.maxLength);
+        if (value.pattern !== undefined)
+            validation = validation.regex(new RegExp(value.pattern));
+        return this.#checkRequired(value, validation);
+    }
+    #validateNumber(value) {
+        let validation = z.number();
+        if (value.minValue !== undefined)
+            validation = validation.min(value.minValue);
+        if (value.maxValue !== undefined)
+            validation = validation.max(value.maxValue);
+        return this.#checkRequired(value, validation);
+    }
+    #validateBoolean(value) {
+        const validation = z.boolean();
+        return this.#checkRequired(value, validation);
+    }
+    #validateDate(value) {
+        const validation = z.iso.datetime();
+        return this.#checkRequired(value, validation);
+    }
+    #validateUuid(value) {
+        const validation = z.uuid();
+        return this.#checkRequired(value, validation);
+    }
+    #validateEmail(value) {
+        const validation = z.email().max(MAX_EMAIL_LENGTH);
+        return this.#checkRequired(value, validation);
+    }
+    #validateArray(value) {
+        let validation = value.validations === undefined
+            ? z.array(z.unknown())
+            : z.array(this.#getValidation(value.validations));
+        if (value.minLength !== undefined)
+            validation = validation.min(value.minLength);
+        if (value.maxLength !== undefined)
+            validation = validation.max(value.maxLength);
+        return this.#checkRequired(value, validation);
+    }
+    #validateUrl(value) {
+        let validation = z.url().max(MAX_URL_LENGTH);
+        if (value.protocols !== undefined) {
+            const expression = value.protocols.join('|');
+            validation = validation.regex(new RegExp(`^(${expression}):.*`));
+        }
+        return this.#checkRequired(value, validation);
+    }
+    #checkRequired(value, validation) {
+        return value.required
+            ? validation
+            : validation.optional();
+    }
+    #getMessages(issues, scheme) {
+        const messages = new Map();
+        for (const issue of issues) {
+            if (issue.code === 'unrecognized_keys') {
+                this.#mapUnrecognizedKeys(issue, scheme, messages);
+                continue;
+            }
+            const field = String(issue.path[0]);
+            const message = this.#getMessageByField(field, scheme);
+            messages.set(field, message);
+        }
+        return messages;
+    }
+    #mapUnrecognizedKeys(issue, scheme, messages) {
+        for (const key of issue.keys) {
+            const message = this.#getMessageByField(key, scheme);
+            messages.set(key, message);
+        }
+    }
+    #getMessageByField(path, scheme) {
+        const field = scheme[path];
+        return field?.message ?? 'Invalid field';
+    }
+}

package/dist/implementations/zod/create.d.ts

@@ -0,0 +1,2 @@
+import Zod from './Zod';
+export default function create(): Zod;

package/dist/implementations/zod/create.js

@@ -0,0 +1,4 @@
+import Zod from './Zod';
+export default function create() {
+    return new Zod();
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './definitions/constants';
+export * from './definitions/types';
+export { default as UnknownImplementation } from './errors/UnknownImplementation';
+export { default as UnknownValidator } from './errors/UnknownValidator';
+export { default as ValidationError } from './errors/ValidationError';
+export { default } from './implementation';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './definitions/constants';
+export * from './definitions/types';
+export { default as UnknownImplementation } from './errors/UnknownImplementation';
+export { default as UnknownValidator } from './errors/UnknownValidator';
+export { default as ValidationError } from './errors/ValidationError';
+export { default } from './implementation';

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@theshelf/validation",
+  "private": false,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test-coverage": "vitest run --coverage",
+    "lint": "eslint",
+    "review": "npm run build && npm run lint && npm run test",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "dependencies": {
+    "zod": "4.1.12"
+  }
+}