diff --git a/README.md b/README.md index 5f1e85d9..355f18fa 100644 --- a/README.md +++ b/README.md @@ -176,60 +176,7 @@ Take a look at the [Gherkin](https://cucumber.io/docs/gherkin/) specification, w ## Type definitions -Type definitions below are described using [TypeScript](https://www.typescriptlang.org/) syntax. - -### Input - -> Gavel makes no assumptions over the validity of a given HTTP message according to the HTTP specification (RFCs [2616](https://www.ietf.org/rfc/rfc2616.txt), [7540](https://httpwg.org/specs/rfc7540.html)) and will accept any input matching the input type definition. Gavel will throw an exception when given malformed input data. - -Both expected and actual HTTP messages (no matter request or response) inherit from a single `HttpMessage` interface: - -```ts -interface HttpMessage { - uri?: string; - method?: string; - statusCode?: number; - headers?: Record | string; - body?: string; - bodySchema?: Object | string; -} -``` - -### Output - -```ts -// Field kind describes the type of a field's values -// subjected to the end comparison. -enum ValidationKind { - null // non-comparable data (validation didn't happen) - text // compared as text - json // compared as JSON -} - -interface ValidationResult { - valid: boolean // validity of the actual message - fields: { - [fieldName: string]: { - valid: boolean // validity of a single field - kind: ValidationKind - values: { // end compared values (coerced, normalized) - actual: any - expected: any - } - errors: FieldError[] - } - } -} - -interface FieldError { - message: string - location?: { // kind-specific additional information - // kind: json - pointer?: string - property?: string[] - } -} -``` +Gavel ships with [TypeScript type definitions](./typings.d.ts). Please refer to the definitions file for more details. ## API diff --git a/package.json b/package.json index ef10fdee..6f020239 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "version": "0.0.0-semantically-released", "description": "Validator of HTTP transactions (JavaScript implementation)", "main": "build/index.js", + "typings": "typings.d.ts", "engines": { "node": ">= 8" }, diff --git a/typings.d.ts b/typings.d.ts new file mode 100644 index 00000000..c002860e --- /dev/null +++ b/typings.d.ts @@ -0,0 +1,80 @@ +declare module 'gavel' { + export enum RESTMethods { + GET = 'GET', + POST = 'POST', + PUT = 'PUT', + PATCH = 'PATCH', + DELETE = 'DELETE', + OPTIONS = 'OPTIONS' + } + + export interface HTTPMessage { + method: RESTMethods; + uri: string; + statusCode: string | number; + headers: Record | string; + body: Record | string; + /** + * [JSON Schema](https://json-schema.org/) Draft V3-4. + */ + bodySchema: Record | string; + } + + export enum FieldKind { + text = 'text', + json = 'json' + } + + export interface ValidationResult { + /** + * Indicates whether the actual HTTP message is valid + * against the expected HTTP message. + */ + valid: boolean; + /** + * Validation results of each individual HTTP message + * field (i.e. "statusCode", "body", etc). + */ + fields: Record; + } + + export interface FieldValidationResult { + /** + * Indicates whether a single HTTP message field is valid. + */ + valid: boolean; + /** + * Kind of validation that has been applied to the field. + */ + kind: FieldKind | null; + /** + * Normalized HTTP message field values that are being validated. + */ + values: { + expected: any; + actual: any; + }; + errors: FieldValidationError[]; + } + + export interface FieldValidationError { + message: string; + /** + * Arbitrary information about the validation error. + * Dependends on the HTTP message field's "kind" property. + */ + location?: { + pointer?: string; + property?: string[]; + }; + } + + /** + * Validates a given expected HTTP message against + * the actual HTTP message. + */ + export function validate( + expectedMessage: Partial, + actualMessage: Partial + ): ValidationResult; +}