@grandlinex/swagger-mate 1.3.2 → 1.3.4

package/dist/cjs/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/cjs/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;
+}

package/dist/cjs/Swagger/Path/ESchemaEditor.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ESchemaEditor = void 0;
+const core_1 = require("@grandlinex/core");
+function resolveDBType(dType) {
+    switch (dType) {
+        case 'int':
+        case 'long':
+            return 'integer';
+        case 'double':
+        case 'float':
+            return 'number';
+        case 'blob':
+            return 'string';
+        case 'string':
+        case 'text':
+        case 'uuid':
+            return 'string';
+        case 'boolean':
+            return 'boolean';
+        case 'date':
+            return 'string';
+        case 'json':
+            return 'object';
+        default:
+            throw Error('TypeNotSupported');
+    }
+}
+class ESchemaEditor {
+    constructor(entity, name) {
+        this.data = ESchemaEditor.schemaFromEntity(entity);
+        this.name = name;
+    }
+    /**
+     * 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) {
+        if (this.data.properties) {
+            for (const key of keys) {
+                this.data.properties = Object.fromEntries(Object.entries(this.data.properties).filter(([e]) => key !== e));
+                this.data.required = (this.data.required || []).filter((e) => key !== e);
+            }
+        }
+        return this;
+    }
+    /**
+     * 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) {
+        if (!this.data.properties) {
+            return this;
+        }
+        for (const option of options) {
+            if (option.schema) {
+                if (option.list) {
+                    this.data.properties[option.key] = {
+                        type: 'array',
+                        items: option.schema,
+                        nullable: option.nullable,
+                    };
+                }
+                else {
+                    this.data.properties[option.key] = option.schema;
+                }
+            }
+            else if (option.entity) {
+                const scheme = ESchemaEditor.fromEntity(option.entity).getSchema();
+                if (option.nullable) {
+                    scheme.nullable = true;
+                }
+                if (option.list) {
+                    this.data.properties[option.key] = {
+                        type: 'array',
+                        items: scheme,
+                    };
+                }
+                else {
+                    this.data.properties[option.key] = scheme;
+                }
+            }
+            if (option.required) {
+                this.data.required = [...(this.data.required || []), option.key];
+            }
+        }
+        return this;
+    }
+    getSchema() {
+        return this.data;
+    }
+    getSKeySchema() {
+        return {
+            [this.name]: this.data,
+        };
+    }
+    static fromEntity(e) {
+        const meta = (0, core_1.getEntityMeta)(e);
+        if (meta) {
+            return new ESchemaEditor(e, meta.name);
+        }
+        throw new Error('Entity metadata not found');
+    }
+    /**
+     * 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(entity) {
+        const schema = {
+            type: 'object',
+            properties: {},
+        };
+        const meta = (0, core_1.getEntityMeta)(entity);
+        if (!meta) {
+            return undefined;
+        }
+        schema.description = `Entity: ${meta.name}`;
+        schema.required = [];
+        const keys = Object.keys(entity);
+        keys.forEach((k) => {
+            const cMeta = (0, core_1.getColumnMeta)(entity, k);
+            if (cMeta && schema.properties) {
+                schema.required.push(k);
+                schema.properties[k] = {
+                    type: resolveDBType(cMeta.dataType),
+                    nullable: cMeta.canBeNull,
+                };
+            }
+        });
+        return schema;
+    }
+}
+exports.ESchemaEditor = ESchemaEditor;

package/dist/cjs/Swagger/Path/SPathUtil.d.ts

@@ -1,6 +1,7 @@
 import { CoreEntity } from '@grandlinex/core';
 import { HttpStatusTypes } from '../Meta/SwaggerTypesStatic.js';
-import { SKey, SSchemaEl, SwaggerContent, SwaggerRPathConfResponse, SwaggerRPathReqBody } from '../Meta/SwaggerTypes.js';
+import { SKey, SSchemaEl, SSchemaElObj, SwaggerContent, SwaggerRPathConfResponse, SwaggerRPathReqBody } from '../Meta/SwaggerTypes.js';
+import { ESchemaEditor } from './ESchemaEditor.js';
 export default class SPathUtil {
     /**
      * Generates a default response mapping for the specified HTTP status types.
@@ -90,10 +91,11 @@ export default class SPathUtil {
      * 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 {SSchemaEl | undefined} The generated schema object, or `undefined`
+     * @returns {SSchemaElObj | undefined} The generated schema object, or `undefined`
      *          if the entity's metadata could not be retrieved.
+     * @deprecated Use {@link ESchemaEditor.schemaFromEntity} instead.
      */
-    static schemaFromEntity<T extends CoreEntity>(entity: T): SSchemaEl | undefined;
+    static schemaFromEntity<T extends CoreEntity>(entity: T): SSchemaElObj | undefined;
     /**
      * Generates a content schema object for the given entity. The schema contains a description derived from the entity metadata and a JSON content schema based on the entity's structure.
      *
@@ -114,7 +116,7 @@ export default class SPathUtil {
      * @param {CoreEntity[]} e The entities for which schema entries should be generated.
      * @return {SKey<SSchemaEl>} An object whose keys are entity names and values are the schemas derived from those entities.
      */
-    static schemaEntryGen(...e: CoreEntity[]): SKey<SSchemaEl>;
+    static schemaEntryGen(...e: CoreEntity[]): SKey<SSchemaElObj>;
     /**
      * Builds a JSON schema representation for an entity view that includes both the
      * entity data and its related entity map.
@@ -124,76 +126,5 @@ export default class SPathUtil {
      * @returns A {@link SSchemaEl} object schema with properties `i`, `dat`, and `join_map`.
      */
     static schemaFromEntityView<A extends CoreEntity, B extends CoreEntity>(entity: A, entityMap: B): SSchemaEl;
-    /**
-     * Extends an entity schema object by merging additional schema options.
-     *
-     * @param {CoreEntity} entity
-     *   The entity for which the schema should be extended.
-     *
-     * @param {...Object} options
-     *   One or more objects defining schema extensions. Each object may contain:
-     *   - `key` (string): The property key to add or extend.
-     *   - `list` (boolean, optional): Indicates whether the property is a list.
-     *   - `entity` (CoreEntity, optional): The entity type for the property.
-     *   - `schema` (SSchemaEl, optional): A custom schema definition for the property.
-     *   - `required` (boolean, optional): Whether the property is required.
-     *
-     * @return {SSchemaEl}
-     *   The resulting schema element. If a single property is returned by
-     *   `extendEntitySchema`, its schema is returned directly; otherwise an
-     *   object schema with a type of `'object'` is returned.
-     */
-    static extendEntitySchemaObject(entity: CoreEntity, ...options: {
-        key: string;
-        list?: boolean;
-        entity?: CoreEntity;
-        schema?: SSchemaEl;
-        required?: boolean;
-    }[]): SSchemaEl;
-    /**
-     * Extends the schema of a given {@link CoreEntity} with additional properties.
-     *
-     * @param {CoreEntity} entity
-     *   The entity whose schema will be extended.
-     *
-     * @param {...{
-     *   key: string,
-     *   list?: boolean,
-     *   entity?: CoreEntity,
-     *   schema?: SSchemaEl,
-     *   required?: boolean
-     * }} options
-     *   One or more option objects specifying the extensions to apply. Each option
-     *   may provide either a direct schema (`schema`) or an entity reference
-     *   (`entity`). The `list` flag indicates whether the property should be
-     *   represented as an array of the provided schema. The `required` flag
-     *   adds the property to the schema’s required list.
-     *
-     * @returns {SKey<SSchemaEl>}
-     *   An object containing the updated schema for the entity, keyed by the
-     *   entity’s name. If the entity metadata cannot be found, an empty
-     *   object is returned.
-     */
-    static extendEntitySchema(entity: CoreEntity, ...options: {
-        key: string;
-        list?: boolean;
-        entity?: CoreEntity;
-        schema?: SSchemaEl;
-        required?: boolean;
-    }[]): SKey<SSchemaEl>;
-    /**
-     * Reduces the entity schema to a single schema element or a generic object.
-     *
-     * @param entity The entity whose schema should be reduced.
-     * @param keys Optional list of keys to include in the reduced schema. If omitted, all keys are considered.
-     * @return Returns the schema element of the sole key if only one key is present; otherwise, returns a generic object schema with type `'object'`. */
-    static reduceEntitySchemaObject<T extends CoreEntity>(entity: T, ...keys: (keyof T)[]): SSchemaEl;
-    /**
-     * Creates a reduced version of an entity's schema by excluding specified properties.
-     *
-     * @param {CoreEntity} entity - The entity whose schema is to be processed.
-     * @param {...string} keys - Property names to remove from the schema's `properties` and `required` lists.
-     *
-     * @returns */
-    static reduceEntitySchema<T extends CoreEntity>(entity: T, ...keys: (keyof T)[]): SKey<SSchemaEl>;
+    static editor<J extends CoreEntity>(e: J): ESchemaEditor<J>;
 }

