diff --git a/types/joi/index.d.ts b/types/joi/index.d.ts index 68eb27ca93..af07b0bb2a 100644 --- a/types/joi/index.d.ts +++ b/types/joi/index.d.ts @@ -37,10 +37,10 @@ export interface ValidationOptions { skipFunctions?: boolean; /** * remove unknown elements from objects and arrays. Defaults to false - * - when true, all unknown elements will be removed - * - when an object: - * - arrays - set to true to remove unknown items from arrays. - * - objects - set to true to remove unknown keys from objects + * when true, all unknown elements will be removed + * when an object: + * arrays set to true to remove unknown items from arrays. + * objects set to true to remove unknown keys from objects */ stripUnknown?: boolean | { arrays?: boolean; objects?: boolean }; /** @@ -291,7 +291,7 @@ export interface AnySchema extends JoiObject { /** * Sets a default value if the original value is undefined. - * @param value - the value. + * @param value the value. * value supports references. * value may also be a function which returns the default value. * If value is specified as a function that accepts a single parameter, that parameter will be a context @@ -333,22 +333,22 @@ export interface AnySchema extends JoiObject { /** * Considers anything that matches the schema to be empty (undefined). - * @param schema - any object or joi schema to match. An undefined schema unsets that rule. + * @param schema any object or joi schema to match. An undefined schema unsets that rule. */ empty(schema?: SchemaLike): this; /** * Overrides the default joi error with a custom error if the rule fails where: - * @param err - can be: - * an instance of `Error` - the override error. + * @param err can be: + * an instance of `Error` the override error. * a `function(errors)`, taking an array of errors as argument, where it must either: - * return a `string` - substitutes the error message with this text + * return a `string` substitutes the error message with this text * return a single `object` or an `Array` of it, where: - * `type` - optional parameter providing the type of the error (eg. `number.min`). - * `message` - optional parameter if `template` is provided, containing the text of the error. - * `template` - optional parameter if `message` is provided, containing a template string, using the same format as usual joi language errors. - * `context` - optional parameter, to provide context to your error if you are using the `template`. - * return an `Error` - same as when you directly provide an `Error`, but you can customize the error message based on the errors. + * `type` optional parameter providing the type of the error (eg. `number.min`). + * `message` optional parameter if `template` is provided, containing the text of the error. + * `template` optional parameter if `message` is provided, containing a template string, using the same format as usual joi language errors. + * `context` optional parameter, to provide context to your error if you are using the `template`. + * return an `Error` same as when you directly provide an `Error`, but you can customize the error message based on the errors. * * Note that if you provide an `Error`, it will be returned as-is, unmodified and undecorated with any of the * normal joi error properties. If validation fails and another error is found before the error @@ -396,7 +396,7 @@ export interface BooleanSchema extends AnySchema { * Allows for additional values to be considered valid booleans by converting them to true during validation. * Accepts a value or an array of values. String comparisons are by default case insensitive, * see boolean.insensitive() to change this behavior. - * @param values - strings, numbers or arrays of them + * @param values strings, numbers or arrays of them */ truthy(...values: Array): this; @@ -404,7 +404,7 @@ export interface BooleanSchema extends AnySchema { * Allows for additional values to be considered valid booleans by converting them to false during validation. * Accepts a value or an array of values. String comparisons are by default case insensitive, * see boolean.insensitive() to change this behavior. - * @param values - strings, numbers or arrays of them + * @param values strings, numbers or arrays of them */ falsy(...values: Array): this; @@ -452,7 +452,7 @@ export interface NumberSchema extends AnySchema { /** * Specifies the maximum number of decimal places where: - * limit - the maximum number of decimal places allowed. + * limit the maximum number of decimal places allowed. */ precision(limit: number): this; @@ -480,16 +480,16 @@ export interface StringSchema extends AnySchema { /** * 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. + * @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): 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. + * @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): this; max(limit: Reference, encoding?: string): this; @@ -501,23 +501,23 @@ export interface StringSchema extends AnySchema { /** * 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. + * @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): 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'. + * @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): 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. + * @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): this; replace(pattern: string, replacement: string): this; @@ -553,7 +553,7 @@ export interface StringSchema extends AnySchema { guid(options?: GuidOptions): this; /** - * Alias for `guid` -- Requires the string value to be a valid GUID + * Alias for `guid`- Requires the string value to be a valid GUID */ uuid(options?: GuidOptions): this; @@ -610,14 +610,14 @@ export interface ArraySchema extends AnySchema { * Errors will contain the number of items that didn't match. * Any unmatched item having a label will be mentioned explicitly. * - * @param type - a joi schema object to validate each array item against. + * @param type a joi schema object to validate each array item against. */ 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. + * @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[]): this; @@ -675,7 +675,7 @@ export interface ObjectSchema extends AnySchema { /** * 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, + * @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(...peers: string[]): this; @@ -683,7 +683,7 @@ export interface ObjectSchema extends AnySchema { /** * 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. + * @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(...peers: string[]): this; @@ -732,15 +732,15 @@ export interface ObjectSchema extends AnySchema { /** * Requires the object to be an instance of a given constructor. * - * @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. + * @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): this; /** * Sets the specified children to required. * - * @param children - can be a single string value, an array of string values, or each child provided as an argument. + * @param children can be a single string value, an array of string values, or each child provided as an argument. * * var schema = Joi.object().keys({ a: { b: Joi.number() }, c: { d: Joi.string() } }); * var requiredSchema = schema.requiredKeys('', 'a.b', 'c', 'c.d'); @@ -753,7 +753,7 @@ export interface ObjectSchema extends AnySchema { /** * Sets the specified children to optional. * - * @param children - can be a single string value, an array of string values, or each child provided as an argument. + * @param children can be a single string value, an array of string values, or each child provided as an argument. * * The behavior is exactly the same as requiredKeys. */ @@ -809,7 +809,7 @@ export interface DateSchema extends AnySchema { /** * Specifies the allowed date format: - * @param format - string or array of strings that follow the moment.js format. + * @param format string or array of strings that follow the moment.js format. */ format(format: string): this; format(format: string[]): this; @@ -821,7 +821,7 @@ export interface DateSchema extends AnySchema { /** * Requires the value to be a timestamp interval from Unix Time. - * @param type - the type of timestamp (allowed values are unix or javascript [default]) + * @param type the type of timestamp (allowed values are unix or javascript [default]) */ timestamp(type?: 'javascript' | 'unix'): this; } @@ -830,19 +830,19 @@ export interface FunctionSchema extends AnySchema { /** * Specifies the arity of the function where: - * @param n - the arity expected. + * @param n the arity expected. */ arity(n: number): this; /** * Specifies the minimal arity of the function where: - * @param n - the minimal arity expected. + * @param n the minimal arity expected. */ minArity(n: number): this; /** * Specifies the minimal arity of the function where: - * @param n - the minimal arity expected. + * @param n the minimal arity expected. */ maxArity(n: number): this; @@ -875,17 +875,17 @@ export type ExtensionBoundSchema = Schema & { /** * Creates a joi error object. * Used in conjunction with custom rules. - * @param type - the type of rule to create the error for. - * @param context - provide properties that will be available in the `language` templates. - * @param state - should the context passed into the `validate` function in a custom rule - * @param options - should the context passed into the `validate` function in a custom rule + * @param type the type of rule to create the error for. + * @param context provide properties that will be available in the `language` templates. + * @param state should the context passed into the `validate` function in a custom rule + * @param options should the context passed into the `validate` function in a custom rule */ createError(type: string, context: Context, state: State, options: ValidationOptions): Err; } export interface Rules

{ name: string; - params?: ObjectSchema | { [key in keyof P]: SchemaLike; }; + params?: ObjectSchema | {[key in keyof P]: SchemaLike; }; setup?(this: ExtensionBoundSchema, params: P): Schema | void; validate?(this: ExtensionBoundSchema, params: P, value: any, state: State, options: ValidationOptions): Err | R; description?: string | ((params: P) => string); @@ -905,7 +905,7 @@ export interface Err extends JoiObject { toString(): string; } -// --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- +//-------------------------------------------------- /** * Current version of the joi package. @@ -996,18 +996,18 @@ export function compile(schema: SchemaLike): T; /** * Validates a value against a schema and throws if validation fails. * - * @param value - the value to validate. - * @param schema - the schema object. - * @param message - optional message string prefix added in front of the error message. may also be an Error object. + * @param value the value to validate. + * @param schema the schema object. + * @param message optional message string prefix added in front of the error message. may also be an Error object. */ 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: * - * @param value - the value to validate. - * @param schema - the schema object. - * @param message - optional message string prefix added in front of the error message. may also be an Error object. + * @param value the value to validate. + * @param schema the schema object. + * @param message optional message string prefix added in front of the error message. may also be an Error object. */ export function attempt(value: T, schema: SchemaLike, message?: string | Error): T; @@ -1032,8 +1032,124 @@ export function reach(schema: ObjectSchema, path: string): T; */ export function extend(extention: Extension): any; +// Below are undocumented APIs. use them at your own risk + /** * Returns a plain object representing the schema's rules and properties */ export function describe(schema: Schema): Description; +/** +* Whitelists a value +*/ +export function allow(value: any, ...values: any[]): Schema; +export function allow(values: any[]): Schema; + +/** + * Adds the provided values into the allowed whitelist and marks them as the only valid values allowed. + */ +export function valid(value: any, ...values: any[]): Schema; +export function valid(values: any[]): Schema; +export function only(value: any, ...values: any[]): Schema; +export function only(values: any[]): Schema; +export function equal(value: any, ...values: any[]): Schema; +export function equal(values: any[]): Schema; + +/** + * Blacklists a value + */ +export function invalid(value: any, ...values: any[]): Schema; +export function invalid(values: any[]): Schema; +export function disallow(value: any, ...values: any[]): Schema; +export function disallow(values: any[]): Schema; +export function not(value: any, ...values: any[]): Schema; +export function not(values: any[]): Schema; + +/** + * Marks a key as required which will not allow undefined as value. All keys are optional by default. + */ +export function required(): Schema; + +/** + * Marks a key as optional which will allow undefined as values. Used to annotate the schema for readability as all keys are optional by default. + */ +export function optional(): Schema; + +/** + * Marks a key as forbidden which will not allow any value except undefined. Used to explicitly forbid keys. + */ +export function forbidden(): Schema; + +/** + * Marks a key to be removed from a resulting object or array after validation. Used to sanitize output. + */ +export function strip(): Schema; + +/** + * Annotates the key + */ +export function description(desc: string): Schema; + +/** + * Annotates the key + */ +export function notes(notes: string): Schema; +export function notes(notes: string[]): Schema; + +/** + * Annotates the key + */ +export function tags(notes: string): Schema; +export function tags(notes: string[]): Schema; + +/** + * Attaches metadata to the key. + */ +export function meta(meta: Object): Schema; + +/** + * Annotates the key with an example value, must be valid. + */ +export function example(value: any): Schema; + +/** + * Annotates the key with an unit name. + */ +export function unit(name: string): Schema; + +/** + * Overrides the global validate() options for the current key and any sub-key. + */ +export function options(options: ValidationOptions): Schema; + +/** + * Sets the options.convert options to false which prevent type casting for the current key and any child keys. + */ +export function strict(isStrict?: boolean): Schema; + +/** + * Returns a new type that is the result of adding the rules of one type to another. + */ +export function concat(schema: T): T; + +/** + * Converts the type into an alternatives type where the conditions are merged into the type definition where: + */ +export function when(ref: string, options: WhenOptions): AlternativesSchema; +export function when(ref: Reference, options: WhenOptions): AlternativesSchema; + +/** + * Overrides the key name in error messages. + */ +export function label(name: string): Schema; + +/** + * Outputs the original untouched value instead of the casted value. + */ +export function raw(isRaw?: boolean): Schema; + +/** + * Considers anything that matches the schema to be empty (undefined). + * @param schema any object or joi schema to match. An undefined schema unsets that rule. + */ +export function empty(schema?: any): Schema; diff --git a/types/joi/joi-tests.ts b/types/joi/joi-tests.ts index 5f44e6ad01..f83196a983 100644 --- a/types/joi/joi-tests.ts +++ b/types/joi/joi-tests.ts @@ -957,3 +957,56 @@ const Joi3 = Joi.extend({ }, ], }); + +// --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- + +schema = Joi.allow(x, x); +schema = Joi.allow([x, x, x]); +schema = Joi.valid(x); +schema = Joi.valid(x, x); +schema = Joi.valid([x, x, x]); +schema = Joi.only(x); +schema = Joi.only(x, x); +schema = Joi.only([x, x, x]); +schema = Joi.equal(x); +schema = Joi.equal(x, x); +schema = Joi.equal([x, x, x]); +schema = Joi.invalid(x); +schema = Joi.invalid(x, x); +schema = Joi.invalid([x, x, x]); +schema = Joi.disallow(x); +schema = Joi.disallow(x, x); +schema = Joi.disallow([x, x, x]); +schema = Joi.not(x); +schema = Joi.not(x, x); +schema = Joi.not([x, x, x]); + +schema = Joi.required(); +schema = Joi.optional(); +schema = Joi.forbidden(); +schema = Joi.strip(); + +schema = Joi.description(str); +schema = Joi.notes(str); +schema = Joi.notes(strArr); +schema = Joi.tags(str); +schema = Joi.tags(strArr); + +schema = Joi.meta(obj); +schema = Joi.example(obj); +schema = Joi.unit(str); + +schema = Joi.options(validOpts); +schema = Joi.strict(); +schema = Joi.strict(bool); +schema = Joi.concat(x); + +schema = Joi.when(str, whenOpts); +schema = Joi.when(ref, whenOpts); + +schema = Joi.label(str); +schema = Joi.raw(); +schema = Joi.raw(bool); +schema = Joi.empty(); +schema = Joi.empty(str); +schema = Joi.empty(anySchema);