@typespec/spec-api 0.1.0-alpha.0

package/src/request-validations.ts

@@ -0,0 +1,216 @@
+import deepEqual from "deep-equal";
+import * as prettier from "prettier";
+import { parseString } from "xml2js";
+import { CollectionFormat, RequestExt } from "./types.js";
+import { ValidationError } from "./validation-error.js";
+
+export const BODY_NOT_EQUAL_ERROR_MESSAGE = "Body provided doesn't match expected body";
+export const BODY_EMPTY_ERROR_MESSAGE = "Body should exists";
+export const BODY_NOT_EMPTY_ERROR_MESSAGE = "Body should be empty";
+
+export const validateRawBodyEquals = (
+  request: RequestExt,
+  expectedRawBody: string | Buffer | undefined,
+): void => {
+  const actualRawBody = request.rawBody;
+
+  if (expectedRawBody == null) {
+    if (!isBodyEmpty(actualRawBody)) {
+      throw new ValidationError(BODY_NOT_EQUAL_ERROR_MESSAGE, expectedRawBody, actualRawBody);
+    }
+    return;
+  }
+
+  if (!deepEqual(actualRawBody, expectedRawBody, { strict: true })) {
+    throw new ValidationError(BODY_NOT_EQUAL_ERROR_MESSAGE, expectedRawBody, actualRawBody);
+  }
+};
+
+export const validateBodyEquals = (
+  request: RequestExt,
+  expectedBody: unknown | undefined,
+): void => {
+  if (expectedBody == null) {
+    if (!isBodyEmpty(request.rawBody)) {
+      throw new ValidationError(BODY_NOT_EQUAL_ERROR_MESSAGE, expectedBody, request.rawBody);
+    }
+    return;
+  }
+
+  if (!deepEqual(request.body, expectedBody, { strict: true })) {
+    throw new ValidationError(BODY_NOT_EQUAL_ERROR_MESSAGE, expectedBody, request.body);
+  }
+};
+
+export const validateXmlBodyEquals = (request: RequestExt, expectedBody: string): void => {
+  if (request.rawBody === undefined || isBodyEmpty(request.rawBody)) {
+    throw new ValidationError(BODY_EMPTY_ERROR_MESSAGE, expectedBody, request.rawBody);
+  }
+
+  expectedBody = `<?xml version='1.0' encoding='UTF-8'?>` + expectedBody;
+
+  let actualParsedBody = "";
+  parseString(request.rawBody, (err: Error | null, result: any): void => {
+    if (err !== null) {
+      throw err;
+    }
+    actualParsedBody = result;
+  });
+
+  let expectedParsedBody = "";
+  parseString(expectedBody, (err: Error | null, result: any): void => {
+    if (err !== null) {
+      throw err;
+    }
+    expectedParsedBody = result;
+  });
+
+  if (!deepEqual(actualParsedBody, expectedParsedBody, { strict: true })) {
+    throw new ValidationError(
+      BODY_NOT_EQUAL_ERROR_MESSAGE,
+      prettier.format(expectedBody),
+      prettier.format(request.body),
+    );
+  }
+};
+
+export const validateCoercedDateBodyEquals = (
+  request: RequestExt,
+  expectedBody: unknown | undefined,
+): void => {
+  if (expectedBody == null) {
+    if (!isBodyEmpty(request.rawBody)) {
+      throw new ValidationError(BODY_NOT_EQUAL_ERROR_MESSAGE, expectedBody, request.rawBody);
+    }
+    return;
+  }
+
+  if (!deepEqual(coerceDate(request.body), expectedBody, { strict: true })) {
+    throw new ValidationError(BODY_NOT_EQUAL_ERROR_MESSAGE, expectedBody, request.body);
+  }
+};
+
+export const validateBodyEmpty = (request: RequestExt): void => {
+  if (isBodyEmpty(request.rawBody)) {
+    if (request.body instanceof Buffer) {
+      if (request.body.length > 0) {
+        throw new ValidationError(BODY_NOT_EMPTY_ERROR_MESSAGE, undefined, request.rawBody);
+      }
+    }
+  } else {
+    throw new ValidationError(BODY_EMPTY_ERROR_MESSAGE, undefined, request.rawBody);
+  }
+};
+
+export const validateBodyNotEmpty = (request: RequestExt): void => {
+  if (isBodyEmpty(request.rawBody)) {
+    if (request.body instanceof Buffer) {
+      if (request.body.length === 0) {
+        throw new ValidationError(BODY_EMPTY_ERROR_MESSAGE, undefined, request.rawBody);
+      }
+    } else {
+      throw new ValidationError(BODY_EMPTY_ERROR_MESSAGE, undefined, request.rawBody);
+    }
+  }
+};
+
+/**
+ * Check if the provided body is empty.
+ * @param body express.js request body.
+ */
+const isBodyEmpty = (body: string | Buffer | undefined | null) => {
+  return body == null || body === "" || body.length === 0;
+};
+
+/**
+ * Check whether the request header contains the given name/value pair
+ */
+export const validateHeader = (request: RequestExt, headerName: string, expected: string): void => {
+  const actual = request.headers[headerName];
+  if (actual !== expected) {
+    throw new ValidationError(`Expected ${expected} but got ${actual}`, expected, actual);
+  }
+};
+
+/**
+ * Check whether the query string contains the given parameter name and value.
+ * Supports query param as string or collection. e.g. if it's a collection, one can call the method like this: validateQueryParam(request, ["a", "b", "c"], "multi")
+ */
+export const validateQueryParam = (
+  request: RequestExt,
+  paramName: string,
+  expected: string | string[],
+  collectionFormat?: CollectionFormat,
+): void => {
+  const actual = request.query[paramName];
+  const splitterMap = {
+    csv: ",",
+    ssv: " ",
+    tsv: "\t",
+    pipes: "|",
+  };
+  let isExpected = false;
+  if (collectionFormat && Array.isArray(expected)) {
+    // verify query parameter as collection
+    if (collectionFormat === "multi" && Array.isArray(actual)) {
+      isExpected = deepEqual(actual, expected);
+    } else if (collectionFormat !== "multi" && typeof actual === "string") {
+      const expectedString = expected.join(splitterMap[collectionFormat]);
+      isExpected = expectedString === decodeURIComponent(actual);
+    }
+    if (!isExpected) {
+      throw new ValidationError(
+        `Expected query param collection ${paramName}=${expected} in ${collectionFormat}, but got ${actual}`,
+        expected,
+        actual,
+      );
+    }
+  } else if (actual !== expected) {
+    throw new ValidationError(
+      `Expected query param ${paramName}=${expected} but got ${actual}`,
+      expected,
+      actual,
+    );
+  }
+};
+
+const coerceDate = (targetObject: Record<string, unknown>): Record<string, unknown> => {
+  let stringRep = JSON.stringify(targetObject);
+  stringRep = stringRep.replace(
+    /(\d\d\d\d-\d\d-\d\d[Tt]\d\d:\d\d:\d\d)(\.\d{3,7})?([Zz]|[+-]00:00)/g,
+    "$1Z",
+  );
+  return JSON.parse(stringRep);
+};
+
+/**
+ * Check whether the value follow the right format.
+ */
+export const validateValueFormat = (
+  value: string,
+  format: "uuid" | "rfc7231" | "rfc3339",
+): void => {
+  switch (format) {
+    case "uuid":
+      if (!/^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(value)) {
+        throw new ValidationError(`Expected uuid format but got ${value}`, "uuid", value);
+      }
+      break;
+    case "rfc7231":
+      if (
+        !/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun),\s\d{2}\s(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s\d{4}\s\d{2}:\d{2}:\d{2}\sGMT$/i.test(
+          value,
+        )
+      ) {
+        throw new ValidationError(`Expected rfc7231 format but got ${value}`, "rfc7231", value);
+      }
+      break;
+    case "rfc3339":
+      if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/i.test(value)) {
+        throw new ValidationError(`Expected rfc3339 format but got ${value}`, "rfc3339", value);
+      }
+      break;
+    default:
+      throw new ValidationError(`Unsupported format ${format}`, format, value);
+  }
+};

