@tsed/schema 8.0.1 → 8.0.3

package/src/utils/getSpec.ts

@@ -0,0 +1,117 @@
+import {cleanObject, isArray, Type, uniqBy} from "@tsed/core";
+import {OpenSpec3} from "@tsed/openspec";
+
+import {SpecTypes} from "../domain/SpecTypes.js";
+import {JsonSchemaOptions} from "../interfaces/JsonSchemaOptions.js";
+import {execMapper} from "../registries/JsonSchemaMapperContainer.js";
+import {getJsonEntityStore} from "./getJsonEntityStore.js";
+import {mergeSpec} from "./mergeSpec.js";
+import {operationIdFormatter} from "./operationIdFormatter.js";
+
+export type JsonTokenOptions = ({token: Type<any>} & Partial<SpecSerializerOptions>)[];
+
+export interface SpecSerializerOptions extends JsonSchemaOptions {
+  /**
+   * Paths
+   */
+  paths?: Record<string, any>;
+  /**
+   * Channels
+   */
+  channels?: Record<string, any>;
+  /**
+   * Root path. This paths will be added to all generated paths Object.
+   */
+  rootPath?: string;
+  /**
+   * A function to generate the operationId.
+   */
+  operationIdFormatter?: (name: string, propertyKey: string, path: string) => string;
+  /**
+   * A pattern to generate the operationId.
+   */
+  operationIdPattern?: string;
+}
+
+/**
+ * @ignore
+ */
+const caches: Map<Type<any>, Map<string, any>> = new Map();
+
+/**
+ * @ignore
+ */
+function get(model: Type<any>, options: any, cb: any) {
+  if (!caches.has(model)) {
+    caches.set(model, new Map());
+  }
+
+  const cache = caches.get(model)!;
+  const key = JSON.stringify(options);
+
+  if (!cache.has(key)) {
+    cache.set(key, cb());
+  }
+
+  return cache.get(key);
+}
+
+function generate(model: Type<any>, options: SpecSerializerOptions) {
+  const store = getJsonEntityStore(model);
+  const {rootPath = "/"} = options;
+
+  options = {
+    ...options,
+    rootPath,
+    defaultTags: [
+      cleanObject({
+        name: store.schema.getName(),
+        description: store.schema.get("description")
+      })
+    ]
+  };
+
+  return execMapper("generate", [store], options);
+}
+
+/**
+ * Return the swagger or open spec for the given class.
+ * @param model
+ * @param options
+ */
+export function getSpec(model: Type<any> | JsonTokenOptions, options: SpecSerializerOptions = {}): Partial<OpenSpec3> {
+  options = {
+    specType: SpecTypes.OPENAPI,
+    ...options,
+    tags: [],
+    paths: {},
+    channels: {},
+    components: {},
+    operationIdFormatter: options.operationIdFormatter || operationIdFormatter(options.operationIdPattern),
+    root: false
+  };
+
+  if (isArray(model)) {
+    let finalSpec: any = {};
+
+    options = {
+      ...options,
+      append(spec: any) {
+        finalSpec = mergeSpec(finalSpec, spec);
+      }
+    };
+
+    model.forEach(({token, ...opts}) => {
+      const spec = getSpec(token, {
+        ...options,
+        ...opts
+      });
+
+      options.append(spec);
+    });
+
+    return finalSpec;
+  }
+
+  return get(model, options, () => generate(model, options));
+}

package/src/utils/getSpecType.spec.ts

@@ -0,0 +1,16 @@
+import {SpecTypes} from "../domain/SpecTypes.js";
+import {getSpecType, getSpecTypeFromSpec} from "./getSpecType.js";
+
+describe("getSpecType", () => {
+  it("should return spect type from version", () => {
+    expect(getSpecType("2.0")).toEqual(SpecTypes.SWAGGER);
+    expect(getSpecType("3.0.1")).toEqual(SpecTypes.OPENAPI);
+  });
+});
+
+describe("getSpecTypeFromSpec", () => {
+  it("should return spect type from version", () => {
+    expect(getSpecTypeFromSpec({swagger: "2.0"})).toEqual(SpecTypes.SWAGGER);
+    expect(getSpecTypeFromSpec({openapi: "3.0.1"})).toEqual(SpecTypes.OPENAPI);
+  });
+});

package/src/utils/getSpecType.ts

