hybrid-validator 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrii Kotsiuba and contributors
+
+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,213 @@
+
+# JSON Schema Validator
+
+High-performance JSON schema validator for Node.js.
+
+Designed for:
+
+- ⚡ maximum performance
+- 🧠 smart compiled validators
+- 🔧 extensibility
+- 📦 minimal overhead
+
+---
+
+# Why another validator?
+
+Most validators focus on flexibility but sacrifice performance.
+
+This project focuses on **raw validation speed** while still supporting:
+
+- runtime validation
+- compiled validators
+- custom types
+- custom validators
+
+---
+
+# Installation
+
+```bash
+npm install json-schema-validator
+````
+
+---
+
+# Quick Example
+
+```js
+import { Validator } from "json-schema-validator";
+
+const validator = new Validator();
+
+const schema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    age: { type: "number" }
+  }
+};
+
+const data = {
+  name: "John",
+  age: 30
+};
+
+const result = validator.validate({
+  schema,
+  data
+});
+
+console.log(result);
+```
+
+---
+
+# Two Validation Modes
+
+## Runtime validation
+
+Use when data is validated **only once**.
+
+```js
+validator.validate({ schema, data });
+```
+
+Advantages:
+
+* no compilation cost
+* fastest for single validation
+
+---
+
+## Compiled validation
+
+Use when validating **large datasets**.
+
+```js
+const validate = validator.compile(schema);
+
+validate(data1);
+validate(data2);
+validate(data3);
+```
+
+Advantages:
+
+* schema compiled once
+* extremely fast repeated validation
+
+---
+
+# Performance
+
+Benchmark executed using **tinybench**.
+
+Libraries compared:
+
+* Ajv
+* Zod
+* Yup
+* Fastest Validator
+
+Results:
+
+| Validator         | ops/sec       | relative speed |
+| ----------------- | ------------- | -------------- |
+| **NativeEngine**  | **1,186,514** | 🥇 fastest     |
+| CompiledValidator | 94,039        | 12× slower     |
+| Yup               | 11,225        | 100× slower    |
+| Zod               | 7,493         | 158× slower    |
+| FastestValidator  | 3,796         | 312× slower    |
+| AJV (cold start)  | 225           | 5270× slower   |
+
+---
+
+# Benchmark Chart
+
+```
+
+NativeEngine        █████████████████████████████████████████ 1,186,514
+CompiledValidator   ████ 94,039
+Yup                 █ 11,225
+Zod                 █ 7,493
+FastestValidator    ▌ 3,796
+AJV cold            ▏ 225
+
+```
+
+---
+
+# When to use which mode
+
+| Scenario                   | Method        |
+| -------------------------- | ------------- |
+| single validation          | `.validate()` |
+| large dataset              | `.compile()`  |
+| high performance pipelines | `.compile()`  |
+
+---
+
+# Cache
+
+Compiled schemas are automatically cached using `WeakMap`.
+
+```js
+const validator = new Validator();
+
+const validate = validator.compile(schema);
+
+// reused from cache
+const validate2 = validator.compile(schema);
+```
+
+Clear cache:
+
+```js
+validator.clearCache();
+```
+
+---
+
+# Options
+
+```js
+const validator = new Validator({
+  recursive: true,
+  strict: true,
+  customTypes: {},
+  customValidators: []
+});
+```
+
+| option           | description                |
+| ---------------- | -------------------------- |
+| recursive        | validate nested structures |
+| strict           | strict schema validation   |
+| customTypes      | user defined types         |
+| customValidators | custom validators          |
+
+---
+
+# Architecture
+
+Validator uses two internal engines:
+
+| Engine        | Description        |
+| ------------- | ------------------ |
+| NativeEngine  | runtime validation |
+| CodeGenerator | compiled validator |
+
+---
+
+# Roadmap
+
+* more JSON Schema features
+* async validation
+* schema precompilation
+* browser support
+
+---
+
+# License
+

package/lib/CodeGenerator.js

@@ -0,0 +1,304 @@
+export class CodeGenerator {
+  constructor(options = {}) {
+    this.options = {
+      recursive: true,
+      strict: true,
+      customTypes: {},
+      customValidators: [],
+      ...options,
+    };
+  }
+
+  compile(schema) {
+    const { customTypes, customValidators, recursive } = this.options;
+
+    const code = [];
+    code.push(`const errors = [];`);
+
+    const gen = (schema, dataRef, pathExpr, depth = 0) => {
+      if (schema === true) return;
+
+      if (schema === false) {
+        code.push(`
+errors.push({
+  path: ${pathExpr},
+  message: "Schema is false, value is not allowed"
+});
+`);
+        return;
+      }
+
+      if (!schema) return;
+
+      if (schema.type) {
+        const typeCheck = this.generateTypeCheck(schema.type, dataRef);
+        const typeLabel = Array.isArray(schema.type)
+          ? schema.type.join(', ')
+          : schema.type;
+
+        code.push(`
+if (${typeCheck}) {
+`);
+
+        if (schema.enum) {
+          const values = JSON.stringify(schema.enum);
+          code.push(`
+if (!${values}.includes(${dataRef})) {
+  errors.push({
+    path: ${pathExpr},
+    message: "Value '" + ${dataRef} + "' is not one of: ${schema.enum.join(', ')}"
+  });
+}
+`);
+        }
+
+        if (schema.minimum !== undefined) {
+          code.push(`
+if (${dataRef} < ${schema.minimum}) {
+  errors.push({
+    path: ${pathExpr},
+    message: "Value " + ${dataRef} + " < minimum ${schema.minimum}"
+  });
+}
+`);
+        }
+
+        if (schema.maximum !== undefined) {
+          code.push(`
+if (${dataRef} > ${schema.maximum}) {
+  errors.push({
+    path: ${pathExpr},
+    message: "Value " + ${dataRef} + " > maximum ${schema.maximum}"
+  });
+}
+`);
+        }
+
+        if (schema.exclusiveMinimum !== undefined) {
+          code.push(`
+if (${dataRef} <= ${schema.exclusiveMinimum}) {
+  errors.push({
+    path: ${pathExpr},
+    message: "Value " + ${dataRef} + " <= exclusiveMinimum ${schema.exclusiveMinimum}"
+  });
+}
+`);
+        }
+
+        if (schema.exclusiveMaximum !== undefined) {
+          code.push(`
+if (${dataRef} >= ${schema.exclusiveMaximum}) {
+  errors.push({
+    path: ${pathExpr},
+    message: "Value " + ${dataRef} + " >= exclusiveMaximum ${schema.exclusiveMaximum}"
+  });
+}
+`);
+        }
+
+        if (schema.multipleOf !== undefined) {
+          code.push(`
+if (${dataRef} % ${schema.multipleOf} !== 0) {
+  errors.push({
+    path: ${pathExpr},
+    message: "Value " + ${dataRef} + " not multipleOf ${schema.multipleOf}"
+  });
+}
+`);
+        }
+
+        if (recursive && schema.type === 'object') {
+          code.push(`
+if (${dataRef} && typeof ${dataRef} === 'object' && !Array.isArray(${dataRef})) {
+`);
+          if (schema.properties) {
+            for (const key in schema.properties) {
+              const prop = schema.properties[key];
+              const ref = `${dataRef}.${key}`;
+
+              const childPath =
+                pathExpr === '""' ? `"${key}"` : `${pathExpr} + "." + "${key}"`;
+
+              code.push(`
+if (${dataRef}.${key} !== undefined) {
+`);
+              gen(prop, ref, childPath, depth);
+              code.push(`}`);
+            }
+          }
+
+          if (schema.additionalProperties === false && schema.properties) {
+            const keys = JSON.stringify(Object.keys(schema.properties));
+
+            code.push(`
+for (const k in ${dataRef}) {
+  if (!${keys}.includes(k)) {
+    errors.push({
+      path: k,
+      message: "Unexpected field '" + k + "'"
+    });
+  }
+}
+`);
+          }
+
+          if (typeof schema.additionalProperties === 'object') {
+            code.push(`
+for (const k in ${dataRef}) {
+`);
+            if (schema.properties) {
+              const keys = JSON.stringify(Object.keys(schema.properties));
+
+              code.push(`
+if (!${keys}.includes(k)) {
+`);
+
+              gen(
+                schema.additionalProperties,
+                `${dataRef}[k]`,
+                pathExpr === '""' ? `k` : `${pathExpr} + "." + k`,
+                depth,
+              );
+
+              code.push(`}`);
+            } else {
+              gen(
+                schema.additionalProperties,
+                `${dataRef}[k]`,
+                pathExpr === '""' ? `k` : `${pathExpr} + "." + k`,
+                depth,
+              );
+            }
+
+            code.push(`}`);
+          }
+
+          if (schema.patternProperties) {
+            for (const pattern in schema.patternProperties) {
+              const propSchema = schema.patternProperties[pattern];
+              const regexName = `regex_${pattern.replace(/\W/g, '_')}`;
+
+              code.push(`
+const ${regexName} = new RegExp(${JSON.stringify(pattern)});
+for (const k in ${dataRef}) {
+  if (${regexName}.test(k)) {
+`);
+
+              gen(
+                propSchema,
+                `${dataRef}[k]`,
+                pathExpr === '""' ? `k` : `${pathExpr} + "." + k`,
+                depth,
+              );
+
+              code.push(`
+  }
+}
+`);
+            }
+          }
+
+          code.push(`
+} // end if object
+`);
+        }
+
+        if (recursive && schema.type === 'array' && schema.items) {
+          const loopVar = `i${depth}`;
+          code.push(`
+if (Array.isArray(${dataRef})) {
+  for (let ${loopVar} = 0; ${loopVar} < ${dataRef}.length; ${loopVar}++) {
+`);
+
+          gen(
+            schema.items,
+            `${dataRef}[${loopVar}]`,
+            pathExpr === '""'
+              ? `"[" + ${loopVar} + "]"`
+              : `${pathExpr} + "[" + ${loopVar} + "]"`,
+            depth + 1,
+          );
+
+          code.push(`
+  }
+} // end if array
+`);
+        }
+
+        code.push(`
+} else {
+  const actual = Array.isArray(${dataRef}) ? "array" : typeof ${dataRef};
+  errors.push({
+    path: ${pathExpr},
+    message: "Expected type '${typeLabel}', got '" + actual + "'"
+  });
+}
+`);
+      } else if (schema.enum) {
+        const values = JSON.stringify(schema.enum);
+        code.push(`
+if (!${values}.includes(${dataRef})) {
+  errors.push({
+    path: ${pathExpr},
+    message: "Value '" + ${dataRef} + "' is not one of: ${schema.enum.join(', ')}"
+  });
+}
+`);
+      }
+    };
+
+    gen(schema, 'data', `""`, 0);
+
+    code.push(`
+for (let i = 0; i < customValidators.length; i++) {
+  customValidators[i](data, "", errors);
+}
+
+return {
+  isValid: errors.length === 0,
+  errors
+};
+`);
+
+    const fn = new Function(
+      'data',
+      'customTypes',
+      'customValidators',
+      code.join('\n'),
+    );
+
+    return (data) => fn(data, customTypes, customValidators);
+  }
+
+  generateTypeCheck(type, ref) {
+    if (Array.isArray(type)) {
+      return type.map((t) => this.generateTypeCheck(t, ref)).join(' || ');
+    }
+
+    switch (type) {
+      case 'string':
+        return `typeof ${ref} === "string"`;
+
+      case 'number':
+        return `typeof ${ref} === "number" && Number.isFinite(${ref})`;
+
+      case 'integer':
+        return `Number.isInteger(${ref})`;
+
+      case 'boolean':
+        return `typeof ${ref} === "boolean"`;
+
+      case 'array':
+        return `Array.isArray(${ref})`;
+
+      case 'object':
+        return `${ref} !== null && typeof ${ref} === "object" && !Array.isArray(${ref})`;
+
+      case 'null':
+        return `${ref} === null`;
+
+      default:
+        return `customTypes["${type}"] ? customTypes["${type}"](${ref}) : typeof ${ref} === "${type}"`;
+    }
+  }
+}

package/lib/NativeEngine.js

@@ -0,0 +1,305 @@
+export class NativeEngine {
+  constructor(options = {}) {
+    const {
+      recursive = true,
+      strict = false,
+      customValidators = [],
+      customTypes = {},
+    } = options;
+
+    this.options = { recursive, strict };
+    this.customValidators = customValidators;
+    this.customTypes = customTypes;
+    this.errors = [];
+  }
+
+  // ==================================================
+  // PUBLIC
+  // ==================================================
+
+  validate({ schema, data }) {
+    this.errors = [];
+
+    this.#validateBySchema(schema, data, '');
+
+    for (const validator of this.customValidators) {
+      validator(data, '', this.errors);
+    }
+
+    return {
+      isValid: this.errors.length === 0,
+      errors: this.errors,
+    };
+  }
+
+  // ==================================================
+  // TYPE CHECKING
+  // ==================================================
+
+  #checkType(value, expectedType) {
+    if (Array.isArray(expectedType)) {
+      return expectedType.some((t) => this.#checkType(value, t));
+    }
+
+    if (this.customTypes[expectedType]) {
+      return this.customTypes[expectedType](value);
+    }
+
+    switch (expectedType) {
+      case 'integer':
+        return Number.isInteger(value);
+
+      case 'number':
+        return typeof value === 'number' && Number.isFinite(value);
+
+      case 'string':
+        return typeof value === 'string';
+
+      case 'boolean':
+        return typeof value === 'boolean';
+
+      case 'array':
+        return Array.isArray(value);
+
+      case 'object':
+        return (
+          typeof value === 'object' && value !== null && !Array.isArray(value)
+        );
+
+      case 'null':
+        return value === null;
+
+      default:
+        return typeof value === expectedType;
+    }
+  }
+
+  #typeError(path, expected, value) {
+    const actual = Array.isArray(value) ? 'array' : typeof value;
+
+    const expectedStr = Array.isArray(expected)
+      ? expected.join(', ')
+      : expected;
+
+    this.errors.push({
+      path: path || 'root',
+      message: `Expected type '${expectedStr}', got '${actual}'`,
+    });
+  }
+
+  // ==================================================
+  // COMMON RULES
+  // ==================================================
+
+  #validateEnum(value, schema, path) {
+    if (schema.enum && !schema.enum.includes(value)) {
+      this.errors.push({
+        path,
+        message: `Value '${value}' is not one of: ${schema.enum.join(', ')}`,
+      });
+    }
+  }
+
+  #validateFormat(value, schema, path) {
+    if (!schema.format) return;
+
+    if (schema.format === 'date-time') {
+      const date = new Date(value);
+
+      if (Number.isNaN(date.getTime())) {
+        this.errors.push({
+          path,
+          message: `Value '${value}' is not a valid ISO 8601 date-time`,
+        });
+      }
+    }
+  }
+
+  #validateNumberRules(value, schema, path) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return;
+
+    if (schema.minimum !== undefined && value < schema.minimum) {
+      this.errors.push({
+        path,
+        message: `Value ${value} is less than minimum ${schema.minimum}`,
+      });
+    }
+
+    if (
+      schema.exclusiveMinimum !== undefined &&
+      value <= schema.exclusiveMinimum
+    ) {
+      this.errors.push({
+        path,
+        message: `Value ${value} must be greater than ${schema.exclusiveMinimum}`,
+      });
+    }
+
+    if (schema.maximum !== undefined && value > schema.maximum) {
+      this.errors.push({
+        path,
+        message: `Value ${value} is greater than maximum ${schema.maximum}`,
+      });
+    }
+
+    if (
+      schema.exclusiveMaximum !== undefined &&
+      value >= schema.exclusiveMaximum
+    ) {
+      this.errors.push({
+        path,
+        message: `Value ${value} must be less than ${schema.exclusiveMaximum}`,
+      });
+    }
+
+    if (schema.multipleOf !== undefined) {
+      if (value % schema.multipleOf !== 0) {
+        this.errors.push({
+          path,
+          message: `Value ${value} is not a multiple of ${schema.multipleOf}`,
+        });
+      }
+    }
+  }
+
+  #applyCommonRules(value, schema, path) {
+    this.#validateEnum(value, schema, path);
+    this.#validateFormat(value, schema, path);
+
+    if (schema.type === 'number' || schema.type === 'integer') {
+      this.#validateNumberRules(value, schema, path);
+    }
+  }
+
+  // ==================================================
+  // OBJECT
+  // ==================================================
+
+  #validateObject(schema, data, path = '') {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return;
+
+    const { strict } = this.options;
+    const validatedKeys = new Set();
+
+    if (schema.required && Array.isArray(schema.required)) {
+      for (const field of schema.required) {
+        if (!(field in data)) {
+          this.errors.push({
+            path: path ? `${path}.${field}` : field,
+            message: `Required field '${field}' is missing`,
+          });
+        }
+      }
+    }
+
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        validatedKeys.add(key);
+
+        if (key in data) {
+          const currentPath = path ? `${path}.${key}` : key;
+
+          this.#validateBySchema(propSchema, data[key], currentPath);
+        }
+      }
+    }
+
+    if (schema.patternProperties) {
+      for (const [pattern, propSchema] of Object.entries(
+        schema.patternProperties,
+      )) {
+        const regex = new RegExp(pattern);
+
+        for (const key of Object.keys(data)) {
+          if (regex.test(key)) {
+            validatedKeys.add(key);
+
+            const currentPath = path ? `${path}.${key}` : key;
+
+            this.#validateBySchema(propSchema, data[key], currentPath);
+          }
+        }
+      }
+    }
+
+    for (const key of Object.keys(data)) {
+      if (validatedKeys.has(key)) continue;
+
+      const currentPath = path ? `${path}.${key}` : key;
+
+      if (schema.additionalProperties === false) {
+        this.errors.push({
+          path: currentPath,
+          message: `Unexpected field '${key}'`,
+        });
+
+        continue;
+      }
+
+      if (typeof schema.additionalProperties === 'object') {
+        this.#validateBySchema(
+          schema.additionalProperties,
+          data[key],
+          currentPath,
+        );
+      } else if (strict && !schema.additionalProperties) {
+        this.errors.push({
+          path: currentPath,
+          message: `Unexpected field '${key}'`,
+        });
+      }
+    }
+  }
+
+  // ==================================================
+  // ARRAY
+  // ==================================================
+
+  #validateArray(schema, data, path) {
+    if (!Array.isArray(data)) {
+      this.#typeError(path, 'array', data);
+      return;
+    }
+
+    if (!schema.items) return;
+
+    data.forEach((item, index) => {
+      const itemPath = `${path}[${index}]`;
+
+      this.#validateBySchema(schema.items, item, itemPath);
+    });
+  }
+
+  // ==================================================
+  // UNIVERSAL VALIDATOR
+  // ==================================================
+
+  #validateBySchema(schema, value, path) {
+    if (schema === true) return;
+    if (schema === false) {
+      this.errors.push({
+        path,
+        message: 'Schema is false, value is not allowed',
+      });
+      return;
+    }
+    if (!schema) return;
+
+    if (schema.type && !this.#checkType(value, schema.type)) {
+      this.#typeError(path, schema.type, value);
+      return;
+    }
+
+    this.#applyCommonRules(value, schema, path);
+
+    if (!this.options.recursive) return;
+
+    if (schema.type === 'object') {
+      this.#validateObject(schema, value, path);
+    }
+
+    if (schema.type === 'array') {
+      this.#validateArray(schema, value, path);
+    }
+  }
+}

package/lib/Validator.js

@@ -0,0 +1,44 @@
+import { NativeEngine } from './NativeEngine.js';
+import { CodeGenerator } from './CodeGenerator.js';
+
+export class Validator {
+  #compiledCache;
+
+  constructor(options = {}) {
+    this.options = {
+      recursive: true,
+      strict: true,
+      customTypes: {},
+      customValidators: [],
+      ...options,
+    };
+
+    this.#compiledCache = new WeakMap();
+  }
+
+  // ==================================================
+  // PUBLIC API
+  // ==================================================
+
+  validate({ schema, data }) {
+    const engine = new NativeEngine(this.options);
+    return engine.validate({ schema, data });
+  }
+
+  compile(schema) {
+    if (this.#compiledCache.has(schema)) {
+      return this.#compiledCache.get(schema);
+    }
+
+    const generator = new CodeGenerator(this.options);
+    const compiledFn = generator.compile(schema);
+
+    this.#compiledCache.set(schema, compiledFn);
+
+    return compiledFn;
+  }
+
+  clearCache() {
+    this.#compiledCache = new WeakMap();
+  }
+}

package/lib/index.js

@@ -0,0 +1,3 @@
+export { Validator } from './Validator.js';
+export { NativeEngine } from './NativeEngine.js';
+export { CodeGenerator } from './CodeGenerator.js';

package/lib/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "hybrid-validator",
+  "version": "0.5.1",
+  "description": "Lightweight JSON Schema validator for Node.js and modern JavaScript environments",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepare": "node tools/setGitHooks.js",
+    "lint": "prettier -c \"**/*.js\" && eslint .",
+    "fix": "prettier --write \"**/*.js\" && eslint . --fix",
+    "test": "node --test",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "imports": {
+    "#lib": "./lib/index.js",
+    "#tools": "./tools/index.js"
+  },
+  "keywords": [
+    "json",
+    "json-schema",
+    "validator",
+    "schema-validation",
+    "validation",
+    "json-validator"
+  ],
+  "author": "Andrii Kotsiuba",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndriiKot/json-schema-validator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AndriiKot/json-schema-validator/issues"
+  },
+  "homepage": "https://github.com/AndriiKot/json-schema-validator#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "private": false,
+  "devDependencies": {
+    "eslint": "^9.39.2",
+    "eslint-config-metarhia": "^9.1.5",
+    "prettier": "^3.8.1"
+  }
+}