package/src/response-utils.ts

@@ -0,0 +1,26 @@
+import { MockResponseBody } from "./types.js";
+
+/**
+ * Serialize the provided content as json to use in a MockResponse body.
+ * @content Object to return as json.
+ * @returns {MockResponseBody} response body with application/json content type.
+ */
+export function json(content: unknown): MockResponseBody {
+  return {
+    contentType: "application/json",
+    rawContent: JSON.stringify(content),
+  };
+}
+
+/**
+ * Sends the provided XML string in a MockResponse body.
+ * The XML declaration prefix will automatically be added to xmlString.
+ * @content Object to return as XML.
+ * @returns {MockResponseBody} response body with application/xml content type.
+ */
+export function xml(xmlString: string): MockResponseBody {
+  return {
+    contentType: "application/xml",
+    rawContent: `<?xml version='1.0' encoding='UTF-8'?>` + xmlString,
+  };
+}

package/src/routes.ts

@@ -0,0 +1,92 @@
+import { HttpMethod, MockApiForHandler, MockRequestHandler } from "./types.js";
+
+/**
+ * Register a GET request for the provided uri.
+ * @param uri URI to match.
+ * @param func Request handler.
+ */
+function get<const T extends MockRequestHandler>(uri: string, func: T): MockApiForHandler<T> {
+  return request("get", uri, func);
+}
+
+/**
+ * Register a POST request for the provided uri.
+ * @param uri URI to match.
+ * @param func Request handler.
+ */
+function post<T extends MockRequestHandler>(uri: string, func: T): MockApiForHandler<T> {
+  return request("post", uri, func);
+}
+
+/**
+ * Register a PUT request for the provided uri.
+ * @param uri URI to match.
+ * @param func Request handler.
+ */
+function put<T extends MockRequestHandler>(uri: string, func: T): MockApiForHandler<T> {
+  return request("put", uri, func);
+}
+
+/**
+ * Register a PATCH request for the provided uri.
+ * @param uri URI to match.
+ * @param func Request handler.
+ */
+function patch<T extends MockRequestHandler>(uri: string, func: T): MockApiForHandler<T> {
+  return request("patch", uri, func);
+}
+
+/**
+ * Register a DELETE request for the provided uri.
+ * @param uri URI to match.
+ * @param func Request handler.
+ */
+function deleteReq<T extends MockRequestHandler>(uri: string, func: T): MockApiForHandler<T> {
+  return request("delete", uri, func);
+}
+
+/**
+ * Register a Options request for the provided uri.
+ * @param uri URI to match.
+ * @param func Request handler.
+ */
+function options<T extends MockRequestHandler>(uri: string, func: T): MockApiForHandler<T> {
+  return request("options", uri, func);
+}
+
+/**
+ * Register a HEAD request for the provided uri.
+ * @param uri URI to match.
+ * @param name Name of the scenario(For coverage).
+ * @param func Request handler.
+ */
+function head<T extends MockRequestHandler>(uri: string, func: T): MockApiForHandler<T> {
+  return request<T>("head", uri, func);
+}
+
+/**
+ * Register a request for the provided uri.
+ * @param method Method to use.
+ * @param uri URI to match.
+ * @param func Request handler.
+ *
+ * @note prefer to use the corresponding method method directly instead of `request()`(i.e `get(), post()`)
+ */
+function request<T extends MockRequestHandler>(
+  method: HttpMethod,
+  uri: string,
+  handler: T,
+): MockApiForHandler<T> {
+  return { method, uri, handler } as any;
+}
+
+export const mockapi = {
+  get,
+  post,
+  put,
+  patch,
+  delete: deleteReq,
+  options,
+  head,
+  request,
+};

