@tsed/schema 8.0.0 → 8.0.2

package/src/decorators/operations/subscribe.spec.ts

@@ -0,0 +1,32 @@
+import "../../index.js";
+
+import {OperationVerbs} from "../../constants/OperationVerbs.js";
+import {JsonEntityStore} from "../../domain/JsonEntityStore.js";
+import {Publish} from "./publish.js";
+import {Subscribe} from "./subscribe.js";
+
+describe("Subscribe", () => {
+  it("should register operation with Subscribe verb", () => {
+    // WHEN
+    class Test {
+      @Publish("event")
+      @Subscribe("event")
+      test() {}
+    }
+
+    const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+    // THEN
+    expect([...endpoint.operation!.operationPaths.values()]).toEqual([
+      {
+        method: OperationVerbs.SUBSCRIBE,
+        path: "event"
+      },
+      {
+        method: OperationVerbs.PUBLISH,
+        path: "event"
+      }
+    ]);
+    expect(endpoint.propertyKey).toBe("test");
+  });
+});

package/src/decorators/operations/subscribe.ts

@@ -0,0 +1,6 @@
+import {OperationVerbs} from "../../constants/OperationVerbs.js";
+import {Operation} from "./operation.js";
+
+export function Subscribe(event: string) {
+  return Operation(OperationVerbs.SUBSCRIBE, event);
+}

package/src/decorators/operations/summary.spec.ts

@@ -0,0 +1,45 @@
+import {getSpec, OperationPath} from "../../index.js";
+import {Summary} from "./summary.js";
+
+describe("Summary", () => {
+  it("should store metadata", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @Summary("summary")
+      get() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "MyController"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            summary: "summary",
+            tags: ["MyController"]
+          }
+        }
+      }
+    });
+  });
+  it("should throw error for unsupported usage", () => {
+    let actualError: any;
+    try {
+      Summary("summary")(class Test {});
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("Summary cannot be used as class decorator on Test");
+  });
+});

package/src/decorators/operations/summary.ts