@@ -0,0 +1,19 @@
+import {OpenSpec2, OpenSpec3} from "@tsed/openspec";
+
+import {SpecTypes} from "../domain/SpecTypes.js";
+
+/**
+ * @ignore
+ * @param version
+ */
+export function getSpecType(version: string) {
+  return version.startsWith("3.") ? SpecTypes.OPENAPI : SpecTypes.SWAGGER;
+}
+
+/**
+ * @ignore
+ * @param spec
+ */
+export function getSpecTypeFromSpec(spec: Partial<OpenSpec2 | OpenSpec3>) {
+  return "openapi" in spec ? SpecTypes.OPENAPI : SpecTypes.SWAGGER;
+}

package/src/utils/isSuccessStatus.spec.ts

@@ -0,0 +1,22 @@
+import {isRedirectionStatus, isSuccessStatus} from "./isSuccessStatus.js";
+
+describe("isSuccessStatus", () => {
+  it("should be a valid success status", () => {
+    expect(isSuccessStatus(200)).toBe(true);
+    expect(isSuccessStatus("200")).toBe(true);
+  });
+
+  it("should not be a valid success status", () => {
+    expect(isSuccessStatus("300")).toBe(false);
+    expect(isSuccessStatus(101)).toBe(false);
+  });
+});
+
+describe("isRedirectionStatus", () => {
+  it("should return the expected value for", () => {
+    expect(isRedirectionStatus("300")).toBe(true);
+    expect(isRedirectionStatus(301)).toBe(true);
+    expect(isRedirectionStatus(200)).toBe(false);
+    expect(isRedirectionStatus(400)).toBe(false);
+  });
+});

package/src/utils/isSuccessStatus.ts

@@ -0,0 +1,2 @@
+export const isSuccessStatus = (code: string | number | undefined) => Number(code) && 200 <= Number(code) && Number(code) < 300;
+export const isRedirectionStatus = (code: string | number | undefined) => Number(code) && 300 <= Number(code) && Number(code) < 400;

package/src/utils/mapHeaders.spec.ts

@@ -0,0 +1,57 @@
+import {mapHeaders} from "./mapHeaders.js";
+
+describe("mapHeaders", () => {
+  it("should map headers", () => {
+    expect(
+      mapHeaders({
+        key: "value"
+      })
+    ).toEqual({
+      key: {
+        example: "value",
+        type: "string"
+      }
+    });
+
+    expect(
+      mapHeaders({
+        key: 1
+      })
+    ).toEqual({
+      key: {
+        example: 1,
+        type: "number"
+      }
+    });
+
+    expect(
+      mapHeaders({
+        key: {
+          description: "test",
+          value: 1
+        }
+      })
+    ).toEqual({
+      key: {
+        description: "test",
+        example: 1,
+        type: "number"
+      }
+    });
+
+    expect(
+      mapHeaders({
+        key: {
+          description: "test",
+          example: 1
+        }
+      } as any)
+    ).toEqual({
+      key: {
+        description: "test",
+        example: 1,
+        type: "number"
+      }
+    });
+  });
+});

package/src/utils/mapHeaders.ts

@@ -0,0 +1,33 @@
+import {cleanObject} from "@tsed/core";
+
+import {JsonHeader, JsonHeaders} from "../interfaces/JsonOpenSpec.js";
+
+/**
+ * Map input header to a standard open spec header
+ * @param headers
+ * @ignore
+ */
+export function mapHeaders(headers: JsonHeaders): {[key: string]: JsonHeader} {
+  return Object.keys(headers).reduce((newHeaders: {[key: string]: JsonHeader}, key: string) => {
+    const value: any = headers[key];
+
+    let type = typeof value;
+
+    let options: any = {
+      example: value
+    };
+
+    if (type === "object") {
+      options = value;
+      options.example = options.value === undefined ? options.example : options.value;
+      delete options.value;
+      type = typeof options.example;
+    }
+
+    options.type = options.type || type;
+
+    newHeaders[key] = cleanObject(options);
+
+    return newHeaders;
+  }, {});
+}

package/src/utils/mapOpenSpec.ts

