From 3b95aa6cce6567dfc1c4917e65a8124aadab0cb2 Mon Sep 17 00:00:00 2001 From: Young Rok Kim Date: Mon, 21 Aug 2017 03:21:50 +0900 Subject: [PATCH] joi: unify return values as this --- types/joi/index.d.ts | 256 +++++++++++++++++++++---------------------- 1 file changed, 126 insertions(+), 130 deletions(-) diff --git a/types/joi/index.d.ts b/types/joi/index.d.ts index fd4659a2d1..43ba612f6f 100644 --- a/types/joi/index.d.ts +++ b/types/joi/index.d.ts @@ -6,7 +6,7 @@ // TODO express type of Schema in a type-parameter (.default, .valid, .example etc) -export type Types = 'any' | 'alternatives' | 'array' | 'string' | 'number' | 'object' | 'boolean' | 'binary' | 'date' | 'function' | 'lazy'; +export type Types = 'any' | 'alternatives' | 'array' | 'boolean' | 'binary' | 'date' | 'function' | 'lazy' | 'number' | 'object' | 'string'; export type LanguageOptions = string | false | null | { [key: string]: LanguageOptions; @@ -185,12 +185,9 @@ export type Schema = AnySchema | NumberSchema | ObjectSchema | StringSchema + | LazySchema | Reference; -export interface Reference extends AnySchema { - -} - export interface AnySchema { /** * Validates a value using the schema and options. @@ -203,27 +200,27 @@ export interface AnySchema { /** * Whitelists a value */ - allow(value: any, ...values: any[]): this; + allow(...values: any[]): this; allow(values: any[]): this; /** * Adds the provided values into the allowed whitelist and marks them as the only valid values allowed. */ - valid(value: any, ...values: any[]): this; + valid(...values: any[]): this; valid(values: any[]): this; - only(value: any, ...values: any[]): this; + only(...values: any[]): this; only(values: any[]): this; - equal(value: any, ...values: any[]): this; + equal(...values: any[]): this; equal(values: any[]): this; /** * Blacklists a value */ - invalid(value: any, ...values: any[]): this; + invalid(...values: any[]): this; invalid(values: any[]): this; - disallow(value: any, ...values: any[]): this; + disallow(...values: any[]): this; disallow(values: any[]): this; - not(value: any, ...values: any[]): this; + not(...values: any[]): this; not(values: any[]): this; /** @@ -402,7 +399,7 @@ export interface BooleanSchema extends AnySchema { * see boolean.insensitive() to change this behavior. * @param values - strings, numbers or arrays of them */ - truthy(...values: Array): BooleanSchema; + truthy(...values: Array): this; /** * Allows for additional values to be considered valid booleans by converting them to false during validation. @@ -410,14 +407,14 @@ export interface BooleanSchema extends AnySchema { * see boolean.insensitive() to change this behavior. * @param values - strings, numbers or arrays of them */ - falsy(...values: Array): BooleanSchema; + falsy(...values: Array): this; /** * Allows the values provided to truthy and falsy as well as the "true" and "false" default conversion * (when not in strict() mode) to be matched in a case insensitive manner. * @param enabled */ - insensitive(enabled: boolean): BooleanSchema; + insensitive(enabled?: boolean): this; } export interface NumberSchema extends AnySchema { @@ -425,166 +422,166 @@ export interface NumberSchema extends AnySchema { * Specifies the minimum value. * It can also be a reference to another field. */ - min(limit: number): NumberSchema; - min(limit: Reference): NumberSchema; + min(limit: number): this; + min(limit: Reference): this; /** * Specifies the maximum value. * It can also be a reference to another field. */ - max(limit: number): NumberSchema; - max(limit: Reference): NumberSchema; + max(limit: number): this; + max(limit: Reference): this; /** * Specifies that the value must be greater than limit. * It can also be a reference to another field. */ - greater(limit: number): NumberSchema; - greater(limit: Reference): NumberSchema; + greater(limit: number): this; + greater(limit: Reference): this; /** * Specifies that the value must be less than limit. * It can also be a reference to another field. */ - less(limit: number): NumberSchema; - less(limit: Reference): NumberSchema; + less(limit: number): this; + less(limit: Reference): this; /** * Requires the number to be an integer (no floating point). */ - integer(): NumberSchema; + integer(): this; /** * Specifies the maximum number of decimal places where: * limit - the maximum number of decimal places allowed. */ - precision(limit: number): NumberSchema; + precision(limit: number): this; /** * Specifies that the value must be a multiple of base. */ - multiple(base: number): NumberSchema; + multiple(base: number): this; /** * Requires the number to be positive. */ - positive(): NumberSchema; + positive(): this; /** * Requires the number to be negative. */ - negative(): NumberSchema; + negative(): this; } export interface StringSchema extends AnySchema { /** * Allows the value to match any whitelist of blacklist item in a case insensitive comparison. */ - insensitive(): StringSchema; + insensitive(): this; /** * Specifies the minimum number string characters. * @param limit - the minimum number of string characters required. It can also be a reference to another field. * @param encoding - if specified, the string length is calculated in bytes using the provided encoding. */ - min(limit: number, encoding?: string): StringSchema; - min(limit: Reference, encoding?: string): StringSchema; + min(limit: number, encoding?: string): this; + min(limit: Reference, encoding?: string): this; /** * Specifies the maximum number of string characters. * @param limit - the maximum number of string characters allowed. It can also be a reference to another field. * @param encoding - if specified, the string length is calculated in bytes using the provided encoding. */ - max(limit: number, encoding?: string): StringSchema; - max(limit: Reference, encoding?: string): StringSchema; + max(limit: number, encoding?: string): this; + max(limit: Reference, encoding?: string): this; /** * Requires the number to be a credit card number (Using Lunh Algorithm). */ - creditCard(): StringSchema; + creditCard(): this; /** * Specifies the exact string length required * @param limit - the required string length. It can also be a reference to another field. * @param encoding - if specified, the string length is calculated in bytes using the provided encoding. */ - length(limit: number, encoding?: string): StringSchema; - length(limit: Reference, encoding?: string): StringSchema; + length(limit: number, encoding?: string): this; + length(limit: Reference, encoding?: string): this; /** * Defines a regular expression rule. * @param pattern - a regular expression object the string value must match against. * @param name - optional name for patterns (useful with multiple patterns). Defaults to 'required'. */ - regex(pattern: RegExp, name?: string): StringSchema; + regex(pattern: RegExp, name?: string): this; /** * Replace characters matching the given pattern with the specified replacement string where: * @param pattern - a regular expression object to match against, or a string of which all occurrences will be replaced. * @param replacement - the string that will replace the pattern. */ - replace(pattern: RegExp, replacement: string): StringSchema; - replace(pattern: string, replacement: string): StringSchema; + replace(pattern: RegExp, replacement: string): this; + replace(pattern: string, replacement: string): this; /** * Requires the string value to only contain a-z, A-Z, and 0-9. */ - alphanum(): StringSchema; + alphanum(): this; /** * Requires the string value to only contain a-z, A-Z, 0-9, and underscore _. */ - token(): StringSchema; + token(): this; /** * Requires the string value to be a valid email address. */ - email(options?: EmailOptions): StringSchema; + email(options?: EmailOptions): this; /** * Requires the string value to be a valid ip address. */ - ip(options?: IpOptions): StringSchema; + ip(options?: IpOptions): this; /** * Requires the string value to be a valid RFC 3986 URI. */ - uri(options?: UriOptions): StringSchema; + uri(options?: UriOptions): this; /** * Requires the string value to be a valid GUID. */ - guid(options?: GuidOptions): StringSchema; + guid(options?: GuidOptions): this; /** * Requires the string value to be a valid hexadecimal string. */ - hex(): StringSchema; + hex(): this; /** * Requires the string value to be a valid hostname as per RFC1123. */ - hostname(): StringSchema; + hostname(): this; /** * Requires the string value to be in valid ISO 8601 date format. */ - isoDate(): StringSchema; + isoDate(): this; /** * Requires the string value to be all lowercase. If the validation convert option is on (enabled by default), the string will be forced to lowercase. */ - lowercase(): StringSchema; + lowercase(): this; /** * Requires the string value to be all uppercase. If the validation convert option is on (enabled by default), the string will be forced to uppercase. */ - uppercase(): StringSchema; + uppercase(): this; /** * Requires the string value to contain no whitespace before or after. If the validation convert option is on (enabled by default), the string will be trimmed. */ - trim(): StringSchema; + trim(): this; } export interface ArraySchema extends AnySchema { @@ -592,13 +589,13 @@ export interface ArraySchema extends AnySchema { * Allow this array to be sparse. * enabled can be used with a falsy value to go back to the default behavior. */ - sparse(enabled?: any): ArraySchema; + sparse(enabled?: any): this; /** * Allow single values to be checked against rules as if it were provided as an array. * enabled can be used with a falsy value to go back to the default behavior. */ - single(enabled?: any): ArraySchema; + single(enabled?: any): this; /** * List the types allowed for the array values. @@ -611,122 +608,122 @@ export interface ArraySchema extends AnySchema { * * @param type - a joi schema object to validate each array item against. */ - items(...types: SchemaLike[]): ArraySchema; - items(types: SchemaLike[]): ArraySchema; + items(...types: SchemaLike[]): this; + items(types: SchemaLike[]): this; /** * Lists the types in sequence order for the array values where: * @param type - a joi schema object to validate against each array item in sequence order. type can be an array of values, or multiple values can be passed as individual arguments. * If a given type is .required() then there must be a matching item with the same index position in the array. Errors will contain the number of items that didn't match. Any unmatched item having a label will be mentioned explicitly. */ - ordered(...types: SchemaLike[]): ArraySchema; - ordered(types: SchemaLike[]): ArraySchema; + ordered(...types: SchemaLike[]): this; + ordered(types: SchemaLike[]): this; /** * Specifies the minimum number of items in the array. */ - min(limit: number): ArraySchema; + min(limit: number): this; /** * Specifies the maximum number of items in the array. */ - max(limit: number): ArraySchema; + max(limit: number): this; /** * Specifies the exact number of items in the array. */ - length(limit: number): ArraySchema; + length(limit: number): this; /** * Requires the array values to be unique. * Be aware that a deep equality is performed on elements of the array having a type of object, * a performance penalty is to be expected for this kind of operation. */ - unique(comparator?: (a: any, b: any) => boolean): ArraySchema; - unique(comparator?: string): ArraySchema; + unique(comparator?: string): this; + unique(comparator?: (a: T, b: T) => boolean): this; } export interface ObjectSchema extends AnySchema { /** * Sets the allowed object keys. */ - keys(schema?: SchemaMap): ObjectSchema; + keys(schema?: SchemaMap): this; /** * Specifies the minimum number of keys in the object. */ - min(limit: number): ObjectSchema; + min(limit: number): this; /** * Specifies the maximum number of keys in the object. */ - max(limit: number): ObjectSchema; + max(limit: number): this; /** * Specifies the exact number of keys in the object. */ - length(limit: number): ObjectSchema; + length(limit: number): this; /** * Specify validation rules for unknown keys matching a pattern. */ - pattern(regex: RegExp, schema: SchemaLike): ObjectSchema; + pattern(regex: RegExp, schema: SchemaLike): this; /** * Defines an all-or-nothing relationship between keys where if one of the peers is present, all of them are required as well. * @param peers - the key names of which if one present, all are required. peers can be a single string value, * an array of string values, or each peer provided as an argument. */ - and(peer1: string, ...peers: string[]): ObjectSchema; - and(peers: string[]): ObjectSchema; + and(...peers: string[]): this; + and(peers: string[]): this; /** * Defines a relationship between keys where not all peers can be present at the same time. * @param peers - the key names of which if one present, the others may not all be present. * peers can be a single string value, an array of string values, or each peer provided as an argument. */ - nand(peer1: string, ...peers: string[]): ObjectSchema; - nand(peers: string[]): ObjectSchema; + nand(...peers: string[]): this; + nand(peers: string[]): this; /** * Defines a relationship between keys where one of the peers is required (and more than one is allowed). */ - or(peer1: string, ...peers: string[]): ObjectSchema; - or(peers: string[]): ObjectSchema; + or(...peers: string[]): this; + or(peers: string[]): this; /** * Defines an exclusive relationship between a set of keys. one of them is required but not at the same time where: */ - xor(peer1: string, ...peers: string[]): ObjectSchema; - xor(peers: string[]): ObjectSchema; + xor(...peers: string[]): this; + xor(peers: string[]): this; /** * Requires the presence of other keys whenever the specified key is present. */ - with(key: string, peers: string): ObjectSchema; - with(key: string, peers: string[]): ObjectSchema; + with(key: string, peers: string): this; + with(key: string, peers: string[]): this; /** * Forbids the presence of other keys whenever the specified is present. */ - without(key: string, peers: string): ObjectSchema; - without(key: string, peers: string[]): ObjectSchema; + without(key: string, peers: string): this; + without(key: string, peers: string[]): this; /** * Renames a key to another name (deletes the renamed key). */ - rename(from: string, to: string, options?: RenameOptions): ObjectSchema; + rename(from: string, to: string, options?: RenameOptions): this; /** * Verifies an assertion where. */ - assert(ref: string, schema: SchemaLike, message?: string): ObjectSchema; - assert(ref: Reference, schema: SchemaLike, message?: string): ObjectSchema; + assert(ref: string, schema: SchemaLike, message?: string): this; + assert(ref: Reference, schema: SchemaLike, message?: string): this; /** * Overrides the handling of unknown keys for the scope of the current object only (does not apply to children). */ - unknown(allow?: boolean): ObjectSchema; + unknown(allow?: boolean): this; /** * Requires the object to be an instance of a given constructor. @@ -734,7 +731,7 @@ export interface ObjectSchema extends AnySchema { * @param constructor - the constructor function that the object must be an instance of. * @param name - an alternate name to use in validation errors. This is useful when the constructor function does not have a name. */ - type(constructor: Function, name?: string): ObjectSchema; + type(constructor: Function, name?: string): this; /** * Sets the specified children to required. @@ -746,9 +743,8 @@ export interface ObjectSchema extends AnySchema { * * Note that in this example '' means the current object, a is not required but b is, as well as c and d. */ - requiredKeys(children: string): ObjectSchema; - requiredKeys(children: string[]): ObjectSchema; - requiredKeys(child: string, ...children: string[]): ObjectSchema; + requiredKeys(children: string[]): this; + requiredKeys(...children: string[]): this; /** * Sets the specified children to optional. @@ -757,31 +753,30 @@ export interface ObjectSchema extends AnySchema { * * The behavior is exactly the same as requiredKeys. */ - optionalKeys(children: string): ObjectSchema; - optionalKeys(children: string[]): ObjectSchema; - optionalKeys(child: string, ...children: string[]): ObjectSchema; + optionalKeys(children: string[]): this; + optionalKeys(...children: string[]): this; } export interface BinarySchema extends AnySchema { /** * Sets the string encoding format if a string input is converted to a buffer. */ - encoding(encoding: string): BinarySchema; + encoding(encoding: string): this; /** * Specifies the minimum length of the buffer. */ - min(limit: number): BinarySchema; + min(limit: number): this; /** * Specifies the maximum length of the buffer. */ - max(limit: number): BinarySchema; + max(limit: number): this; /** * Specifies the exact length of the buffer: */ - length(limit: number): BinarySchema; + length(limit: number): this; } export interface DateSchema extends AnySchema { @@ -792,10 +787,10 @@ export interface DateSchema extends AnySchema { * allowing to explicitly ensure a date is either in the past or in the future. * It can also be a reference to another field. */ - min(date: Date): DateSchema; - min(date: number): DateSchema; - min(date: string): DateSchema; - min(date: Reference): DateSchema; + min(date: Date): this; + min(date: number): this; + min(date: string): this; + min(date: Reference): this; /** * Specifies the latest date allowed. @@ -803,29 +798,28 @@ export interface DateSchema extends AnySchema { * allowing to explicitly ensure a date is either in the past or in the future. * It can also be a reference to another field. */ - max(date: Date): DateSchema; - max(date: number): DateSchema; - max(date: string): DateSchema; - max(date: Reference): DateSchema; + max(date: Date): this; + max(date: number): this; + max(date: string): this; + max(date: Reference): this; /** * Specifies the allowed date format: * @param format - string or array of strings that follow the moment.js format. */ - format(format: string): DateSchema; - format(format: string[]): DateSchema; + format(format: string): this; + format(format: string[]): this; /** * Requires the string value to be in valid ISO 8601 date format. */ - iso(): DateSchema; - + iso(): this; /** * Requires the value to be a timestamp interval from Unix Time. * @param type - the type of timestamp (allowed values are unix or javascript [default]) */ - timestamp(type?: 'javascript' | 'unix'): DateSchema; + timestamp(type?: 'javascript' | 'unix'): this; } export interface FunctionSchema extends AnySchema { @@ -834,49 +828,55 @@ export interface FunctionSchema extends AnySchema { * Specifies the arity of the function where: * @param n - the arity expected. */ - arity(n: number): FunctionSchema; - + arity(n: number): this; /** * Specifies the minimal arity of the function where: * @param n - the minimal arity expected. */ - minArity(n: number): FunctionSchema; - + minArity(n: number): this; /** * Specifies the minimal arity of the function where: * @param n - the minimal arity expected. */ - maxArity(n: number): FunctionSchema; + maxArity(n: number): this; /** * Requires the function to be a Joi reference. */ - ref(): FunctionSchema; + ref(): this; } export interface AlternativesSchema extends AnySchema { - try(schemas: SchemaLike[]): AlternativesSchema; - try(...types: SchemaLike[]): AlternativesSchema; - when(ref: string, options: WhenOptions): AlternativesSchema; - when(ref: Reference, options: WhenOptions): AlternativesSchema; + try(types: SchemaLike[]): this; + try(...types: SchemaLike[]): this; + when(ref: string, options: WhenOptions): this; + when(ref: Reference, options: WhenOptions): this; +} + +export interface LazySchema extends AnySchema { + +} + +export interface Reference extends AnySchema { + } export interface Rules

