{"id":12341,"library":"v8n","title":"v8n: Fluent JavaScript Validation","description":"v8n (validation) is a JavaScript validation library offering a dead-simple, fluent API for creating complex validation rules. It supports chaining multiple rules and modifiers, allowing for highly intuitive and readable validation logic for various data types including primitives, arrays, and objects. The library provides flexible validation strategies, including boolean-based `test()`, exception-based `check()` for detailed error feedback, and `testAll()` to gather all failures, as well as asynchronous validation. Currently at version 1.5.1, v8n maintains an active development pace with incremental feature additions and bug fixes, often addressing issues related to its schema, optional, and async validation capabilities. It differentiates itself through its highly customizable nature, enabling users to extend it with custom rules, and its reusability, allowing validation chains to be exported as modules.","status":"active","version":"1.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/imbrn/v8n","tags":["javascript","validation","library","typescript"],"install":[{"cmd":"npm install v8n","lang":"bash","label":"npm"},{"cmd":"yarn add v8n","lang":"bash","label":"yarn"},{"cmd":"pnpm add v8n","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` works, the library's primary documentation and examples use ESM. Type definitions are bundled since v1.4.0.","wrong":"const v8n = require('v8n')","symbol":"v8n","correct":"import v8n from 'v8n'"},{"note":"The error class was renamed from `ValidationException` to `ValidationError` in v1.2.1. It is a named export.","wrong":"import { ValidationException } from 'v8n'","symbol":"ValidationError","correct":"import { ValidationError } from 'v8n'"},{"note":"`extend` is a method on the default `v8n` export, not a standalone named export.","wrong":"import { extend } from 'v8n'; extend({ /* rules */ });","symbol":"v8n.extend","correct":"import v8n from 'v8n'; v8n.extend({ /* rules */ });"}],"quickstart":{"code":"import v8n, { ValidationError } from 'v8n';\n\n// Basic string validation\nconst isGreeting = v8n().string().minLength(5).first('H').last('o');\nconsole.log('\"Hello\" is a greeting:', isGreeting.test('Hello')); // true\n\n// Array and number validation with modifiers\nconst allEvenAndPositive = v8n().array().every.number().not.some.negative();\nconsole.log('[2, 4, 6] are all even and positive:', allEvenAndPositive.test([2, 4, 6])); // true\nconsole.log('[1, 2, -3] are all even and positive:', allEvenAndPositive.test([1, 2, -3])); // false\n\n// Object schema validation\nconst userSchema = v8n().schema({\n  id: v8n().string().alphanumeric().minLength(4),\n  age: v8n().number().between(18, 99).optional()\n});\nconsole.log('Valid user object:', userSchema.test({ id: 'user123', age: 30 })); // true\nconsole.log('Invalid user object:', userSchema.test({ id: 'abc' })); // false\n\n// Exception-based validation\ntry {\n  v8n().string().first('b').check('foo');\n} catch (ex) {\n  if (ex instanceof ValidationError) {\n    console.log('Validation failed for rule:', ex.rule.name); // first\n  }\n}\n\n// Custom rule extension\nfunction isBar() {\n  return value => value === 'bar';\n}\nv8n.extend({ isBar });\nconsole.log('\"bar\" is \"bar\":', v8n().string().isBar().test('bar')); // true","lang":"typescript","description":"Demonstrates basic string, array, object schema validation, custom rule extension, and exception-based error handling using the fluent API."},"warnings":[{"fix":"Update `catch (ex: ValidationException)` to `catch (ex: ValidationError)` and import `ValidationError`.","message":"The `ValidationException` error class was renamed to `ValidationError`. Code catching the old exception name will fail.","severity":"breaking","affected_versions":">=1.2.1"},{"fix":"Ensure `check()` is used for its side effect (throwing an error) and not for a boolean return value. The type definition has been corrected in v1.5.0.","message":"The return type of the `check()` method was incorrectly typed as boolean instead of void. This could lead to misassumptions about its return value.","severity":"gotcha","affected_versions":">=1.0.0 <1.5.0"},{"fix":"Upgrade to v1.5.0 or later to ensure correct behavior of the `optional` rule, especially concerning empty strings and async validation within it.","message":"Earlier versions had bugs where the `optional` rule might incorrectly ignore subsequent validation rules or fail to validate empty strings when trimmed, leading to unexpected passes.","severity":"gotcha","affected_versions":"<1.5.0"},{"fix":"Update to v1.5.0 or newer. The bug with `Proxy` check returning `true` has been fixed.","message":"In environments that don't correctly implement `Proxy` objects or due to bugs, the `Proxy` check in v8n might have always returned `true`, causing validation logic to bypass intended checks.","severity":"gotcha","affected_versions":">=1.0.0 <1.5.0"},{"fix":"Upgrade to v1.5.1 or later to benefit from the fixed and more efficient regular expressions for these rules.","message":"The `lowercase()` and `uppercase()` rules in earlier versions used inefficient regular expressions, which could lead to performance issues or ReDoS vulnerabilities on large or malicious input strings.","severity":"gotcha","affected_versions":"<1.5.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change all references from `ValidationException` to `ValidationError` and ensure `ValidationError` is imported.","cause":"Attempting to catch or reference the old error class name `ValidationException` after it was renamed.","error":"ReferenceError: ValidationException is not defined"},{"fix":"Ensure `check()` is always within a `try...catch` block and that you are checking for `instanceof ValidationError`. Remember `check()` throws on failure and returns `void` on success.","cause":"This usually indicates that `check()` was called but no error was thrown, or the caught object is not a `ValidationError`. This could happen if `check()` was expected to return a boolean but didn't, or if the logic flow is incorrect.","error":"TypeError: Cannot read properties of undefined (reading 'name') at v8n(...).check(...)"},{"fix":"Update `v8n` to version 1.5.0 or later. Also, consider the `considerTrimmedEmptyString` flag on the `optional` rule for specific empty string handling needs.","cause":"Older versions of the `optional` rule had bugs where it would ignore subsequent rules or fail to correctly handle empty strings.","error":"v8n().optional().string().test('') unexpectedly returns true, but I expect validation for empty string."},{"fix":"Ensure `v8n.extend({ myCustomRule })` is called before using the rule. For TypeScript, you might need declaration merging (see v8n documentation on custom types).","cause":"A custom rule was defined but not properly registered with `v8n.extend()` or TypeScript types are not extended.","error":"Property 'myCustomRule' does not exist on type 'V8n' or 'v8n.V8n'"}],"ecosystem":"npm"}