@@ -0,0 +1,44 @@
+import {getValue, setValue} from "@tsed/core";
+import {OpenSpec2, OpenSpec3, OpenSpecVersions} from "@tsed/openspec";
+
+import {SpecTypes} from "../domain/SpecTypes.js";
+import {getSpecType} from "./getSpecType.js";
+import {mapOpenSpec2} from "./mapOpenSpec2.js";
+import {mapOpenSpec3} from "./mapOpenSpec3.js";
+import {mergeSpec} from "./mergeSpec.js";
+
+/**
+ * @ignore
+ * @param spec
+ * @param fileSpec
+ * @param version
+ * @param acceptMimes
+ * @param specVersion
+ */
+export function mapOpenSpec(spec: any, {fileSpec, acceptMimes, specVersion, version}: any): Partial<OpenSpec2 | OpenSpec3> {
+  specVersion = specVersion || getValue<OpenSpecVersions>(spec, "openapi", getValue(spec, "swagger", "2.0"));
+
+  const options = {
+    specVersion,
+    acceptMimes
+  };
+
+  switch (getSpecType(specVersion)) {
+    case SpecTypes.OPENAPI:
+      spec = mapOpenSpec3(spec, options);
+      fileSpec = fileSpec ? mapOpenSpec3(fileSpec, options) : fileSpec;
+      break;
+    default:
+    case SpecTypes.SWAGGER:
+      spec = mapOpenSpec2(spec, options);
+      fileSpec = fileSpec ? mapOpenSpec2(fileSpec, options) : fileSpec;
+      break;
+  }
+
+  spec = mergeSpec(spec, fileSpec);
+
+  setValue(spec, "info.title", getValue(spec, "info.title", "Api documentation"));
+  setValue(spec, "info.version", getValue(spec, "info.version", version));
+
+  return spec;
+}

package/src/utils/mapOpenSpec2.ts

@@ -0,0 +1,50 @@
+import {getValue, uniq} from "@tsed/core";
+import {OpenSpec2} from "@tsed/openspec";
+
+import {mapOpenSpecInfo} from "./mapOpenSpecInfo.js";
+
+/**
+ * @ignore
+ * @param spec
+ * @param version
+ * @param specVersion
+ * @param acceptMimes
+ */
+export function mapOpenSpec2(
+  spec: Partial<OpenSpec2>,
+  {version, specVersion, acceptMimes = ["application/json"]}: any
+): Partial<OpenSpec2> {
+  const {
+    paths,
+    security,
+    tags,
+    host,
+    basePath,
+    schemes,
+    consumes = [],
+    produces = ["application/json"],
+    definitions,
+    parameters,
+    responses,
+    securityDefinitions,
+    externalDocs
+  } = spec;
+
+  return {
+    swagger: specVersion,
+    consumes: uniq([...acceptMimes, ...consumes]),
+    produces: uniq<string>([...produces]),
+    info: mapOpenSpecInfo(getValue(spec, "info", {})),
+    paths,
+    host,
+    basePath,
+    schemes,
+    definitions,
+    parameters,
+    responses,
+    security,
+    securityDefinitions,
+    tags,
+    externalDocs
+  };
+}

package/src/utils/mapOpenSpec3.ts

@@ -0,0 +1,25 @@
+import {getValue} from "@tsed/core";
+import {OpenSpec3} from "@tsed/openspec";
+
+import {mapOpenSpecInfo} from "./mapOpenSpecInfo.js";
+
+/**
+ * @ignore
+ * @param spec
+ * @param version
+ * @param specVersion
+ */
+export function mapOpenSpec3(spec: any, {specVersion}: any): Partial<OpenSpec3> {
+  const {servers, paths, components, security, tags, externalDocs} = spec;
+
+  return {
+    openapi: specVersion,
+    info: mapOpenSpecInfo(getValue(spec, "info", {})),
+    servers,
+    paths,
+    components,
+    security,
+    tags,
+    externalDocs
+  };
+}

package/src/utils/mapOpenSpecInfo.ts

@@ -0,0 +1,19 @@
+import {cleanObject} from "@tsed/core";
+import {OpenSpecInfo} from "@tsed/openspec";
+
+/**
+ * @ignore
+ * @param info
+ */
+export function mapOpenSpecInfo(info: Partial<OpenSpecInfo>): OpenSpecInfo {
+  const {title, description, version, termsOfService, contact, license} = info;
+
+  return cleanObject({
+    version,
+    title,
+    description,
+    termsOfService,
+    contact,
+    license
+  });
+}

package/src/utils/mapOperationOptions.ts