@@ -0,0 +1,32 @@
+import {DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Add summary metadata on the decorated element.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * class Model {
+ *    @Summary("summary")
+ *    id: string;
+ * }
+ * ```
+ *
+ * @param summary
+ * @decorator
+ * @swagger
+ * @schema
+ * @operation
+ */
+export function Summary(summary: string) {
+  return JsonEntityFn((store, args) => {
+    if (store.decoratorType !== DecoratorTypes.METHOD) {
+      throw new UnsupportedDecoratorType(Summary, args);
+    }
+
+    store.operation!.summary(summary);
+  });
+}

package/src/decorators/operations/tags.spec.ts

@@ -0,0 +1,113 @@
+import {getSpec, OperationPath} from "../../index.js";
+import {Tags} from "./tags.js";
+
+describe("Tags", () => {
+  it("should store metadata (method)", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @Tags("api")
+      get() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [{name: "api"}],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["api"]
+          }
+        }
+      }
+    });
+  });
+  it("should store metadata (method - map)", () => {
+    class MyController {
+      @OperationPath("POST", "/")
+      @Tags({name: "api", description: "description"})
+      get() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [
+        {
+          name: "api",
+          description: "description"
+        }
+      ],
+      paths: {
+        "/": {
+          post: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["api"]
+          }
+        }
+      }
+    });
+  });
+  it("should store metadata (class)", () => {
+    @Tags("api")
+    class MyController {
+      @OperationPath("GET", "/")
+      get() {}
+
+      @OperationPath("POST", "/")
+      @Tags("allow")
+      post() {}
+    }
+
+    expect(getSpec(MyController)).toEqual({
+      tags: [{name: "api"}, {name: "allow"}],
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerGet",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["api"]
+          },
+          post: {
+            operationId: "myControllerPost",
+            parameters: [],
+            responses: {
+              "200": {
+                description: "Success"
+              }
+            },
+            tags: ["allow", "api"]
+          }
+        }
+      }
+    });
+  });
+  it("should throw error for unsupported usage", () => {
+    class Test {
+      test() {}
+    }
+
+    let actualError: any;
+    try {
+      Tags("tags")(Test.prototype, "test", 0);
+    } catch (er) {
+      actualError = er;
+    }
+
+    expect(actualError.message).toEqual("Tags cannot be used as parameter decorator on Test.test.[0]");
+  });
+});

package/src/decorators/operations/tags.ts

@@ -0,0 +1,53 @@
+import {decorateMethodsOf, DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+import {OpenSpecTag} from "@tsed/openspec";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+function mapTags(tags: (string | OpenSpecTag)[]) {
+  return tags.map((tag) => {
+    if (typeof tag === "string") {
+      return {
+        name: tag
+      };
+    }
+
+    return tag;
+  });
+}
+
+/**
+ * Add tags metadata on the decorated element.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * @Controller("/")
+ * class MyController {
+ *  @Tags("api")
+ *  get() {}
+ * }
+ * ```
+ *
+ * @param tags
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @operation
+ */
+export function Tags(...tags: (string | OpenSpecTag)[]) {
+  return JsonEntityFn((store, args) => {
+    switch (store.decoratorType) {
+      case DecoratorTypes.METHOD:
+        store.operation!.addTags(mapTags(tags));
+        break;
+      case DecoratorTypes.CLASS:
+        decorateMethodsOf(args[0], Tags(...tags));
+        break;
+
+      default:
+        throw new UnsupportedDecoratorType(Tags, args);
+    }
+  });
+}

package/src/decorators/operations/view.spec.ts

@@ -0,0 +1,16 @@
+import {JsonMethodStore, View} from "../../index.js";
+
+describe("@View", () => {
+  it("should set metadata", () => {
+    class Test {
+      @View("page", {test: "test"})
+      test() {}
+    }
+
+    const endpoint = JsonMethodStore.get(Test, "test");
+    expect(endpoint.view).toEqual({
+      path: "page",
+      options: {test: "test"}
+    });
+  });
+});

package/src/decorators/operations/view.ts

@@ -0,0 +1,27 @@
+import {StoreSet} from "@tsed/core";
+
+/**
+ * Use a view and sends the rendered HTML string to the client. Optional parameter:
+ *
+ * * viewOptions, an object whose properties define local variables for the view.
+ *
+ * The view argument is a string that is the file path of the view file to render.
+ * This can be an absolute path, or a path relative to the views setting.
+ * If the path does not contain a file extension, then the view engine setting determines the file extension.
+ * If the path does contain a file extension, then Express will load the module for the specified template engine (via require())
+ * and render it using the loaded module’s __express function.
+ *
+ * For more information, see [Using template engines with Express](http://expressjs.com/guide/using-template-engines.html).
+ *
+ * > NOTE: The view argument performs file system operations like reading a file from disk and evaluating Node.js modules,
+ * and as so for security reasons should not contain input from the end-user.
+ *
+ * @param path Relative path to the view file.
+ * @param options Additional options
+ * @decorator
+ * @operation
+ * @response
+ */
+export function View(path: string, options?: Object): MethodDecorator {
+  return StoreSet("view", {path, options}) as any;
+}

package/src/domain/DecoratorContext.ts

@@ -0,0 +1,116 @@
+import {DecoratorParameters, DecoratorTypes} from "@tsed/core";
+import {pascalCase} from "change-case";
+
+import {JsonEntityStore} from "./JsonEntityStore.js";
+
+/**
+ * @ignore
+ */
+export interface DecoratorActionHandler {
+  (ctx: Map<string, any>): void;
+}
+
+/**
+ * @ignore
+ */
+export abstract class DecoratorContext<T = any> extends Map<string, any> {
+  readonly methods: string[];
+  protected decoratorType: DecoratorTypes;
+  protected entity: JsonEntityStore;
+  protected actions: DecoratorActionHandler[] = [];
+
+  constructor(opts: any = {}) {
+    super();
+
+    Object.entries(opts).forEach(([key, value]) => {
+      this.set(key, value);
+    });
+  }
+
+  addAction(cb: DecoratorActionHandler) {
+    this.actions.push(cb);
+    return this;
+  }
+
+  build(): T {
+    const decorator: any = (...args: DecoratorParameters) => this.bind(args, decorator);
+
+    const wrap = (cb: any) => {
+      return (...args: any[]) => {
+        cb(...args);
+        return decorator;
+      };
+    };
+
+    const wrapKey = (key: string) => {
+      return wrap((...values: any[]) => {
+        key in this ? (this as any)[key](...values) : this.set(key, values[0]);
+      });
+    };
+
+    this.methods.forEach((name) => {
+      decorator[pascalCase(name)] = wrapKey(name);
+    });
+
+    return decorator as unknown as T;
+  }
+
+  toObject(): any {
+    return [...this.entries()].reduce((obj, [key, value]) => {
+      return {
+        ...obj,
+        [key]: value
+      };
+    }, {});
+  }
+
+  getMergedKey(key: string, defaultValue: any) {
+    let value = this.get(key) || defaultValue;
+
+    if (!value) {
+      return;
+    }
+
+    if (this.decoratorType === DecoratorTypes.CLASS) {
+      value = {
+        ...value,
+        ...(defaultValue || {})
+      };
+    }
+
+    return {
+      ...(defaultValue || {}),
+      ...value
+    };
+  }
+
+  protected bind(args: DecoratorParameters, decorator: any) {
+    this.entity = JsonEntityStore.from(...args);
+
+    this.beforeInit();
+    this.onInit(args, decorator);
+    this.afterInit();
+  }
+
+  protected onInit(args: DecoratorParameters, decorator: any): void {
+    this.forEach((value, key) => {
+      this.onMapKey(key, value);
+    });
+  }
+
+  protected onMapKey(key: string, value: any): void {
+    this.entity.set(key, value);
+  }
+
+  protected runActions() {
+    this.actions.forEach((action: any) => {
+      action(this);
+    });
+
+    return this;
+  }
+
+  protected beforeInit() {}
+
+  protected afterInit() {}
+}

package/src/domain/JsonAliasMap.ts

@@ -0,0 +1,19 @@
+/**
+ * @ignore
+ */
+export type AliasType = string | number | symbol;
+/**
+ * @ignore
+ */
+export type AliasMap = Map<AliasType, AliasType>;
+/**
+ * @ignore
+ */
+export function mapAliasedProperties(value: any, alias: AliasMap) {
+  return Object.entries(value).reduce<any>((properties, [key, value]) => {
+    key = (alias.get(key) as string) || key;
+    properties[key] = value;
+
+    return properties;
+  }, {});
+}

package/src/domain/JsonClassStore.ts

@@ -0,0 +1,35 @@
+import {DecoratorTypes} from "@tsed/core";
+
+import {JsonEntityComponent} from "../decorators/config/jsonEntityComponent.js";
+import {JsonEntityStore, JsonEntityStoreOptions} from "./JsonEntityStore.js";
+import type {JsonMethodStore} from "./JsonMethodStore.js";
+import type {JsonPropertyStore} from "./JsonPropertyStore.js";
+import {JsonSchema} from "./JsonSchema.js";
+
+@JsonEntityComponent(DecoratorTypes.CLASS)
+export class JsonClassStore extends JsonEntityStore {
+  /**
+   * List of children JsonEntityStore (properties or methods or params)
+   */
+  readonly children: Map<string | number, JsonMethodStore | JsonPropertyStore> = new Map();
+
+  get path() {
+    return this.store.get("path", "/");
+  }
+
+  set path(path: string) {
+    this.store.set("path", path);
+  }
+
+  protected build() {
+    if (!this._type) {
+      this.buildType(this.target);
+    }
+
+    this._type = this._type || Object;
+
+    this._schema = JsonSchema.from({
+      type: this.type
+    });
+  }
+}

package/src/domain/JsonDiscriminator.spec.ts

@@ -0,0 +1,65 @@
+import {DiscriminatorValue} from "../decorators/class/discriminatorValue.js";
+import {DiscriminatorKey} from "../decorators/common/discriminatorKey.js";
+import {Property} from "../decorators/common/property.js";
+import {Required} from "../decorators/common/required.js";
+import {JsonEntityStore} from "./JsonEntityStore.js";
+
+class Event {
+  @DiscriminatorKey() // declare this property a discriminator key
+  type: string;
+
+  @Property()
+  value: string;
+}
+
+@DiscriminatorValue("page_view") // or @DiscriminatorValue() value can be inferred by the class name
+class PageView extends Event {
+  @Required()
+  url: string;
+}
+
+@DiscriminatorValue("action", "click_action")
+class Action extends Event {
+  @Required()
+  event: string;
+}
+
+@DiscriminatorValue()
+class CustomAction extends Event {
+  @Required()
+  event: string;
+
+  @Property()
+  meta: string;
+}
+
+describe("Discriminator", () => {
+  describe("getType()", () => {
+    it("should return the expected type", () => {
+      const discriminator = JsonEntityStore.from(Event).schema.discriminator();
+
+      expect(discriminator.getType("custom_action")).toEqual(CustomAction);
+      expect(discriminator.getType("")).toEqual(Event);
+    });
+  });
+
+  describe("getValues()", () => {
+    it("should return the expected values", () => {
+      const discriminator = JsonEntityStore.from(Event).schema.discriminator();
+
+      expect(discriminator.getValues(CustomAction)).toEqual(["custom_action"]);
+      expect(discriminator.getValues(Event)).toEqual(undefined);
+      expect(discriminator.getValues(Action)).toEqual(["action", "click_action"]);
+    });
+  });
+
+  describe("getDefaultValue()", () => {
+    it("should return the expected value", () => {
+      const discriminator = JsonEntityStore.from(Event).schema.discriminator();
+
+      expect(discriminator.getDefaultValue(CustomAction)).toEqual("custom_action");
+      expect(discriminator.getDefaultValue(Event)).toEqual(undefined);
+      expect(discriminator.getDefaultValue(Action)).toEqual("action");
+    });
+  });
+});

package/src/domain/JsonDiscriminator.ts

@@ -0,0 +1,52 @@
+import {cleanObject, Type} from "@tsed/core";
+
+export class Discriminator {
+  propertyName: string;
+  base: Type<any>;
+  values: Map<string, Type> = new Map();
+  types: Map<Type, string[]> = new Map();
+
+  constructor({
+    base,
+    propertyName,
+    types,
+    values
+  }: Partial<{base: Type<any>; propertyName: string; values: Map<string, Type<any>>; types: Map<Type, string[]>}> = {}) {
+    Object.assign(
+      this,
+      cleanObject({
+        base,
+        propertyName,
+        types: types ? new Map(types) : undefined,
+        values: values ? new Map(values) : undefined
+      })
+    );
+  }
+
+  add(type: Type<string>, values: string[]) {
+    values.forEach((value) => {
+      this.values.set(value, type);
+    });
+
+    this.types.set(type, values);
+
+    return this;
+  }
+
+  getType(discriminatorValue: string): Type<any> {
+    return this.values.get(discriminatorValue) || this.base;
+  }
+
+  getValues(type: Type) {
+    return this.types.get(type);
+  }
+
+  getDefaultValue(type: Type<any>) {
+    const values = this.types.get(type);
+    return values ? values[0] : undefined;
+  }
+
+  children() {
+    return [...new Set([...this.types.keys()])];
+  }
+}