{ name: string; - params?: {[key in keyof P]: SchemaLike }; - setup?: (this: Schema, params: P) => Schema | void; - validate?: (this: Schema, params: P, value: any, state: State, options: ValidationOptions) => Err | R; + params?: { [key in keyof P]: SchemaLike; }; + setup?(this: Schema, params: P): Schema | void; + validate?(this: Schema, params: P, value: any, state: State, options: ValidationOptions): Err | R; description?: string | ((params: P) => string); } export interface Extension { name: string; base?: Schema; - pre?: (this: Schema, value: any, state: State, options: ValidationOptions) => Err | R; language?: LanguageOptions; - describe?: (this: Schema, description: Description) => Description; + pre?(this: Schema, value: any, state: State, options: ValidationOptions): Err | R; + describe?(this: Schema, description: Description): Description; rules?: Rules[]; } @@ -889,7 +889,7 @@ export interface Err { /** * Generates a schema object that matches any data type. */ -export function any(): Schema; +export function any(): AnySchema; /** * Generates a schema object that matches an array data type. @@ -945,7 +945,7 @@ export function alternatives(...types: SchemaLike[]): AlternativesSchema; * Supports the same methods of the any() type. * This is mostly useful for recursive schemas */ -export function lazy(cb: () => Schema): Schema; +export function lazy(cb: () => Schema): LazySchema; /** * Validates a value using the given schema and options. @@ -960,6 +960,7 @@ export function validate(value: T, schema: SchemaLike, options: Validation * Converts literal schema definition to joi schema object (or returns the same back if already a joi schema object). */ export function compile(schema: SchemaLike): Schema; +export function compile(schema: SchemaLike): T; /** * Validates a value against a schema and throws if validation fails. @@ -970,7 +971,6 @@ export function compile(schema: SchemaLike): Schema; */ export function assert(value: any, schema: SchemaLike, message?: string | Error): void; - /** * Validates a value against a schema, returns valid object, and throws if validation fails where: * @@ -980,18 +980,15 @@ export function assert(value: any, schema: SchemaLike, message?: string | Error) */ export function attempt(value: T, schema: SchemaLike, message?: string | Error): T; - /** * Generates a reference to the value of the named key. */ export function ref(key: string, options?: ReferenceOptions): Reference; - /** * Checks whether or not the provided argument is a reference. It's especially useful if you want to post-process error messages. */ -export function isRef(ref: any): boolean; - +export function isRef(ref: any): ref is Reference; /** * Get a sub-schema of an existing schema based on a path. Path separator is a dot (.). @@ -999,7 +996,6 @@ export function isRef(ref: any): boolean; export function reach(schema: ObjectSchema, path: string): Schema; export function reach(schema: ObjectSchema, path: string): T; - /** * Creates a new Joi instance customized with the extension(s) you provide included. */