package/dist/cjs/Swagger/Path/SPathUtil.js

@@ -5,31 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@grandlinex/core");
 const SUtilMap_js_1 = __importDefault(require("./SUtilMap.js"));
-const SwaggerTypes_js_1 = require("../Meta/SwaggerTypes.js");
-function resolveDBType(dType) {
-    switch (dType) {
-        case 'int':
-        case 'long':
-            return 'integer';
-        case 'double':
-        case 'float':
-            return 'number';
-        case 'blob':
-            return 'string';
-        case 'string':
-        case 'text':
-        case 'uuid':
-            return 'string';
-        case 'boolean':
-            return 'boolean';
-        case 'date':
-            return 'string';
-        case 'json':
-            return 'object';
-        default:
-            throw Error('TypeNotSupported');
-    }
-}
+const ESchemaEditor_js_1 = require("./ESchemaEditor.js");
 class SPathUtil {
     /**
      * Generates a default response mapping for the specified HTTP status types.
@@ -266,32 +242,12 @@ class SPathUtil {
      * 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 {SSchemaEl | undefined} The generated schema object, or `undefined`
+     * @returns {SSchemaElObj | undefined} The generated schema object, or `undefined`
      *          if the entity's metadata could not be retrieved.
+     * @deprecated Use {@link ESchemaEditor.schemaFromEntity} instead.
      */
     static schemaFromEntity(entity) {
-        const schema = {
-            type: 'object',
-            properties: {},
-        };
-        const meta = (0, core_1.getEntityMeta)(entity);
-        if (!meta) {
-            return undefined;
-        }
-        schema.description = `Entity: ${meta.name}`;
-        schema.required = [];
-        const keys = Object.keys(entity);
-        keys.forEach((k) => {
-            const cMeta = (0, core_1.getColumnMeta)(entity, k);
-            if (cMeta && schema.properties) {
-                schema.required.push(k);
-                schema.properties[k] = {
-                    type: resolveDBType(cMeta.dataType),
-                    nullable: cMeta.canBeNull,
-                };
-            }
-        });
-        return schema;
+        return ESchemaEditor_js_1.ESchemaEditor.schemaFromEntity(entity);
     }
     /**
      * Generates a content schema object for the given entity. The schema contains a description derived from the entity metadata and a JSON content schema based on the entity's structure.
@@ -308,7 +264,7 @@ class SPathUtil {
             description: `Entity: ${meta.name}`,
             content: {
                 'application/json': {
-                    schema: this.schemaFromEntity(entity),
+                    schema: ESchemaEditor_js_1.ESchemaEditor.schemaFromEntity(entity),
                 },
             },
         };
@@ -324,7 +280,7 @@ class SPathUtil {
         e.forEach((el) => {
             const meta = (0, core_1.getEntityMeta)(el);
             if (meta) {
-                out[meta.name] = SPathUtil.schemaFromEntity(el);
+                out[meta.name] = ESchemaEditor_js_1.ESchemaEditor.schemaFromEntity(el);
             }
         });
         return out;
@@ -344,141 +300,13 @@ class SPathUtil {
                 i: {
                     type: 'integer',
                 },
-                dat: this.schemaFromEntity(entity),
-                join_map: this.schemaFromEntity(entityMap),
+                dat: ESchemaEditor_js_1.ESchemaEditor.schemaFromEntity(entity),
+                join_map: ESchemaEditor_js_1.ESchemaEditor.schemaFromEntity(entityMap),
             },
         };
     }
-    /**
-     * Extends an entity schema object by merging additional schema options.
-     *
-     * @param {CoreEntity} entity
-     *   The entity for which the schema should be extended.
-     *
-     * @param {...Object} options
-     *   One or more objects defining schema extensions. Each object may contain:
-     *   - `key` (string): The property key to add or extend.
-     *   - `list` (boolean, optional): Indicates whether the property is a list.
-     *   - `entity` (CoreEntity, optional): The entity type for the property.
-     *   - `schema` (SSchemaEl, optional): A custom schema definition for the property.
-     *   - `required` (boolean, optional): Whether the property is required.
-     *
-     * @return {SSchemaEl}
-     *   The resulting schema element. If a single property is returned by
-     *   `extendEntitySchema`, its schema is returned directly; otherwise an
-     *   object schema with a type of `'object'` is returned.
-     */
-    static extendEntitySchemaObject(entity, ...options) {
-        const schema = this.extendEntitySchema(entity, ...options);
-        const ent = Object.entries(schema);
-        if (ent.length === 1) {
-            return ent[0][1];
-        }
-        return {
-            type: 'object',
-        };
-    }
-    /**
-     * Extends the schema of a given {@link CoreEntity} with additional properties.
-     *
-     * @param {CoreEntity} entity
-     *   The entity whose schema will be extended.
-     *
-     * @param {...{
-     *   key: string,
-     *   list?: boolean,
-     *   entity?: CoreEntity,
-     *   schema?: SSchemaEl,
-     *   required?: boolean
-     * }} options
-     *   One or more option objects specifying the extensions to apply. Each option
-     *   may provide either a direct schema (`schema`) or an entity reference
-     *   (`entity`). The `list` flag indicates whether the property should be
-     *   represented as an array of the provided schema. The `required` flag
-     *   adds the property to the schema’s required list.
-     *
-     * @returns {SKey<SSchemaEl>}
-     *   An object containing the updated schema for the entity, keyed by the
-     *   entity’s name. If the entity metadata cannot be found, an empty
-     *   object is returned.
-     */
-    static extendEntitySchema(entity, ...options) {
-        const meta = (0, core_1.getEntityMeta)(entity);
-        if (meta) {
-            const schema = SPathUtil.schemaEntryGen(entity)[meta.name];
-            if (schema && !(0, SwaggerTypes_js_1.isSwaggerRef)(schema) && schema.properties) {
-                for (const option of options) {
-                    if (option.schema) {
-                        if (option.list) {
-                            schema.properties[option.key] = {
-                                type: 'array',
-                                items: option.schema,
-                            };
-                        }
-                        else {
-                            schema.properties[option.key] = option.schema;
-                        }
-                    }
-                    else if (option.entity) {
-                        const eMeta = (0, core_1.getEntityMeta)(option.entity);
-                        if (eMeta) {
-                            const scheme = SPathUtil.schemaEntryGen(option.entity)[eMeta.name];
-                            if (option.list) {
-                                schema.properties[option.key] = {
-                                    type: 'array',
-                                    items: scheme,
-                                };
-                            }
-                            else {
-                                schema.properties[option.key] = scheme;
-                            }
-                        }
-                    }
-                    if (option.required) {
-                        schema.required = [...(schema.required || []), option.key];
-                    }
-                }
-            }
-            return {
-                [meta.name]: schema,
-            };
-        }
-        return {};
-    }
-    /**
-     * Reduces the entity schema to a single schema element or a generic object.
-     *
-     * @param entity The entity whose schema should be reduced.
-     * @param keys Optional list of keys to include in the reduced schema. If omitted, all keys are considered.
-     * @return Returns the schema element of the sole key if only one key is present; otherwise, returns a generic object schema with type `'object'`. */
-    static reduceEntitySchemaObject(entity, ...keys) {
-        const schema = this.reduceEntitySchema(entity, ...keys);
-        const ent = Object.entries(schema);
-        if (ent.length === 1) {
-            return ent[0][1];
-        }
-        return {
-            type: 'object',
-        };
-    }
-    /**
-     * Creates a reduced version of an entity's schema by excluding specified properties.
-     *
-     * @param {CoreEntity} entity - The entity whose schema is to be processed.
-     * @param {...string} keys - Property names to remove from the schema's `properties` and `required` lists.
-     *
-     * @returns */
-    static reduceEntitySchema(entity, ...keys) {
-        const meta = (0, core_1.getEntityMeta)(entity);
-        if (meta) {
-            const schema = SPathUtil.schemaEntryGen(entity)[meta.name];
-            if (schema && !(0, SwaggerTypes_js_1.isSwaggerRef)(schema) && schema.properties) {
-                schema.properties = Object.fromEntries(Object.entries(schema.properties).filter(([e]) => !keys.includes(e)));
-                schema.required = (schema.required || []).filter((e) => !keys.includes(e));
-            }
-            return { [meta.name]: schema };
-        }
-        return {};
+    static editor(e) {
+        return ESchemaEditor_js_1.ESchemaEditor.fromEntity(e);
     }
 }
 exports.default = SPathUtil;

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

@@ -55,10 +55,21 @@ export default class BaseCon {
     con: ConHandle;
     reconnect: () => Promise<boolean>;
     onReconnect: (con: BaseCon) => Promise<boolean>;
+    /**
+     * Initializes a new instance of the client.
+     *
+     * @param {Object} conf Configuration object.
+     * @param {ConHandle} conf.con - Connection handle.
+     * @param {string} conf.endpoint - API endpoint URL.
+     * @param {(arg: any) => void} [conf.logger] - Optional logger function; defaults to console.log.
+     * @param {Record<string, string>} [conf.permanentHeader] - Optional permanent headers to include in requests.
+     * @return {void}
+     */
     constructor(conf: {
         con: ConHandle;
         endpoint: string;
         logger?: (arg: any) => void;
+        permanentHeader?: Record<string, string>;
     });
     /**
      * Retrieves the API endpoint.
@@ -84,11 +95,17 @@ export default class BaseCon {
      */
     isConnected(): boolean;
     /**
-     * Returns the current authorization token.
+     * Retrieves the current authorization token.
+     *
+     * @return {string|null} The token string used for authorization, or {@code null} if no token is set.
+     */
+    token(): string | null;
+    /**
+     * Returns the bearer token string if an authorization value has been set.
      *
-     * @return {string} The authorization token or an empty string if none is set.
+     * @return {string|null} The bearer token prefixed with "Bearer ", or {@code null} when no authorization is present.
      */
-    token(): string;
+    getBearer(): string | null;
     private p;
     /**
      * Sends a ping request to the API to verify connectivity and version availability.
@@ -96,6 +113,18 @@ export default class BaseCon {
      * @return {boolean} `true` if the API responded with a 200 status code and a valid version object; `false` otherwise.
      */
     ping(): Promise<boolean>;
+    /**
+     * Builds the Authorization header for HTTP requests.
+     *
+     * If the instance has an authorization token, this method returns an object
+     * containing a single `Authorization` header with the Bearer token value.
+     * When no token is available, an empty header object is returned.
+     *
+     * @return {Record<string, string>} The headers object containing the
+     * `Authorization` header when applicable, otherwise an empty object.
+     */
+    private tokenHeader;
+    setPermanentHeader(header: Record<string, string>): void;
     /**
      * 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
@@ -126,10 +155,11 @@ export default class BaseCon {
     /**
      * Forces a connection using the provided bearer token.
      *
-     * @param {string} token The token to be used for authentication.
+     * @param {string|null} token The token to be used for authentication.
      * @returns {void}
      */
-    forceConnectWithToken(token: string): void;
+    forceConnect(token: string | null): void;
+    coppyFrom(con: BaseCon): void;
     /**
      * Establishes a connection to the backend using the supplied credentials.
      * Performs a health‑check ping first; if successful, it requests an authentication