@@ -0,0 +1,34 @@
+import {OperationVerbs} from "../constants/OperationVerbs.js";
+
+const ALLOWED_VERBS = new Set([
+  ...Object.keys(OperationVerbs)
+    .filter((v) => v !== OperationVerbs.CUSTOM)
+    .map((v) => v.toLowerCase())
+]);
+
+export function mapOperationOptions(args: any[]) {
+  let method: string | undefined = undefined;
+  let path: string | RegExp | undefined = undefined;
+
+  const handlers = args.filter((arg: any) => {
+    if (typeof arg === "string" && ALLOWED_VERBS.has(arg.toLowerCase())) {
+      method = arg.toLocaleUpperCase();
+
+      return false;
+    }
+
+    if (typeof arg === "string" || arg instanceof RegExp) {
+      path = arg || "/";
+
+      return false;
+    }
+
+    return !!arg;
+  });
+
+  return {
+    path,
+    method,
+    use: handlers
+  };
+}

package/src/utils/matchGroups.spec.ts

@@ -0,0 +1,85 @@
+import {matchGroups} from "./matchGroups.js";
+
+describe("matchGroups", () => {
+  it.each([
+    [
+      {
+        groups: ["!creation"],
+        givenGroups: [],
+        expected: false
+      },
+      {
+        groups: ["group.summary"],
+        givenGroups: [],
+        expected: true
+      },
+      {
+        groups: ["group.extended"],
+        givenGroups: [],
+        expected: true
+      },
+      {
+        groups: ["!creation"],
+        givenGroups: [],
+        expected: false
+      },
+      {
+        groups: ["group.summary"],
+        givenGroups: [],
+        expected: true
+      },
+      {
+        groups: ["group.extended"],
+        givenGroups: [],
+        expected: true
+      },
+      {
+        groups: ["!creation"],
+        givenGroups: ["group.summary"],
+        expected: false
+      },
+      {
+        groups: ["group.summary"],
+        givenGroups: ["group.summary"],
+        expected: false
+      },
+      {
+        groups: ["group.extended"],
+        givenGroups: ["group.summary"],
+        expected: true
+      },
+      {
+        groups: ["!creation"],
+        givenGroups: ["creation"],
+        expected: true
+      },
+      {
+        groups: ["group.summary"],
+        givenGroups: ["creation"],
+        expected: true
+      },
+      {
+        groups: ["group.extended"],
+        givenGroups: ["creation"],
+        expected: true
+      },
+      {
+        groups: ["!creation"],
+        givenGroups: ["group.*"],
+        expected: false
+      },
+      {
+        groups: ["group.summary"],
+        givenGroups: ["group.*"],
+        expected: false
+      },
+      {
+        groups: ["group.extended"],
+        givenGroups: ["group.*"],
+        expected: false
+      }
+    ]
+  ])("should compare groups $groups with given groups $givenGroups and should return $expected", ({groups, givenGroups, expected}) => {
+    expect(matchGroups(groups, givenGroups)).toEqual(expected);
+  });
+});

package/src/utils/matchGroups.ts

@@ -0,0 +1,64 @@
+import picomatch from "picomatch";
+
+function micromatch(list: string[], patterns: string[]) {
+  patterns = ([] as string[]).concat(patterns);
+  list = ([] as string[]).concat(list);
+
+  let omit = new Set();
+  let keep = new Set();
+  let items = new Set();
+  let negatives = 0;
+
+  let onResult = (state: any) => {
+    items.add(state.output);
+  };
+
+  for (let i = 0; i < patterns.length; i++) {
+    let isMatch: any = picomatch(String(patterns[i]), {onResult}, true);
+    let negated = isMatch.state.negated || isMatch.state.negatedExtglob;
+
+    if (negated) {
+      negatives++;
+    }
+
+    for (let item of list) {
+      let matched = isMatch(item, true);
+
+      let match = negated ? !matched.isMatch : matched.isMatch;
+      if (!match) continue;
+
+      if (negated) {
+        omit.add(matched.output);
+      } else {
+        omit.delete(matched.output);
+        keep.add(matched.output);
+      }
+    }
+  }
+
+  let result = negatives === patterns.length ? [...items] : [...keep];
+  return !!result.filter((item) => !omit.has(item)).length;
+}
+
+/**
+ * @ignore
+ */
+export function matchGroups(groups: string[], compareWith: string[] = []) {
+  const groupsExcludes = groups.filter((group) => group.startsWith("!")).map((group) => group.replace("!", ""));
+  const groupsIncludes = groups.filter((group) => !group.startsWith("!"));
+
+  if (groupsExcludes.length) {
+    if (compareWith.length && micromatch(groupsExcludes, compareWith)) {
+      return true;
+    }
+  }
+
+  if (groupsIncludes.length) {
+    return !micromatch(
+      groups.filter((group) => !group.startsWith("!")),
+      compareWith
+    );
+  }
+
+  return false;
+}