@nestia/core 2.5.8 → 2.5.9

package/README.md

@@ -6,17 +6,19 @@
 [![Downloads](https://img.shields.io/npm/dm/@nestia/core.svg)](https://www.npmjs.com/package/@nestia/core)
 [![Build Status](https://github.com/samchon/nestia/workflows/build/badge.svg)](https://github.com/samchon/nestia/actions?query=workflow%3Abuild)
 [![Guide Documents](https://img.shields.io/badge/guide-documents-forestgreen)](https://nestia.io/docs/)
+[![Discord Badge](https://img.shields.io/badge/discord-NestJS/Nestia-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.com/channels/520622812742811698/1197293125434093701)](https://discord.com/channels/520622812742811698/1181877086797967420)
 
 Nestia is a set of helper libraries for NestJS, supporting below features:
 
-  - `@nestia/core`: super-fast decorators
+  - `@nestia/core`: Super-fast decorators
   - `@nestia/sdk`:
     - Swagger generator evolved than ever
     - SDK library generator for clients
     - Mockup Simulator for client applications
     - Automatic E2E test functions generator
-  - `@nestia/migrate`: migration from Swagger to NestJS
-  - `nestia`: just CLI (command line interface) tool
+  - `@nestia/migrate`: Migration from Swagger to NestJS
+  - `@nestia/editor`: Online TypeScript Swagger Editor
+  - `nestia`: Just CLI (command line interface) tool
 
 > **Note**
 > 
@@ -25,8 +27,8 @@ Nestia is a set of helper libraries for NestJS, supporting below features:
 >   - Runtime validator is **20,000x faster** than `class-validator`
 >   - JSON serialization is **200x faster** than `class-transformer`
 > - Software Development Kit
->   - SDK is a collection of `fetch` functions with type definitions like [tRPC](https://trpc.io/)
->   - Mockup simulator means embedded backend simulator in SDK
+>   - Collection of typed `fetch` functions with DTO structures like [tRPC](https://trpc.io/)
+>   - Mockup simulator means embedded backend simulator in the SDK
 >     - similar with [msw](https://mswjs.io/), but fully automated
 
 ![nestia-sdk-demo](https://user-images.githubusercontent.com/13158709/215004990-368c589d-7101-404e-b81b-fbc936382f05.gif)
@@ -59,7 +61,7 @@ Check out the document in the [website](https://nestia.io/docs/):
     - [TypedRoute](https://nestia.io/docs/core/TypedRoute/)
     - [TypedBody](https://nestia.io/docs/core/TypedBody/)
     - [TypedParam](https://nestia.io/docs/core/TypedParam/)
-    - [TypedQuery](https://nestia.io/docs/core/TypedRoute/)
+    - [TypedQuery](https://nestia.io/docs/core/TypedQuery/)
     - [TypedHeaders](https://nestia.io/docs/core/TypedHeaders/)
     - [TypedException](https://nestia.io/docs/core/TypedException/)
   - Generators
@@ -68,6 +70,7 @@ Check out the document in the [website](https://nestia.io/docs/):
     - [E2E Functions](https://nestia.io/docs/sdk/e2e/)
     - [Mockup Simulator](https://nestia.io/docs/sdk/simulator/)
   - [Swagger to NestJS](https://nestia.io/docs/migrate/)
+  - [TypeScript Swagger Editor](https://nestia.io/docs/editor/)
 
 ### 🔗 Appendix
   - [⇲ Benchmark Result](https://github.com/samchon/nestia/tree/master/benchmark/results/11th%20Gen%20Intel(R)%20Core(TM)%20i5-1135G7%20%40%202.40GHz)

package/lib/decorators/SwaggerCustomizer.d.ts

@@ -0,0 +1,64 @@
+import { ISwagger } from "../structures/ISwagger";
+import { ISwaggerRoute } from "../structures/ISwaggerRoute";
+/**
+ * Swagger customization decorator.
+ *
+ * `SwaggerCustomizer` is a method decorator function which can used for
+ * customizing the swagger data with `npx nestia swagger` command. Furthermore,
+ * it is possible to add plugin properties starting with `x-` characters.
+ *
+ * In other words, this decorator function does not affect to the runtime,
+ * but only for the swagger data customization.
+ *
+ * @param closure Callback function which can customize the swagger data
+ * @returns Method decorator
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare function SwaggerCustomizer(closure: (props: SwaggerCustomizer.IProps) => unknown): MethodDecorator;
+export declare namespace SwaggerCustomizer {
+    /**
+     * Properties for the `SwaggerCustomizer` decorator.
+     *
+     * `SwaggerCustomizer.IProps` is a type for the `closure` parameter of the
+     * `SwaggerCustomizer` decorator. It's a callback function which can customize
+     * the swagger data.
+     */
+    interface IProps {
+        /**
+         * Swagger data.
+         */
+        swagger: ISwagger;
+        /**
+         * Method of the route.
+         */
+        method: string;
+        /**
+         * Path of the route.
+         */
+        path: string;
+        /**
+         * Route data.
+         */
+        route: ISwaggerRoute;
+        /**
+         * Get neighbor route data.
+         *
+         * @param accessor Accessor for getting neighbor route data
+         * @returns Neighbor route data
+         */
+        get(accessor: IAccessor): ISwaggerRoute | undefined;
+    }
+    /**
+     * Accessor for getting neighbor route data.
+     */
+    interface IAccessor {
+        /**
+         * Path of the neighbor route.
+         */
+        path: string;
+        /**
+         * Method of the neighbor route.
+         */
+        method: string;
+    }
+}

package/lib/decorators/SwaggerCustomizer.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerCustomizer = void 0;
+/**
+ * Swagger customization decorator.
+ *
+ * `SwaggerCustomizer` is a method decorator function which can used for
+ * customizing the swagger data with `npx nestia swagger` command. Furthermore,
+ * it is possible to add plugin properties starting with `x-` characters.
+ *
+ * In other words, this decorator function does not affect to the runtime,
+ * but only for the swagger data customization.
+ *
+ * @param closure Callback function which can customize the swagger data
+ * @returns Method decorator
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+function SwaggerCustomizer(closure) {
+    return function SwaggerCustomizer(target, propertyKey, descriptor) {
+        Reflect.defineMetadata("nestia/SwaggerCustomizer", closure, target, propertyKey);
+        return descriptor;
+    };
+}
+exports.SwaggerCustomizer = SwaggerCustomizer;
+//# sourceMappingURL=SwaggerCustomizer.js.map

package/lib/decorators/SwaggerCustomizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwaggerCustomizer.js","sourceRoot":"","sources":["../../src/decorators/SwaggerCustomizer.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;GAaG;AACH,SAAgB,iBAAiB,CAC/B,OAAqD;IAErD,OAAO,SAAS,iBAAiB,CAC/B,MAAc,EACd,WAA4B,EAC5B,UAAwC;QAExC,OAAO,CAAC,cAAc,CACpB,0BAA0B,EAC1B,OAAO,EACP,MAAM,EACN,WAAW,CACZ,CAAC;QACF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAhBD,8CAgBC"}

package/lib/module.d.ts

@@ -5,6 +5,7 @@ export * from "./decorators/EncryptedModule";
 export * from "./decorators/EncryptedRoute";
 export * from "./utils/ExceptionManager";
 export * from "./decorators/PlainBody";
+export * from "./decorators/SwaggerCustomizer";
 export * from "./decorators/TypedBody";
 export * from "./decorators/TypedException";
 export * from "./decorators/TypedHeaders";

package/lib/module.js

@@ -21,6 +21,7 @@ __exportStar(require("./decorators/EncryptedModule"), exports);
 __exportStar(require("./decorators/EncryptedRoute"), exports);
 __exportStar(require("./utils/ExceptionManager"), exports);
 __exportStar(require("./decorators/PlainBody"), exports);
+__exportStar(require("./decorators/SwaggerCustomizer"), exports);
 __exportStar(require("./decorators/TypedBody"), exports);
 __exportStar(require("./decorators/TypedException"), exports);
 __exportStar(require("./decorators/TypedHeaders"), exports);

package/lib/module.js.map

@@ -1 +1 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6DAA2C;AAC3C,6DAA2C;AAC3C,mEAAiD;AACjD,+DAA6C;AAC7C,8DAA4C;AAC5C,2DAAyC;AACzC,yDAAuC;AACvC,yDAAuC;AACvC,8DAA4C;AAC5C,4DAA0C;AAC1C,6DAA2C;AAC3C,0DAAwC;AACxC,0DAAwC;AACxC,0DAAwC;AACxC,oEAAkD"}
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6DAA2C;AAC3C,6DAA2C;AAC3C,mEAAiD;AACjD,+DAA6C;AAC7C,8DAA4C;AAC5C,2DAAyC;AACzC,yDAAuC;AACvC,iEAA+C;AAC/C,yDAAuC;AACvC,8DAA4C;AAC5C,4DAA0C;AAC1C,6DAA2C;AAC3C,0DAAwC;AACxC,0DAAwC;AACxC,0DAAwC;AACxC,oEAAkD"}

package/lib/structures/ISwagger.d.ts

@@ -0,0 +1,72 @@
+import { ISwaggerComponents } from "./ISwaggerComponents";
+import { ISwaggerInfo } from "./ISwaggerInfo";
+import { ISwaggerRoute } from "./ISwaggerRoute";
+/**
+ * Swagger Document.
+ *
+ * `ISwagger` is a data structure representing content of `swagger.json` file
+ * generated by Nestia. Note that, this is not an universal structure, but a dedicated
+ * structure only for Nestia.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ISwagger {
+    /**
+     * The version of the OpenAPI document.
+     *
+     * Nestia always generate OpenAPI 3.0.x document.
+     */
+    openapi: `3.0.${number}`;
+    /**
+     * List of servers that provide the API.
+     */
+    servers: ISwagger.IServer[];
+    /**
+     * Information about the API.
+     */
+    info: ISwaggerInfo;
+    /**
+     * The available paths and operations for the API.
+     *
+     * The 1st key is the path, and the 2nd key is the HTTP method.
+     */
+    paths: Record<string, Record<string, ISwaggerRoute>>;
+    /**
+     * An object to hold reusable data structures.
+     *
+     * It stores both DTO schemas and security schemes.
+     *
+     * For reference, `nestia` defines every object and alias types as reusable DTO
+     * schemas. The alias type means that defined by `type` keyword in TypeScript.
+     */
+    components: ISwaggerComponents;
+}
+export declare namespace ISwagger {
+    /**
+     * Remote server definition.
+     */
+    interface IServer {
+        /**
+         * A URL to the target host.
+         *
+         * @format uri
+         */
+        url: string;
+        /**
+         * An optional string describing the target server.
+         */
+        description?: string;
+    }
+    interface IExternalDocs {
+        /**
+         * The URL for target documentation.
+         *
+         * @format uri
+         */
+        url: string;
+        /**
+         * A short description of the target documentation.
+         */
+        description?: string;
+    }
+}

package/lib/structures/ISwagger.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ISwagger.js.map

package/lib/structures/ISwagger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISwagger.js","sourceRoot":"","sources":["../../src/structures/ISwagger.ts"],"names":[],"mappings":""}

package/lib/structures/ISwaggerComponents.d.ts

@@ -0,0 +1,26 @@
+import { IJsonComponents } from "typia";
+import { ISwaggerSecurityScheme } from "./ISwaggerSecurityScheme";
+/**
+ * Reusable components in Swagger.
+ *
+ * `ISwaggerComponents` is a data structure representing content of `components` object
+ * in `swagger.json` file generated by Nestia. Note that, this is not an universal
+ * structure, but a dedicated structure only for Nestia.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ISwaggerComponents {
+    /**
+     * An object to hold reusable DTO schemas.
+     *
+     * For reference, `nestia` stores every object and alias types as reusable DTO
+     * schemas. The alias type means that defined by `type` keyword in TypeScript.
+     */
+    schemas?: Record<string, IJsonComponents.IAlias>;
+    /**
+     * An object to hold reusable security schemes.
+     *
+     * This property be configured by user in `nestia.config.ts` file.
+     */
+    securitySchemes?: Record<string, ISwaggerSecurityScheme>;
+}

package/lib/structures/ISwaggerComponents.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ISwaggerComponents.js.map

package/lib/structures/ISwaggerComponents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISwaggerComponents.js","sourceRoot":"","sources":["../../src/structures/ISwaggerComponents.ts"],"names":[],"mappings":""}

package/lib/structures/ISwaggerInfo.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Information about the API.
+ *
+ * @author Samchon
+ */
+export interface ISwaggerInfo {
+    /**
+     * The title of the API.
+     */
+    title: string;
+    /**
+     * A short description of the API.
+     */
+    description?: string;
+    /**
+     * A URL to the Terms of Service for the API.
+     *
+     * @format uri
+     */
+    termsOfService?: string;
+    /**
+     * The contact information for the exposed API.
+     */
+    contact?: ISwaggerInfo.IContact;
+    /**
+     * The license information for the exposed API.
+     */
+    license?: ISwaggerInfo.ILicense;
+    /**
+     * Version of the API.
+     */
+    version: string;
+}
+export declare namespace ISwaggerInfo {
+    /**
+     * Contact information for the exposed API.
+     */
+    interface IContact {
+        /**
+         * The identifying name of the contact person/organization.
+         */
+        name?: string;
+        /**
+         * The URL pointing to the contact information.
+         *
+         * @format uri
+         */
+        url?: string;
+        /**
+         * The email address of the contact person/organization.
+         *
+         * @format email
+         */
+        email?: string;
+    }
+    /**
+     * License information for the exposed API.
+     */
+    interface ILicense {
+        /**
+         * The license name used for the API.
+         */
+        name: string;
+        /**
+         * A URL to the license used for the API.
+         *
+         * @format uri
+         */
+        url?: string;
+    }
+}

package/lib/structures/ISwaggerInfo.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ISwaggerInfo.js.map

package/lib/structures/ISwaggerInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISwaggerInfo.js","sourceRoot":"","sources":["../../src/structures/ISwaggerInfo.ts"],"names":[],"mappings":""}

package/lib/structures/ISwaggerRoute.d.ts

@@ -0,0 +1,46 @@
+import { IJsonSchema } from "typia";
+export interface ISwaggerRoute {
+    deprecated?: boolean;
+    security?: Record<string, string[]>[];
+    operationId?: string;
+    tags: string[];
+    parameters: ISwaggerRoute.IParameter[];
+    requestBody?: ISwaggerRoute.IRequestBody;
+    responses: ISwaggerRoute.IResponseBody;
+    summary?: string;
+    description?: string;
+}
+export declare namespace ISwaggerRoute {
+    interface IParameter {
+        name: string;
+        in: string;
+        schema: IJsonSchema;
+        required: boolean;
+        description?: string;
+    }
+    interface IRequestBody {
+        description?: string;
+        content: IContent;
+        required: true;
+        "x-nestia-encrypted"?: boolean;
+    }
+    type IResponseBody = Record<string, {
+        description: string;
+        content?: IContent;
+        "x-nestia-encrypted"?: boolean;
+    }>;
+    interface IContent {
+        "application/x-www-form-urlencoded"?: {
+            schema: IJsonSchema;
+        };
+        "application/json"?: {
+            schema: IJsonSchema;
+        };
+        "text/plain"?: {
+            schema: IJsonSchema;
+        };
+        "multipart/form-data"?: {
+            schema: IJsonSchema;
+        };
+    }
+}

package/lib/structures/ISwaggerRoute.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ISwaggerRoute.js.map

package/lib/structures/ISwaggerRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISwaggerRoute.js","sourceRoot":"","sources":["../../src/structures/ISwaggerRoute.ts"],"names":[],"mappings":""}

package/lib/structures/ISwaggerSecurityScheme.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Security scheme of Swagger Documents.
+ *
+ * `ISwaggerSecurityScheme` is a data structure representing content of
+ * `securitySchemes` in `swagger.json` file. It is composed with 5 types of security
+ * schemes as an union type like below.
+ *
+ * @reference https://swagger.io/specification/#security-scheme-object
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type ISwaggerSecurityScheme = ISwaggerSecurityScheme.IHttpBasic | ISwaggerSecurityScheme.IHttpBearer | ISwaggerSecurityScheme.IApiKey | ISwaggerSecurityScheme.IOpenId | ISwaggerSecurityScheme.IOAuth2;
+export declare namespace ISwaggerSecurityScheme {
+    interface IHttpBasic {
+        type: "http";
+        scheme: "basic";
+    }
+    interface IHttpBearer {
+        type: "http";
+        scheme: "bearer";
+        bearerFormat?: string;
+    }
+    interface IApiKey {
+        type: "apiKey";
+        /**
+         * @default header
+         */
+        in?: "header" | "query" | "cookie";
+        /**
+         * @default Authorization
+         */
+        name?: string;
+    }
+    interface IOpenId {
+        type: "openIdConnect";
+        openIdConnectUrl: string;
+    }
+    interface IOAuth2 {
+        type: "oauth2";
+        flows: IOAuth2.IFlowSet;
+        description?: string;
+    }
+    namespace IOAuth2 {
+        interface IFlowSet {
+            authorizationCode?: IFlow;
+            implicit?: Omit<IFlow, "tokenUrl">;
+            password?: Omit<IFlow, "authorizationUrl">;
+            clientCredentials?: Omit<IFlow, "authorizationUrl">;
+        }
+        interface IFlow {
+            authorizationUrl: string;
+            tokenUrl: string;
+            refreshUrl: string;
+            scopes?: Record<string, string>;
+        }
+    }
+}

package/lib/structures/ISwaggerSecurityScheme.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ISwaggerSecurityScheme.js.map

package/lib/structures/ISwaggerSecurityScheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISwaggerSecurityScheme.js","sourceRoot":"","sources":["../../src/structures/ISwaggerSecurityScheme.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/core",
-  "version": "2.5.8",
+  "version": "2.5.9",
   "description": "Super-fast validation decorators of NestJS",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -36,7 +36,7 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^2.5.8",
+    "@nestia/fetcher": "^2.5.9",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "detect-ts-node": "^1.0.5",
@@ -48,7 +48,7 @@
     "typia": "^5.4.5"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=2.5.8",
+    "@nestia/fetcher": ">=2.5.9",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",