@tsed/schema 8.0.0 → 8.0.2

package/src/decorators/operations/path.ts

@@ -0,0 +1,27 @@
+import {DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Set class path to expose all endpoints
+ *
+ * ::: warning
+ * Don't use this decorator to change the path if you develop your application with Ts.ED.
+ * :::
+ *
+ * @param path
+ * @decorator
+ * @swagger
+ * @schema
+ * @classDecorator
+ * @operation
+ */
+export function Path(path: string) {
+  return JsonEntityFn((store, args) => {
+    if (store.decoratorType !== DecoratorTypes.CLASS) {
+      throw new UnsupportedDecoratorType(Path, args);
+    }
+
+    store.path = path;
+  });
+}

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

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

package/src/decorators/operations/produces.ts

@@ -0,0 +1,44 @@
+import {decorateMethodsOf, DecoratorTypes, UnsupportedDecoratorType} from "@tsed/core";
+
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+
+/**
+ * Add produces metadata on the decorated element.
+ *
+ * ## Examples
+ * ### On method
+ *
+ * ```typescript
+ * class Model {
+ *    @Produces("text/html")
+ *    id: string;
+ * }
+ * ```
+ *
+ * ::: warning
+ * For openspec v3 prefer `@Returns().ContentType()` usage (see @@Returns@@).
+ * :::
+ *
+ * @param produces
+ * @decorator
+ * @swagger
+ * @methodDecorator
+ * @classDecorator
+ * @operation
+ * @response
+ */
+export function Produces(...produces: string[]) {
+  return JsonEntityFn((store, args) => {
+    switch (store.decoratorType) {
+      case DecoratorTypes.METHOD:
+        store.operation!.produces(produces);
+        break;
+      case DecoratorTypes.CLASS:
+        decorateMethodsOf(args[0], Produces(...produces));
+        break;
+
+      default:
+        throw new UnsupportedDecoratorType(Produces, args);
+    }
+  });
+}

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

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

package/src/decorators/operations/publish.ts

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

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

@@ -0,0 +1,146 @@
+import {getSpec, OperationPath, SpecTypes} from "../../index.js";
+import {Redirect} from "./redirect.js";
+
+describe("Redirect", () => {
+  it("should set header with path only", () => {
+    class MyController {
+      @Redirect("/path/to")
+      @OperationPath("GET", "/")
+      test() {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerTest",
+            parameters: [],
+            responses: {
+              "302": {
+                content: {
+                  "*/*": {
+                    schema: {
+                      type: "object"
+                    }
+                  }
+                },
+                description: "Found",
+                headers: {
+                  Location: {
+                    example: "/path/to",
+                    schema: {
+                      type: "string"
+                    }
+                  }
+                }
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+  it("should set header with path and status", () => {
+    class MyController {
+      @Redirect(301, "/path/to")
+      @OperationPath("GET", "/")
+      test() {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerTest",
+            parameters: [],
+            responses: {
+              "301": {
+                content: {
+                  "*/*": {
+                    schema: {
+                      type: "object"
+                    }
+                  }
+                },
+                description: "Moved Permanently",
+                headers: {
+                  Location: {
+                    example: "/path/to",
+                    schema: {
+                      type: "string"
+                    }
+                  }
+                }
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+  it("should set header with path and status and meta", () => {
+    class MyController {
+      @Redirect(301, "/path/to", {
+        description: "Test description"
+      })
+      @OperationPath("GET", "/")
+      test() {}
+    }
+
+    const spec = getSpec(MyController, {specType: SpecTypes.OPENAPI});
+
+    expect(spec).toEqual({
+      paths: {
+        "/": {
+          get: {
+            operationId: "myControllerTest",
+            parameters: [],
+            responses: {
+              "301": {
+                content: {
+                  "*/*": {
+                    schema: {
+                      type: "object"
+                    }
+                  }
+                },
+                description: "Moved Permanently",
+                headers: {
+                  Location: {
+                    description: "Test description",
+                    example: "/path/to",
+                    schema: {
+                      type: "string"
+                    }
+                  }
+                }
+              }
+            },
+            tags: ["MyController"]
+          }
+        }
+      },
+      tags: [
+        {
+          name: "MyController"
+        }
+      ]
+    });
+  });
+});

package/src/decorators/operations/redirect.ts

@@ -0,0 +1,82 @@
+import {isNumber, isString, useDecorators} from "@tsed/core";
+
+import {JsonHeader} from "../../interfaces/JsonOpenSpec.js";
+import {JsonEntityFn} from "../common/jsonEntityFn.js";
+import {Returns} from "./returns.js";
+
+/**
+ * Redirects to the URL derived from the specified path, with specified status, a positive integer that corresponds to an HTTP status code . If not specified, status defaults to “302 “Found”.
+ *
+ * ```typescript
+ *  @Redirect('/foo/bar')
+ *  @Redirect(301, 'http://example.com').Type(Model)
+ *  private myMethod() {}
+ * ```
+ * Redirects can be a fully-qualified URL for redirecting to a different site:
+ *
+ * ```typescript
+ *  @Redirect('http://google.com');
+ *  private myMethod() {}
+ * ```
+ *
+ * Redirects can be relative to the root of the host name. For example, if the application is on http://example.com/admin/post/new, the following would redirect to the URL http://example.com/admin:
+ *
+ * ```typescript
+ *  @Redirect('/admin');
+ * ```
+ * Redirects can be relative to the current URL. For example, from http://example.com/blog/admin/ (notice the trailing slash), the following would redirect to the URL http://example.com/blog/admin/post/new.
+ *
+ * ```typescript
+ *  @Redirect('post/new');
+ * ```
+ *
+ * Redirecting to post/new from http://example.com/blog/admin (no trailing slash), will redirect to http://example.com/blog/post/new.
+ *
+ * If you found the above behavior confusing, think of path segments as directories (with trailing slashes) and files, it will start to make sense.
+ *
+ * Path-relative redirects are also possible. If you were on http://example.com/admin/post/new, the following would redirect to http//example.com/admin/post:
+ *
+ * ```typescript
+ *  @Redirect('..');
+ * ``
+ *
+ * A back redirection redirects the request back to the referer, defaulting to / when the referer is missing.
+ *
+ * ```typescript
+ *  @Redirect('back');
+ * ```
+ *
+ * @param url
+ * @param meta
+ * @decorator
+ * @operation
+ * @response
+ * @headers
+ */
+export function Redirect(url: string, meta?: JsonHeader): Function;
+export function Redirect(status: number, url: string, meta?: JsonHeader): Function;
+export function Redirect(...args: any[]): Function {
+  const {status, url, meta} = args.reduce(
+    (options: any, value: any) => {
+      if (isNumber(value)) {
+        options.status = value;
+        return options;
+      }
+
+      if (isString(value)) {
+        options.url = value;
+        return options;
+      }
+
+      options.meta = value;
+      return options;
+    },
+    {status: 302, url: "", meta: {}}
+  );
+  return useDecorators(
+    Returns(status).Location(url, meta),
+    JsonEntityFn((entity) => {
+      entity.operation?.setRedirection(status);
+    })
+  );
+}