@grandlinex/swagger-mate 1.3.1 → 1.3.3

package/dist/cjs/Swagger/SwaggerUtil.js

@@ -47,6 +47,13 @@ const PathHelp_js_1 = __importStar(require("../PathHelp.js"));
 const index_js_1 = require("./annotation/index.js");
 const index_js_2 = require("../index.js");
 class SwaggerUtil {
+    static getLogger() {
+        if (!this.logger) {
+            const logger = new core_1.DefaultLogger();
+            this.logger = new core_1.CoreLogChannel('SwaggerUtil', logger);
+        }
+        return this.logger;
+    }
     static writeMeta(conf, kind, path) {
         if (kind === 'JSON') {
             const p = Path.join(path || process.cwd(), 'openapi.json');
@@ -63,11 +70,25 @@ class SwaggerUtil {
             return JSON.parse(file);
         }
         catch (e) {
+            this.getLogger().error(e);
             return null;
         }
     }
-    static async serveMeta(conf, port, auth) {
-        const resFiles = (0, PathHelp_js_1.default)((0, PathHelp_js_1.getBaseFolder)(), '..', 'res', 'html');
+    /**
+     * Serves a meta page for Swagger UI or rapi-doc.
+     *
+     * @param {SwaggerConfig} conf The swagger configuration to expose via `/spec`.
+     * @param {Object} [option] Options for serving the meta page.
+     * @param {'swagger-ui'|'rapi-doc'} [option.type='swagger-ui'] The type of UI to serve.
+     * @param {number} [option.port] The port to listen on. Defaults to 9000.
+     * @param {string} [option.auth] Optional authentication key appended to the URL.
+     * @returns {Promise<Server|null>} A promise that resolves with the created server instance or null.
+     */
+    static async serveMeta(conf, option) {
+        const type = option?.type ?? 'swagger-ui';
+        const port = option?.port || 9000;
+        const auth = option?.auth;
+        const resFiles = (0, PathHelp_js_1.default)((0, PathHelp_js_1.getBaseFolder)(), '..', 'res', 'html', type);
         const key = auth ? `?auth=${auth}` : '';
         const app = (0, express_1.default)();
         app.use('/', express_1.default.static(resFiles));
@@ -75,8 +96,8 @@ class SwaggerUtil {
             res.status(200).send(conf);
         });
         return new Promise((resolve) => {
-            const s = app.listen(port || 9000, () => {
-                console.log(`listen on http://localhost:${port || 9000}${key}#`);
+            const s = app.listen(port, () => {
+                this.getLogger().log(`${type} listen on http://localhost:${port}${key}#`);
                 resolve(s);
             });
         });
@@ -121,7 +142,13 @@ class SwaggerUtil {
             // Handle requestBody
             if (!conf.requestBody) {
                 if (route.meta.requestSchema) {
-                    conf.requestBody = index_js_2.SPathUtil.jsonBody(route.meta.requestSchema);
+                    if (typeof route.meta.requestSchema === 'string' ||
+                        (0, core_1.instanceOfEntity)(route.meta.requestSchema)) {
+                        conf.requestBody = index_js_2.SPathUtil.refRequest(route.meta.requestSchema, route.meta.responseType === 'LIST');
+                    }
+                    else {
+                        conf.requestBody = index_js_2.SPathUtil.jsonBody(route.meta.requestSchema);
+                    }
                 }
             }
             // Handle responses

package/dist/cjs/Swagger/annotation/index.d.ts

@@ -8,13 +8,18 @@ export declare enum ActionMode {
     'DMZ_WITH_USER' = 2
 }
 export type ActionTypes = 'POST' | 'GET' | 'USE' | 'PATCH' | 'DELETE';
-export type ResponseTypes = 'LIST';
+/**
+ * LIST - Response is an array of items
+ * SINGLE - Response is a single item (default)
+ */
+export type ResponseRequestTypes = 'LIST' | 'SINGLE';
 export type RouteMeta = {
     pathOverride?: string;
     mode?: ActionMode;
-    requestSchema?: SSchemaEl;
+    requestSchema?: SSchemaEl | CoreEntity | string;
     responseSchema?: SSchemaEl | CoreEntity | string;
-    responseType?: ResponseTypes;
+    requestType?: ResponseRequestTypes;
+    responseType?: ResponseRequestTypes;
     responseCodes?: HttpStatusTypes[];
 } & SwaggerRPathConf;
 export type RouteData = {

package/dist/cjs/Swagger/debug/BaseCon.d.ts

@@ -38,13 +38,20 @@ export interface ConHandle {
     patch<T, J>(url: string, body?: J, config?: ConHandleConfig): Promise<ConHandleResponse<T>>;
     delete<T>(url: string, config?: ConHandleConfig): Promise<ConHandleResponse<T>>;
 }
+/**
+ * BaseCon provides a minimal client for interacting with an HTTP backend.
+ * It manages connection state, authentication tokens, and reconnection
+ * logic while delegating actual HTTP requests to a supplied {@link ConHandle}.
+ *
+ * @class
+ */
 export default class BaseCon {
-    api: string;
-    permanentHeader: undefined | Record<string, string>;
-    authorization: string | null;
-    disconnected: boolean;
-    failFlag: boolean;
-    logger: (arg: any) => void;
+    private api;
+    private permanentHeader;
+    private authorization;
+    private noAuth;
+    private disconnected;
+    private readonly logger;
     con: ConHandle;
     reconnect: () => Promise<boolean>;
     onReconnect: (con: BaseCon) => Promise<boolean>;
@@ -53,16 +60,113 @@ export default class BaseCon {
         endpoint: string;
         logger?: (arg: any) => void;
     });
+    /**
+     * Retrieves the API endpoint.
+     *
+     * @return {string} The API endpoint string.
+     */
+    getApiEndpoint(): string;
+    /**
+     * Sets the API endpoint URL used by the client.
+     *
+     * @param {string} endpoint - The full URL of the API endpoint.
+     * @returns {void}
+     */
+    setApiEndpoint(endpoint: string): void;
+    /**
+     * Indicates whether the instance is considered connected.
+     *
+     * The instance is regarded as connected when it either does not require authentication
+     * (`noAuth` is true) or it has an authorization token set (`authorization` is not null),
+     * and it is not currently marked as disconnected.
+     *
+     * @return {boolean} `true` if the instance is connected, `false` otherwise.
+     */
     isConnected(): boolean;
+    /**
+     * Returns the current authorization token.
+     *
+     * @return {string} The authorization token or an empty string if none is set.
+     */
     token(): string;
-    p(path: string, config?: ConHandleConfig): string;
+    private p;
+    /**
+     * Sends a ping request to the API to verify connectivity and version availability.
+     *
+     * @return {boolean} `true` if the API responded with a 200 status code and a valid version object; `false` otherwise.
+     */
     ping(): Promise<boolean>;
-    test(email: string, password: string): Promise<boolean>;
+    /**
+     * Validates the current authentication token by performing a ping and a test request
+     * to the backend. The method first ensures connectivity via {@link ping}. If the ping
+     * succeeds, it attempts to retrieve a token from the `/test/auth` endpoint using the
+     * current token in the `Authorization` header. The operation is considered successful
+     * if the response status code is 200 or 201.
+     *
+     * If any step fails, an error is logged and the method returns {@code false}. On
+     * success, it returns {@code true}.
+     *
+     * @return {Promise<boolean>} A promise that resolves to {@code true} if the token
+     * test succeeds, otherwise {@code false}.
+     */
     testToken(): Promise<boolean>;
-    connect(email: string, pw: string): Promise<boolean>;
     /**
-     * Enable client before auth
+     * Attempts to establish a connection to the backend without authentication.
+     *
+     * This method sends a ping request.  If the ping succeeds, it clears any
+     * existing authorization data, marks the instance as connected,
+     * enables the no‑authentication mode, and returns `true`.  If the ping
+     * fails, it logs a warning, clears authorization, marks the instance
+     * as disconnected, and returns `false`.
+     *
+     * @return {Promise<boolean>} `true` when a connection is successfully
+     * established without authentication, otherwise `false`.
+     */
+    connectNoAuth(): Promise<boolean>;
+    /**
+     * Forces a connection using the provided bearer token.
+     *
+     * @param {string} token The token to be used for authentication.
+     * @returns {void}
+     */
+    forceConnectWithToken(token: string): void;
+    /**
+     * Establishes a connection to the backend using the supplied credentials.
+     * Performs a health‑check ping first; if successful, it requests an authentication
+     * token from the `/token` endpoint.  When the token is obtained, the method
+     * updates internal state (authorization header, connection flags) and, unless
+     * a dry run is requested, sets up a reconnection routine.  Any errors are
+     * logged and the method resolves to `false`.
+     *
+     * @param {string} email - The user's email address for authentication.
+     * @param {string} pw - The password (or token) for the specified user.
+     * @param {boolean} [dry=false] - If `true`, the method performs a dry run
+     *   without persisting credentials or configuring reconnection logic.
+     *
+     * @returns  Promise<boolean>  `true` if the connection was successfully
+     *   established, otherwise `false`.
+     */
+    connect(email: string, pw: string, dry?: boolean): Promise<boolean>;
+    /**
+     * Performs an HTTP request using the client’s internal connection.
+     *
+     * The method verifies that the client is connected before attempting a request.
+     * It automatically injects the authorization token, permanent headers, and any
+     * headers supplied in `config`. If the request body is a `FormData` instance
+     * (or provides a `getHeaders` method), the appropriate form headers are added.
+     *
+     * Response handling:
+     * - `200` or `201`: returns `success: true` with the received data.
+     * - `498`: attempts to reconnect and retries the request once.
+     * - `401`: logs an authentication error, marks the client as disconnected.
+     * - `403` and other status codes: return `success: false` with the status code.
+     *
+     * @param {'POST'|'GET'|'PATCH'|'DELETE'} type The HTTP method to use.
+     * @param {string} path The endpoint path relative to the base URL.
+     * @param {J} [body] Optional request payload. May be `FormData` or a plain object.
+     * @param {ConHandleConfig} [config] Optional Axios-like configuration for the request.
+     * @returns {Promise<HandleRes<T>>} A promise that resolves to a `HandleRes` object
+     * containing the response data, status code, any error information, and headers.
      */
-    fakeEnableClient(): void;
     handle<T, J>(type: 'POST' | 'GET' | 'PATCH' | 'DELETE', path: string, body?: J, config?: ConHandleConfig): Promise<HandleRes<T>>;
 }

package/dist/cjs/Swagger/debug/BaseCon.js

@@ -12,13 +12,20 @@ const form_data_1 = __importDefault(require("form-data"));
 function isErrorType(x) {
     return x && typeof x === 'object' && x.type === 'error';
 }
+/**
+ * BaseCon provides a minimal client for interacting with an HTTP backend.
+ * It manages connection state, authentication tokens, and reconnection
+ * logic while delegating actual HTTP requests to a supplied {@link ConHandle}.
+ *
+ * @class
+ */
 class BaseCon {
     constructor(conf) {
         this.api = conf.endpoint;
-        this.logger = conf.logger || console.log;
+        this.logger = conf.logger ?? console.log;
         this.disconnected = true;
+        this.noAuth = false;
         this.authorization = null;
-        this.failFlag = false;
         this.con = conf.con;
         this.reconnect = async () => {
             this.disconnected = true;
@@ -27,10 +34,40 @@ class BaseCon {
         this.onReconnect = () => Promise.resolve(true);
         this.handle = this.handle.bind(this);
     }
-    // Class helper functions
+    /**
+     * Retrieves the API endpoint.
+     *
+     * @return {string} The API endpoint string.
+     */
+    getApiEndpoint() {
+        return this.api;
+    }
+    /**
+     * Sets the API endpoint URL used by the client.
+     *
+     * @param {string} endpoint - The full URL of the API endpoint.
+     * @returns {void}
+     */
+    setApiEndpoint(endpoint) {
+        this.api = endpoint;
+    }
+    /**
+     * Indicates whether the instance is considered connected.
+     *
+     * The instance is regarded as connected when it either does not require authentication
+     * (`noAuth` is true) or it has an authorization token set (`authorization` is not null),
+     * and it is not currently marked as disconnected.
+     *
+     * @return {boolean} `true` if the instance is connected, `false` otherwise.
+     */
     isConnected() {
-        return this.authorization !== null && !this.disconnected;
+        return (this.noAuth || this.authorization !== null) && !this.disconnected;
     }
+    /**
+     * Returns the current authorization token.
+     *
+     * @return {string} The authorization token or an empty string if none is set.
+     */
     token() {
         return this.authorization || '';
     }
@@ -56,35 +93,34 @@ class BaseCon {
         }
         return `${this.api}${pp}`;
     }
+    /**
+     * Sends a ping request to the API to verify connectivity and version availability.
+     *
+     * @return {boolean} `true` if the API responded with a 200 status code and a valid version object; `false` otherwise.
+     */
     async ping() {
         try {
             const version = await this.con.get(this.p('/version'));
-            return version.data?.api === 1 && version.code === 200;
+            return version.data?.api !== undefined && version.code === 200;
         }
         catch (e) {
             this.logger('ping failed');
             return false;
         }
     }
-    async test(email, password) {
-        const ping = await this.ping();
-        if (ping) {
-            try {
-                this.logger({ email, password });
-                const con = await this.con.post(this.p('/token'), {
-                    username: email,
-                    token: password,
-                });
-                return con.code === 200 || con.code === 201;
-            }
-            catch (e) {
-                this.logger(e);
-                this.logger('cant connect to backend');
-            }
-        }
-        this.logger('test ping failed');
-        return false;
-    }
+    /**
+     * Validates the current authentication token by performing a ping and a test request
+     * to the backend. The method first ensures connectivity via {@link ping}. If the ping
+     * succeeds, it attempts to retrieve a token from the `/test/auth` endpoint using the
+     * current token in the `Authorization` header. The operation is considered successful
+     * if the response status code is 200 or 201.
+     *
+     * If any step fails, an error is logged and the method returns {@code false}. On
+     * success, it returns {@code true}.
+     *
+     * @return {Promise<boolean>} A promise that resolves to {@code true} if the token
+     * test succeeds, otherwise {@code false}.
+     */
     async testToken() {
         const ping = await this.ping();
         if (ping) {
@@ -104,7 +140,59 @@ class BaseCon {
         this.logger('test ping failed');
         return false;
     }
-    async connect(email, pw) {
+    /**
+     * Attempts to establish a connection to the backend without authentication.
+     *
+     * This method sends a ping request.  If the ping succeeds, it clears any
+     * existing authorization data, marks the instance as connected,
+     * enables the no‑authentication mode, and returns `true`.  If the ping
+     * fails, it logs a warning, clears authorization, marks the instance
+     * as disconnected, and returns `false`.
+     *
+     * @return {Promise<boolean>} `true` when a connection is successfully
+     * established without authentication, otherwise `false`.
+     */
+    async connectNoAuth() {
+        const ping = await this.ping();
+        if (ping) {
+            this.authorization = null;
+            this.disconnected = false;
+            this.noAuth = true;
+            return true;
+        }
+        this.logger('cant connect to backend');
+        this.authorization = null;
+        this.disconnected = true;
+        return false;
+    }
+    /**
+     * Forces a connection using the provided bearer token.
+     *
+     * @param {string} token The token to be used for authentication.
+     * @returns {void}
+     */
+    forceConnectWithToken(token) {
+        this.authorization = `Bearer ${token}`;
+        this.disconnected = false;
+        this.noAuth = false;
+    }
+    /**
+     * Establishes a connection to the backend using the supplied credentials.
+     * Performs a health‑check ping first; if successful, it requests an authentication
+     * token from the `/token` endpoint.  When the token is obtained, the method
+     * updates internal state (authorization header, connection flags) and, unless
+     * a dry run is requested, sets up a reconnection routine.  Any errors are
+     * logged and the method resolves to `false`.
+     *
+     * @param {string} email - The user's email address for authentication.
+     * @param {string} pw - The password (or token) for the specified user.
+     * @param {boolean} [dry=false] - If `true`, the method performs a dry run
+     *   without persisting credentials or configuring reconnection logic.
+     *
+     * @returns  Promise<boolean>  `true` if the connection was successfully
+     *   established, otherwise `false`.
+     */
+    async connect(email, pw, dry = false) {
         const ping = await this.ping();
         if (ping) {
             try {
@@ -112,13 +200,15 @@ class BaseCon {
                     username: email,
                     token: pw,
                 });
-                // TODO check token
                 if (token.code === 200 || token.code === 201) {
-                    this.authorization = `Bearer ${token.data?.token}`;
-                    this.disconnected = false;
-                    this.reconnect = async () => {
-                        return (await this.connect(email, pw)) && (await this.testToken());
-                    };
+                    if (!dry) {
+                        this.authorization = `Bearer ${token.data?.token}`;
+                        this.disconnected = false;
+                        this.noAuth = false;
+                        this.reconnect = async () => {
+                            return ((await this.connect(email, pw)) && (await this.testToken()));
+                        };
+                    }
                     return true;
                 }
             }
@@ -129,17 +219,32 @@ class BaseCon {
         this.logger('cant connect to backend');
         this.authorization = null;
         this.disconnected = true;
+        this.noAuth = false;
         return false;
     }
     /**
-     * Enable client before auth
+     * Performs an HTTP request using the client’s internal connection.
+     *
+     * The method verifies that the client is connected before attempting a request.
+     * It automatically injects the authorization token, permanent headers, and any
+     * headers supplied in `config`. If the request body is a `FormData` instance
+     * (or provides a `getHeaders` method), the appropriate form headers are added.
+     *
+     * Response handling:
+     * - `200` or `201`: returns `success: true` with the received data.
+     * - `498`: attempts to reconnect and retries the request once.
+     * - `401`: logs an authentication error, marks the client as disconnected.
+     * - `403` and other status codes: return `success: false` with the status code.
+     *
+     * @param {'POST'|'GET'|'PATCH'|'DELETE'} type The HTTP method to use.
+     * @param {string} path The endpoint path relative to the base URL.
+     * @param {J} [body] Optional request payload. May be `FormData` or a plain object.
+     * @param {ConHandleConfig} [config] Optional Axios-like configuration for the request.
+     * @returns {Promise<HandleRes<T>>} A promise that resolves to a `HandleRes` object
+     * containing the response data, status code, any error information, and headers.
      */
-    fakeEnableClient() {
-        this.authorization = 'DEBUG';
-        this.disconnected = false;
-    }
     async handle(type, path, body, config) {
-        if (!this.authorization || this.disconnected) {
+        if (!this.isConnected()) {
             this.logger('Disconnected');
             return {
                 success: false,
@@ -246,7 +351,6 @@ class BaseCon {
                 };
             case 401:
                 this.logger('AUTH NOT VALID');
-                this.disconnected = true;
                 return {
                     success: false,
                     data: null,

package/dist/cjs/cli.js

@@ -76,7 +76,11 @@ async function run() {
             console.log('Serving Swagger Meta');
             const auth = process.env.SW_AUTH || undefined;
             const port = process.env.SW_PORT || undefined;
-            SwaggerUtil_js_1.default.serveMeta(conf, port ? parseInt(port, 10) : undefined, auth);
+            SwaggerUtil_js_1.default.serveMeta(conf, {
+                port: port ? parseInt(port, 10) : undefined,
+                auth,
+                type: 'rapi-doc',
+            });
         }
         if (arg[arg.length - 2] === '--build') {
             console.log('Building Swagger Meta');

package/dist/cjs/index.d.ts

@@ -1,6 +1,7 @@
 import SwaggerUtil from './Swagger/SwaggerUtil.js';
 import SPathUtil from './Swagger/Path/SPathUtil.js';
 import SwaggerClient from './Swagger/Client/SwaggerClient.js';
+export * from './Swagger/Path/ESchemaEditor.js';
 export * from './Swagger/debug/index.js';
 export * from './Swagger/annotation/index.js';
 export * from './Swagger/Meta/Swagger.js';

package/dist/cjs/index.js

@@ -24,6 +24,7 @@ const SPathUtil_js_1 = __importDefault(require("./Swagger/Path/SPathUtil.js"));
 exports.SPathUtil = SPathUtil_js_1.default;
 const SwaggerClient_js_1 = __importDefault(require("./Swagger/Client/SwaggerClient.js"));
 exports.SwaggerClient = SwaggerClient_js_1.default;
+__exportStar(require("./Swagger/Path/ESchemaEditor.js"), exports);
 __exportStar(require("./Swagger/debug/index.js"), exports);
 __exportStar(require("./Swagger/annotation/index.js"), exports);
 __exportStar(require("./Swagger/Meta/Swagger.js"), exports);

package/dist/mjs/Swagger/Meta/SwaggerTypes.d.ts

@@ -56,7 +56,7 @@ export interface SwaggerRInfo {
     version: string;
     license?: SwaggerRInfoLicence;
 }
-export type SSchemaEl = {
+export type SSchemaElObj = {
     type: SDataType;
     example?: string;
     format?: SDataFormat;
@@ -68,7 +68,8 @@ export type SSchemaEl = {
     required?: string[];
     enum?: string[];
     nullable?: boolean;
-} | SwaggerRRef;
+};
+export type SSchemaEl = SSchemaElObj | SwaggerRRef;
 export type SwaggerContent = {
     [K in SMediaType]?: {
         schema: SSchemaEl;

package/dist/mjs/Swagger/Path/ESchemaEditor.d.ts

@@ -0,0 +1,51 @@
+import { CoreEntity } from '@grandlinex/core';
+import { SKey, SSchemaEl, SSchemaElObj } from '../Meta/SwaggerTypes.js';
+export type ESchemaAddOption = {
+    key: string;
+    list?: boolean;
+    entity?: CoreEntity;
+    schema?: SSchemaEl;
+    required?: boolean;
+    nullable?: boolean;
+};
+export declare class ESchemaEditor<T extends CoreEntity> {
+    private data;
+    private name;
+    private constructor();
+    /**
+     * Removes the specified keys from the schema's properties and updates the required list.
+     *
+     * @param {...(keyof T)} keys - The keys of the properties to remove.
+     * @returns {ESchemaEditor<T>} The editor instance for method chaining.
+     */
+    remove(...keys: (keyof T)[]): ESchemaEditor<T>;
+    /**
+     * Adds properties to the schema based on the provided options.
+     *
+     * @param {...ESchemaAddOption} options The options describing the properties to add. Each option may specify a
+     *   `key`, a `schema` or an `entity`, and optionally whether the property is a `list`, `nullable`, or `required`.
+     * @returns {ESchemaEditor<T>} The editor instance for chaining.
+     */
+    add(...options: ESchemaAddOption[]): ESchemaEditor<T>;
+    getSchema(): SSchemaElObj;
+    getSKeySchema(): SKey<SSchemaElObj>;
+    static fromEntity<J extends CoreEntity>(e: J): ESchemaEditor<J>;
+    /**
+     * Generates a JSON schema representation from a CoreEntity instance.
+     *
+     * This method inspects the entity's metadata to construct a schema object
+     * describing the entity's shape. The resulting schema contains:
+     * - `type`: always `"object"`.
+     * - `description`: a string indicating the entity name.
+     * - `required`: an array of property names that are defined on the entity.
+     * - `properties`: an object mapping each property name to an object that
+     *   includes the resolved database type and its nullability.
+     *
+     * If no metadata is found for the provided entity, the method returns `undefined`.
+     *
+     * @param {T} entity - The entity instance for which to create a schema.
+     * @returns {SSchemaElObj | undefined} The generated schema object, or `undefined`
+     *          if the entity's metadata could not be retrieved.
+     */
+    static schemaFromEntity<T extends CoreEntity>(entity: T): SSchemaElObj | undefined;
+}