Validata

Type safe data validation and sanitization.

See also

• validata-koa for more usage in Koa
• validata-express for more usage in Express

Getting started

1npm i validata

Basic usage

1import { asString, isObject, isString, maybeString } from 'validata';
2
3interface Sample {
4  maybeString: string | undefined;
5  myString: string;
6  numericString: string;
7}
8
9const sample = isObject<Sample>({
10  maybeString: maybeString(), // will allow string data type or sanitize to undefined
11  myString: isString(), // will allow only string data type
12  numericString: asString(), // will allow string or attempt to convert to string
13});
14
15console.log(
16  JSON.stringify(
17    sample.process({
18      maybeString: 123,
19      myString: 123,
20      numericString: 123,
21    })
22  )
23);
24
25/*
26FAIL: Outputs:
27{"issues":[{"path":["maybeString"],"value":123,"reason":"incorrect-type","info":{"expectedType":"string"}},{"path":["myString"],"value":123,"reason":"incorrect-type","info":{"expectedType":"string"}}]}
28*/
29
30console.log(
31  JSON.stringify(
32    sample.process({
33      myString: '123',
34      numericString: 123,
35    })
36  )
37);
38
39/*
40SUCCESS: Outputs:
41{"value":{"myString":"123","numericString":"123"}}
42*/

Upgrading to v6

V6 of validata has been marked as a breaking change as it moves the packages luxon, @types/luxon and validata from dependencies to peerDependencies. This better supports different package versions.

If you are using any of the validators that use these packages, you will need to install them directly into your project:

1pnpm add luxon @types/luxon validata

API

Checks:

• isAny
• Array
  • isArray
  • maybeArray
  • asArray
  • maybeAsArray
• Boolean
  • isBoolean
  • maybeBoolean
  • asBoolean
  • maybeAsBoolean
• Date
  • isDate
  • maybeDate
  • asDate
  • maybeAsDate
• DateTime
  • isDateTime
  • maybeDateTime
  • asDateTime
  • maybeAsDateTime
• Enum
  • isEnum
  • maybeEnum
  • asEnum
  • maybeAsEnum
• Number
  • isNumber
  • maybeNumber
  • asNumber
  • maybeAsNumber
• Object
  • isObject
  • maybeObject
  • asObject
  • maybeAsObject
• Record
  • isRecord
  • maybeRecord
  • asRecord
  • maybeAsRecord
• String
  • isString
  • maybeString
  • asString
  • maybeAsString
• Tuple
  • isTuple
  • maybeTuple
• Url
  • isUrl
  • maybeUrl
  • asUrl
  • maybeAsUrl
• isNullable
• asNullable

Types

• TypeOf

Work is done by a typed ValueProcessor, as returned byisObject<T>() or asNumber().

1interface ValueProcessor<T> {
2  process(value: unknown): Result<T>;
3}

The process() method returns a Result<T>.The Result is either a list of issues (meaning validation failures) or the accepted value (it may be coerced/altered from the original).

1type Result<T> = ValueResult<T> | IssueResult;
2
3interface ValueResult<T> {
4  value: T;
5}
6
7interface IssueResult {
8  issues: Issue[];
9}

Naming conventions

is... e.g. isNumber

• if the value is of the type it will be accepted
• null or undefined cause an issue
• otherwise it will cause an issue

maybe... e.g. maybeNumber

• if the value is of the type it will be accepted
• null or undefined it will sanitized to undefined
• otherwise it will cause an issue

as... e.g. asNumber

• if the value is of the type it will be accepted
• null or undefined converted to default, if provided, or cause an issue
• if the value can be converted to the type, it will be converted and used
• if the value is cannot be converted the default will be used if provided
• otherwise it will cause an issue

maybeAs... e.g. maybeAsNumber

• if the value is of the type it will be accepted
• null or undefined converted to default, if provided, or sanitized to undefined
• if the value can be converted to the type it will be converted and used
• if the value is cannot be converted the default will be used if provided
• otherwise it will cause an issue // * otherwise it will be sanitized to undefined

Checks

isArray, maybeArray, asArray, maybeAsArray

Usage:

1isArray(itemProcessor, options);
2maybeArray(itemProcessor, options);
3asArray(itemProcessor, options);
4maybeAsArray(itemProcessor, options);

Options:

