A TypeScript-friendly validator.
This package provides:
- Compiler; It compiles schemas then creates a validation function. The validation is fast.
- Type Assertion; It can compute the value type of schemas. The validated values will get well typing.
- Customizable; You can use a function (with type guard) to define your validation.
- Localization; Every validation error is represented with a code and arguments. You can define error messages in your primary language. (Of course, this package provides the default error messages.)
Use npm or a compatible tool to install.
npm install validia
import { validate } from "validia";
// 1. Define your schema.
const myOptionSchema = {
type: "object",
properties: {
include: { type: "array", elements: { type: "string" } },
exclude: { type: "array", elements: { type: "string" } },
},
} as const; // `as const` is important.
// 2. Validate a value.
declare let value: any;
validate(myOptionSchema, value);
// The `value` is `{ include?: string[]; exclude?: string[] }` here.
Schema is simple objects. But I'd like to recommend using factory functions to utilize input completion and ensure good typings.
import { schemas as s, validate } from "validia";
// 1. Define your schema.
const myOptionSchema = s.object({
include: s.array(s.string()),
exclude: s.array(s.string()),
});
// 2. Validate a value.
declare let value: any;
validate(myOptionSchema, value);
// The `value` is `{ include?: string[]; exclude?: string[] }` here.
The schemas
is the namespace of factory functions.
import { createValidation, schemas as s, Validate } from "validia";
// 1. Define your schema.
const myOptionSchema = s.object({
include: s.array(s.string()),
exclude: s.array(s.string()),
});
// 2. Compile validation.
const validate: Validate<typeof myOptionSchema> = createValidation(
myOptionSchema
);
// 3. Validate a value.
declare let value: any;
validate(value);
// The `value` is `{ include?: string[]; exclude?: string[] }` here.
Unfortunately, you have to declare the type of the validate
function explicitly because of microsoft/TypeScript#33580. In short, the type of Assertion Functions must be decided before the type inference phase.
This package requires ES2018 or later.
If you want to use this package on a legacy platform, use the validia/es5
entry point along with core-js
, @babel/runtime
, and regenerator-runtime
.
For example:
const { schemas, createValidate } = require("validia/es5");
// ...
Or you can merely configure your bundler to transpile this package as well.
The generated code of createValidation(schema)
function is ES5 then it works well on IE11. (probably!)
import {
// objects
createValidation,
validate,
schemas,
ValidationError,
DefaultMessage,
// types
Message,
Schema,
TypeOf,
Validate,
} from "validia";
Compile the validation function of given schema object.
schema
... The schema object.options
... The options to compile.options.defaultMessages
... The error message generator. Optional. Default isDefaultMessage
.
- The validation function of the schema;
(value: any, options?: Options) => void
.- If the
value
argument passed the validation, thevalue
argument gets good typing. Otherwise, the validation function throws aValidationError
instance. - The
options.messages
argument is the error message generator. Optional. Default isoptions.defaultMessages
. - The
options.name
argument will be used in error messages. Optional. Default is"value"
.
- If the
This is equivalent to createValidation<T>(schema)(value, options)
.
The schema factories.
schemas.any()
... The schema representingany
.schemas.array(schema?, options?)
... The schema representing specific arrays.schema
is the schema of array elements. Default isschemas.any()
.options.maxLength
is the maximum length.options.minLength
is the minimum length.options.unique
is the flag to disallow duplicated values.
schemas.bigInt(options?)
... The schema representing specificbigint
values.options.maxValue
is the maximum value.options.minValue
is the minimum value.
schemas.boolean()
... The schema representingtrue
orfalse
.schemas.instanceOf(constructor)
... The schema representing instances of a specific class.constructor
is the class.
schemas.custom(name, check)
... The schema representing a user-defined check.name
is the name of this check. It will be used in error messages.check
is the function of this chck;<T>(value: unknown) => value is T
. Returntrue
if thevalue
passed validation.
schemas.enum(...values)
... The schema representing any of specific values.values
is the list of allowed values.
schemas.function()
... The schema representing any functions.schemas.number(options?)
... The schema representing specific numbers.options.allowInfinity
is the flag to allowInfinity
and-Infinity
.options.allowNaN
is the flag to allowNaN
.options.intOnly
is the flag to disallow non-integers.options.maxValue
is the maximum value.options.minValue
is the minimum value.
schemas.object(properties?, options?)
... The schema representing specific objects. If you give no arguments, the returned schema matches any objects.properties
is the definition of known properties;Record<string, Schema>
.options.allowUnknown
is the flag to allow unknown properties.options.required
istrue
or the array of known property names to be required. Iftrue
, all known properties are required.
schemas.record(schema?)
... The schema representing specific objects.schema
is the schema of properties. Default isschemas.any()
.
schemas.string(options?)
... The schema representing specific strings.options.maxLength
is the maximum number of characters.options.minLength
is the minimum number of characters.options.pattern
is the regular expression of allowed strings.
schemas.symbol()
... The schema representing any symbols.schemas.tuple(...elements)
... The schema representing specific tuples.elements
is the schemas of elements.
schemas.anyOf(...schemas)
... The schema representing specific union types.schemas
is the schema of allowed types.
schemas.bigInt64
... Equivalent toschemas.bigInt({ maxValue: 9223372036854775807n, minValue: -9223372036854775808n })
.schemas.bigUint64
... Equivalent toschemas.bigInt({ maxValue: 18446744073709551615n, minValue: 0 })
.schemas.null
... Equivalent toschemas.enum(null)
.schemas.int8
... Equivalent toschemas.number({ intOnly: true, maxValue: 127, minValue: -128 })
.schemas.int16
... Equivalent toschemas.number({ intOnly: true, maxValue: 32767, minValue: -32768 })
.schemas.int32
... Equivalent toschemas.number({ intOnly: true, maxValue: 2147483647, minValue: -2147483648 })
.schemas.uint8
... Equivalent toschemas.number({ intOnly: true, maxValue: 255, minValue: 0 })
.schemas.uint16
... Equivalent toschemas.number({ intOnly: true, maxValue: 65535, minValue: 0 })
.schemas.uint32
... Equivalent toschemas.number({ intOnly: true, maxValue: 4294967295, minValue: 0 })
.
The Error
class for validation errors.
The default error messages.
The interface to define your own error messages.
See src/message/default-message.ts for example.
The types of schemas.
See src/schema-types.ts for details.
The types for calculating the value type of schemas.
See src/real-types.ts for details.
The type of validation functions.
type Validate<T extends Schema> = (
name: string,
value: any
) => asserts value is TypeOf<T>;
See GitHub Releases.
Welcome contributing!
Please use GitHub's Issues/PRs.
npm test
runs tests and measures coverage.npm run build
compiles source code to index.mjs, index.js, index.mjs.map, index.js.map, and index.d.ts.npm run clean
removes the temporary files which are created by npm test and npm run build.npm run format
runs Prettier.npm run lint
runs ESLint.npm version <patch|minor|major>
makes a new release.