From 98b47fbc86a350d1baed86e3d0c7bf64c8decb16 Mon Sep 17 00:00:00 2001 From: pgonzal Date: Thu, 19 Jan 2017 18:30:59 +0100 Subject: [PATCH] Fix z-schema module definition and add SchemaErrorDetail (#14005) * Fix module declaration so that helper interfaces are usable again * Introduce SchemaErrorDetail since getLastError() and getLastErrors() return two distinct types; add documentation * Fix unit tests, add explicit type declarations * Transferred project ownership from Adam * Eliminated ambient external module by making Validator into a merged class and namespace --- z-schema/index.d.ts | 170 ++++++++++++++++++++++++------------- z-schema/z-schema-tests.ts | 11 ++- 2 files changed, 115 insertions(+), 66 deletions(-) diff --git a/z-schema/index.d.ts b/z-schema/index.d.ts index f49e677158..695866a7e9 100644 --- a/z-schema/index.d.ts +++ b/z-schema/index.d.ts @@ -1,13 +1,9 @@ // Type definitions for z-schema v3.16.0 // Project: https://github.com/zaggino/z-schema -// Definitions by: Adam Meadows +// Definitions by: pgonzal // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -export = ZSchema.Validator; -export as namespace ZSchema; - -declare namespace ZSchema { - +declare namespace Validator { export interface Options { asyncTimeout?: number; forceAdditional?: boolean; @@ -31,66 +27,120 @@ declare namespace ZSchema { ignoreUnknownFormats?: boolean; } - export interface SchemaError { - code: string; - description: string; + export interface SchemaError extends Error { + /** + * Implements the Error.name contract. The value is always "z-schema validation error". + */ + name: string; + + /** + * An identifier indicating the type of error. + * Example: "JSON_OBJECT_VALIDATION_FAILED" + */ message: string; - params: string[]; + + /** + * Returns details for each error that occurred during validation. + * See Options.breakOnFirstError. + */ + details: SchemaErrorDetail[]; + } + + export interface SchemaErrorDetail { + /** + * Example: "Expected type string but found type array" + */ + message: string; + /** + * An error identifier that can be used to format a custom error message. + * Example: "INVALID_TYPE" + */ + code: string; + /** + * Format parameters that can be used to format a custom error message. + * Example: ["string","array"] + */ + params: Array; + /** + * A JSON path indicating the location of the error. + * Example: "#/projects/1" + */ path: string; + /** + * The schema rule description, which is included for certain errors where + * this information is useful (e.g. to describe a constraint). + */ + description: string; + + /** + * Returns details for sub-schemas that failed to match. For example, if the schema + * uses the "oneOf" constraint to accept several alternative possibilities, each + * alternative will have its own inner detail object explaining why it failed to match. + */ + inner: SchemaErrorDetail[]; } +} - export class Validator { - - /** - * Register a custom format. - * - * @param name - name of the custom format - * @param validatorFunction - custom format validator function. - * Returns `true` if `value` matches the custom format. - */ - public static registerFormat(formatName: string, validatorFunction: (value: any) => boolean): void; +declare class Validator { + /** + * Register a custom format. + * + * @param name - name of the custom format + * @param validatorFunction - custom format validator function. + * Returns `true` if `value` matches the custom format. + */ + public static registerFormat(formatName: string, validatorFunction: (value: any) => boolean): void; - /** - * Unregister a format. - * - * @param name - name of the custom format - */ - public static unregisterFormat(name: string): void; - - /** - * Get the list of all registered formats. - * - * Both the names of the burned-in formats and the custom format names are - * returned by this function. - * - * @returns {string[]} the list of all registered format names. - */ - public static getRegisteredFormats(): string[]; - - public static getDefaultOptions(): Options; - - constructor(options: Options); + /** + * Unregister a format. + * + * @param name - name of the custom format + */ + public static unregisterFormat(name: string): void; - /** - * @param schema - JSON object representing schema - * @returns {boolean} true if schema is valid. - */ - validateSchema(schema: any): boolean; + /** + * Get the list of all registered formats. + * + * Both the names of the burned-in formats and the custom format names are + * returned by this function. + * + * @returns {string[]} the list of all registered format names. + */ + public static getRegisteredFormats(): string[]; - /** - * @param json - either a JSON string or a parsed JSON object - * @param schema - the JSON object representing the schema - * @returns true if json matches schema - */ - validate(json: any, schema: any): boolean; + public static getDefaultOptions(): Validator.Options; - /** - * @param json - either a JSON string or a parsed JSON object - * @param schema - the JSON object representing the schema - */ - validate(json: any, schema: any, callback: (err: any, valid: boolean) => void): void; + constructor(options: Validator.Options); - getLastError(): SchemaError; - getLastErrors(): SchemaError[]; - } -} \ No newline at end of file + /** + * @param schema - JSON object representing schema + * @returns {boolean} true if schema is valid. + */ + validateSchema(schema: any): boolean; + + /** + * @param json - either a JSON string or a parsed JSON object + * @param schema - the JSON object representing the schema + * @returns true if json matches schema + */ + validate(json: any, schema: any): boolean; + + /** + * @param json - either a JSON string or a parsed JSON object + * @param schema - the JSON object representing the schema + */ + validate(json: any, schema: any, callback: (err: any, valid: boolean) => void): void; + + /** + * Returns an Error object for the most recent failed validation, or null if the validation was successful. + */ + getLastError(): Validator.SchemaError; + + /** + * Returns the error details for the most recent validation, or undefined if the validation was successful. + * This is the same list as the SchemaError.details property. + */ + getLastErrors(): Validator.SchemaErrorDetail[]; +} + +export = Validator; diff --git a/z-schema/z-schema-tests.ts b/z-schema/z-schema-tests.ts index 042c5dfe62..9f1c81ff7f 100644 --- a/z-schema/z-schema-tests.ts +++ b/z-schema/z-schema-tests.ts @@ -1,13 +1,12 @@ +import Validator = require('z-schema'); -import ZSchema = require('z-schema'); - -var options = { +var options: Validator.Options = { noTypeless: true, forceItems: true, }; -var validator = new ZSchema(options); +var validator: Validator = new Validator(options); var json: any = { foo: 'bar', }; @@ -31,5 +30,5 @@ validator.validate(json, schema, function (err: any, valid: boolean) { } }); -var error = validator.getLastError(); -var errors = validator.getLastErrors(); +var error: Validator.SchemaError = validator.getLastError(); +var errors: Validator.SchemaErrorDetail[] = validator.getLastErrors();