• converter?: (value: unknown, options?: any) => T | undefined - custom converter function, if not defined or undefined is returned then built in conversions will be run
• convertOptions - options to pass to the converter
• coerceMaxLength? number - if there are more items than this, some will be removed
• maxLength?: number - if there are more items than this, it's an error max-length
• minLength?: number - if there are less items than this, it's an error min-length
• validator?: (value: T, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

Example:

1isArray<number>(isNumber({ max: 20, min: 10 }), { coerceMaxLength: 7 });

isBoolean, maybeBoolean, asBoolean, maybeAsBoolean

Usage:

1isBoolean(options);
2maybeBoolean(options);
3asBoolean(options);
4maybeAsBoolean(options);

Options:

• converter?: (value: unknown, options?: any) => T | undefined - custom converter function, if not defined or undefined is returned then built in conversions will be run
• convertOptions - options to pass to the converter
• validator?: (value: T, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

isDate, maybeDate, asDate, maybeAsDate

NOTE: Requires peer dependencies luxon and @types/luxon.

Usage:

1isDate(options);
2maybeDate(options);
3asDate(options);
4maybeAsDate(options);

Options:

• converter?: (value: unknown, options?: any) => T | undefined - custom converter function, if not defined or undefined is returned then built in conversions will be run
• convertOptions - options to pass to the converter
• format - custom date format used in conversion from string to Date see Luxon formatting
• maxFuture?: Duration - if the value is after this duration into the future, it's an error max-future
• maxPast?: Duration - if the value is before this duration into the past, it's an error max-past
• validator?: (value: T, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

isDateTime, maybeDateTime, asDateTime, maybeAsDateTime

Similar to above but for luxon DateTime.

NOTE: Requires peer dependencies luxon and @types/luxon.

Usage:

1isDateTime(options);
2maybeDateTime(options);
3asDateTime(options);
4maybeAsDateTime(options);

Options:

• converter?: (value: unknown, options?: any) => T | undefined - custom converter function, if not defined or undefined is returned then built in conversions will be run
• convertOptions - options to pass to the converter
• format - custom date format used in conversion from string to Date see Luxon formatting
• maxFuture?: Duration - if the value is after this duration into the future, it's an error max-future
• maxPast?: Duration - if the value is before this duration into the past, it's an error max-past
• validator?: (value: T, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

isEnum, maybeEnum, asEnum, maybeAsEnum

Usage:

1isEnum(Enum);
2maybeNumber(Enum);
3asNumber(Enum);
4maybeAsNumber(Enum);

Example:

1// String based Enum
2enum EnumOne {
3  A = 'A',
4  B = 'B',
5  C = 'C',
6}
7isEnum(EnumOne); // Allows "A", "B", "C"
8
9// Number based Enum
10enum EnumTwo {
11  A,
12  B,
13  C,
14}
15isEnum(EnumTwo); // Allows 0, 1, 2
16
17// Converting to an Enum using it's key or value
18asEnum(EnumTwo); // Allows 1, 2, 3, "A", "B", "C"
19asEnum(EnumTwo).process('A'));       // { value: 0 }
20asEnum(EnumTwo).process(0));         // { value: 0 }
21asEnum(EnumTwo).process(EnumOne.A)); // { value: 0 }

isNumber, maybeNumber, asNumber, maybeAsNumber

Usage:

1isNumber(options);
2maybeNumber(options);
3asNumber(options);
4maybeAsNumber(options);

Options:

• converter?: (value: unknown, options?: any) => T | undefined - custom converter function, if not defined or undefined is returned then built in conversions will be run
• convertOptions - options to pass to the converter
• coerceMin?: number - if the value is less than this, it will be set to this value
• coerceMax?: number - if the value is more than this, it will be set to this value
• max?: number - if the value is than this, it's an error max
• min?: number - if the value is than this, it's an error min
• validator?: (value: T, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

isObject, maybeObject, asObject, maybeAsObject

Usage:

1isObject(contract, options);
2maybeObject(contract, options);
3asObject(contract, options); // will parse string JSON as object
4maybeAsObject(contract, options); // will parse string JSON as object
5// where `contract` is Record<string, ValueProcessor>

Options:

• converter?: (value: unknown, options?: any) => T | undefined - custom converter function, if not defined or undefined is returned then built in conversions will be run
• convertOptions - options to pass to the converter
• validator?: (value: T, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

Example:

1interface Sample {
2  myString: string;
3  maybeString: string | undefined;
4  numericString: string;
5}
6
7const check = isObject<Sample>({
8  maybeString: maybeString(), // if these don't match the interface TypeScript will error
9  myString: isString(),
10  numericString: asString(),
11});

isRecord, maybeRecord, asRecord, maybeAsRecord

Usage:

1isRecord<V>(check, options);
2maybeRecord<V>(check, options);
3asRecord<V>(check, options);
4maybeAsRecord<V>(check, options);
5// where `check` is ValueProcessor<V>, and Record<string, V> is the type to be processed

Options:

• keyRegex?: RegExp - regular expression to check each key name, or it's an error key-regex
• maxKeys?: number - if the number of keys in the object is more than this, it's an error max-keys
• minKeys?: number - if the number of keys in the object is more than this, it's an error max-keys
• validator?: (value: Record<string, V>, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

Example:

1const check = isRecord(isString());
2check.process({ foo: 'bar' });

isString, maybeString, asString, maybeAsString

Usage:

1isString(options);
2maybeString(options);
3asString(options);
4maybeAsString(options);

Options:

• converter?: (value: unknown, options?: any) => T | undefined - custom converter function, if not defined or undefined is returned then built in conversions will be run
• convertOptions - options to pass to the converter
• limitLength?: number - if the length of the string is more than this, it will be truncated to this length
• padStart?: StringPadding - pad the start of the string up to given value
• padEnd?: StringPadding - pad the end of the string up to given value
• trim?: 'start' | 'end' | 'both' | 'none' - removes the leading and/or trailing white space and line terminator characters from the string
• regex?: RegExp - regular expression that must be matched, or it's an error regex
• maxLength?: number - if the length of the string is more than this, it's an error max-length
• minLength?: number - if the length of the string is less than this, it's an error min-length
• format:? StringFormatCheck - extension point for string format checking, if check fails it's an issue format with info.expectedFormat set
• validator?: (value: T, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

StringPadding:

• length: number - will pad up until this length
• padWith: string - the value to pad with

StringFormat:

• StringFormat.ULID() - https://github.com/ulid/spec
• StringFormat.UUID() - https://www.ietf.org/rfc/rfc4122.txt
• StringFormat.password(requirements: PasswordRequirements) - Password format with minimum requirements
• StringFormat.email(options: { allowDisplayName: boolean }) - requires peer dependency validator

Example:

1const check = isString({
2  limitLength: 6,
3  padStart: { length: 6, padWith: '-' },
4});

1const check = isString({
2  format: StringFormat.ULID(),
3});

1const check = isString({
2  format: StringFormat.password({
3    minLength: 10, // default=8
4    numberChars: 2, // default=1
5    lowerCaseChars: 2, // default=1
6    upperCaseChars: 2, // default=1
7    specialChars: 0, // default=1
8  }),
9});

1const check = isString({
2  format: StringFormat.email({ allowDisplayName: false }),
3});

1// change case
2import { pascalCase } from 'change-case';
3
4const check = isString({
5  transform: pascalCase,
6});

1const check = isString({
2  maxLength: 10,
3  minLength: 8,
4  regex: /^[A-Z]+$/,
5});

1import validator from 'validator';
2
3const check = isString({
4  validator: validator.isEmail,
5  validatorOptions: { allow_display_name: true },
6});

isTuple, maybeTuple

Usage:

1isTuple(options);
2maybeTuple(options);

Options:

• validator?: (value: T, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

Example:

1type MyTuple = [number, string];
2const check = isTuple([isNumber({ max: 9, min: 3 }), isString({ regex: /^\w+$/ })]);

isUrl, maybeUrl, asUrl, maybeAsUrl

Working with Node's URL object

Usage:

1isUrl(options);
2maybeUrl(options);
3asUrl(options);
4maybeAsUrl(options);

Options:

• converter?: (value: unknown, options?: any) => T | undefined - custom converter function, if not defined or undefined is returned then built in conversions will be run
• convertOptions - options to pass to the converter
• setProtocol?: string - will coerce the protocol to the given value, if present
• protocol?: string - given URL must have this protocol, or it's an error invalid-protocol
• validator?: (value: URL, options?: any, path?: Path[]) => boolean | Issue[] - custom validation function; if false or Issue[] is returned it's an error
• validatorOptions?: any - options to pass to the validator

Example:

1const check = asUrl({
2  protocol: 'https',
3});

isNullable

Any other check can be wrapped into isNullable to accept null.

Example:

1const check = isNullable(isString({ min: 3 }));

asNullable

Any other check can be wrapped into asNullable to accept null.

Options:

• default - can be null or return type or a function with return type of the wrapped check

Example:

1const check = asNullable(isString({ min: 3 }));
2const check = asNullable(isString({ min: 3 }), { default: null });
3const check = asNullable(isString({ min: 3 }), { default: 'text' });
4const check = asNullable(isString({ min: 3 }), { default: () => 'text' });

Types

Types can be extracted from a ValueProcessor or a Contract-like pure object.

1const sampleContract = {
2  maybeString: maybeString(),
3  myString: isString(),
4  numericString: asString(),
5};
6const sample = isObject(sampleContract);
7
8// both are same as
9export type SampleContract = TypeOf<typeof sample>;
10export type Sample = TypeOf<typeof sample>;
11// interface Sample {
12//   myString: string;
13//   maybeString: string | undefined;
14//   numericString: string;
15// }