Merge pull request #300 from apiaryio/add-typings

Adds TypeScript type definitions

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> | 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
 

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"
   },

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, string> | string;
+    body: Record<string, any> | string;
+    /**
+     * [JSON Schema](https://json-schema.org/) Draft V3-4.
+     */
+    bodySchema: Record<string, any> | 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<string, FieldValidationResult>;
+  }
+
+  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<HTTPMessage>,
+    actualMessage: Partial<HTTPMessage>
+  ): ValidationResult;
+}