package/src/scenarios.ts

@@ -0,0 +1,76 @@
+import {
+  KeyedMockApi,
+  KeyedMockApiDefinition,
+  MockApi,
+  MockApiDefinition,
+  PassByKeyScenario,
+  PassByServiceKeyScenario,
+  PassOnCodeScenario,
+  PassOnSuccessScenario,
+} from "./types.js";
+
+/**
+ * Specify that the scenario should be a `pass` if all the endpoints are called and the API response with 2xx exit code.
+ * @param apis Endpoint or List of endpoints for this scenario
+ */
+export function passOnSuccess(
+  apis: MockApi | readonly MockApi[] | MockApiDefinition | readonly MockApiDefinition[],
+): PassOnSuccessScenario {
+  return {
+    passCondition: "response-success",
+    apis: Array.isArray(apis) ? apis : [apis],
+  };
+}
+/**
+ * Specify that the scenario should be a `pass` if all the endpoints are called and the API response with the given exit code.
+ * @param code Status code all endpoint should return
+ * @param apis Endpoint or List of endpoints for this scenario
+ */
+export function passOnCode(
+  code: number,
+  apis: MockApi | readonly MockApi[] | MockApiDefinition,
+): PassOnCodeScenario {
+  return {
+    passCondition: "status-code",
+    code,
+    apis: Array.isArray(apis) ? apis : [apis],
+  };
+}
+
+export interface WithKeysScenarioExpect<K extends string> {
+  pass(api: KeyedMockApi<K>): PassByKeyScenario<K>;
+}
+/**
+ * Specify a list of keys that must be hit to this scenario to pass
+ * @param keys List of keys
+ * @param api Mock api that in the MockResponse can return a pass key.
+ */
+export function withKeys<const K extends string>(keys: K[]): WithKeysScenarioExpect<K> {
+  return {
+    pass: (api) => {
+      return {
+        passCondition: "by-key",
+        keys,
+        apis: [api],
+      };
+    },
+  };
+}
+
+export interface WithServiceKeysScenarioExpect<K extends string> {
+  pass(api: KeyedMockApiDefinition<K> | KeyedMockApiDefinition<K>[]): PassByServiceKeyScenario<K>;
+}
+
+export function withServiceKeys<const K extends string>(
+  keys: K[],
+): WithServiceKeysScenarioExpect<K> {
+  return {
+    pass: (api: KeyedMockApiDefinition<K> | KeyedMockApiDefinition<K>[]) => {
+      return {
+        passCondition: "by-key",
+        keys,
+        apis: Array.isArray(api) ? api : [api],
+      };
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,125 @@
+import type { Request } from "express";
+import { MockRequest } from "./mock-request.js";
+
+/**
+ * Extension of the express.js request which include a rawBody.
+ */
+export interface RequestExt extends Request {
+  rawBody?: string | Buffer;
+  files?:
+    | {
+        [fieldname: string]: Express.Multer.File[];
+      }
+    | Express.Multer.File[]
+    | undefined;
+}
+
+export type ScenarioPassCondition = "response-success" | "status-code";
+
+export interface PassOnSuccessScenario {
+  passCondition: "response-success";
+  apis: MockApi[] | MockApiDefinition[];
+}
+
+export interface PassOnCodeScenario {
+  passCondition: "status-code";
+  code: number;
+  apis: MockApi[] | MockApiDefinition[];
+}
+export interface PassByKeyScenario<K extends string = string> {
+  passCondition: "by-key";
+  keys: K[];
+  apis: KeyedMockApi<K>[];
+}
+export interface PassByServiceKeyScenario<K extends string = string> {
+  passCondition: "by-key";
+  keys: K[];
+  apis: KeyedMockApiDefinition<K>[];
+}
+
+export type ScenarioMockApi =
+  | PassOnSuccessScenario
+  | PassOnCodeScenario
+  | PassByKeyScenario
+  | PassByServiceKeyScenario;
+export type MockRequestHandler = SimpleMockRequestHandler | KeyedMockRequestHandler;
+export type SimpleMockRequestHandler = (req: MockRequest) => MockResponse | Promise<MockResponse>;
+export type KeyedMockRequestHandler<T extends string = string> = (
+  req: MockRequest,
+) => KeyedMockResponse<T> | Promise<KeyedMockResponse<T>>;
+export type KeyedServiceRequestHandler<T extends string = string> = (
+  req: ServiceRequest,
+) => KeyedMockResponse<T> | Promise<KeyedMockResponse<T>>;
+
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
+
+export type MockApiForHandler<Handler extends MockRequestHandler> =
+  Handler extends KeyedMockRequestHandler<infer K> ? KeyedMockApi<K> : MockApi;
+
+export interface MockApi {
+  method: HttpMethod;
+  uri: string;
+  handler: MockRequestHandler;
+  kind: "MockApi";
+}
+
+export interface MockApiDefinition {
+  uri: string;
+  method: HttpMethod;
+  request: ServiceRequest;
+  response: MockResponse;
+  handler?: MockRequestHandler;
+  kind: "MockApiDefinition";
+}
+
+export interface ServiceRequestFile {
+  fieldname: string;
+  originalname: string;
+  buffer: Buffer;
+  mimetype: string;
+}
+
+export interface ServiceRequest {
+  body?: any;
+  status?: number;
+  /**
+   * Query parameters to match to the request.
+   */
+  params?: Record<string, unknown>;
+  headers?: Record<string, unknown>;
+  files?: ServiceRequestFile[];
+}
+
+export const Fail = Symbol.for("Fail");
+export interface KeyedMockApi<K extends string> extends MockApi {
+  handler: KeyedMockRequestHandler<K>;
+}
+export interface KeyedMockApiDefinition<K extends string> extends MockApiDefinition {
+  handler: KeyedMockRequestHandler<K>;
+}
+
+export interface MockResponse {
+  status: number;
+  headers?: {
+    [key: string]: string | null;
+  };
+
+  body?: MockResponseBody;
+
+  /**
+   * Let the mock API know that this request was successful to counting coverage regardless of the status code.
+   * By default only 2xx status code will count toward success.
+   */
+  testSuccessful?: boolean;
+}
+
+export interface KeyedMockResponse<K extends string = string> extends MockResponse {
+  pass: K | typeof Fail;
+}
+
+export interface MockResponseBody {
+  contentType: string;
+  rawContent: string | Buffer | undefined;
+}
+
+export type CollectionFormat = "multi" | "csv" | "ssv" | "tsv" | "pipes";

package/src/validation-error.ts

@@ -0,0 +1,21 @@
+export class ValidationError extends Error {
+  public status = 400;
+
+  /**
+   * Error thrown there there is a validation issue.
+   * @param message Message describing the error.
+   * @param expected expected value.
+   * @param actual actual value.
+   */
+  constructor(
+    message: string,
+    public expected: unknown | undefined,
+    public actual: unknown | undefined,
+  ) {
+    super(message);
+  }
+
+  public toJSON(): string {
+    return JSON.stringify({ message: this.message, expected: this.expected, actual: this.actual });
+  }
+}