@flancer32/teq-web 0.4.0 → 0.6.0

package/src/Back/Handler/Static/A/{FileService.js → FileService.mjs}

@@ -1,23 +1,36 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    fs: 'node_fs',
+    http2: 'node_http2',
+    path: 'node_path',
+    logger: 'Fl32_Web_Back_Logger$',
+    helpMime: 'Fl32_Web_Back_Helper_Mime$',
+    resolver: 'Fl32_Web_Back_Handler_Static_A_Resolver$',
+    fallback: 'Fl32_Web_Back_Handler_Static_A_Fallback$',
+});
+
 export default class Fl32_Web_Back_Handler_Static_A_FileService {
     /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
     /**
-     * @param {typeof import('node:fs')} fs
-     * @param {typeof import('node:http2')} http2
-     * @param {typeof import('node:path')} path
-     * @param {Fl32_Web_Back_Logger} logger
-     * @param {Fl32_Web_Back_Helper_Mime} helpMime
-     * @param {Fl32_Web_Back_Handler_Static_A_Resolver} resolver
-     * @param {Fl32_Web_Back_Handler_Static_A_Fallback} fallback
+     * @param {object} params
+     * @param {Fl32_Web_Node_Fs} params.fs
+     * @param {Fl32_Web_Node_Http2} params.http2
+     * @param {Fl32_Web_Node_Path} params.path
+     * @param {Fl32_Web_Back_Logger} params.logger
+     * @param {Fl32_Web_Back_Helper_Mime} params.helpMime
+     * @param {Fl32_Web_Back_Handler_Static_A_Resolver} params.resolver
+     * @param {Fl32_Web_Back_Handler_Static_A_Fallback} params.fallback
      */
     constructor(
         {
-            'node:fs': fs,
-            'node:http2': http2,
-            'node:path': path,
-            Fl32_Web_Back_Logger$: logger,
-            Fl32_Web_Back_Helper_Mime$: helpMime,
-            Fl32_Web_Back_Handler_Static_A_Resolver$: resolver,
-            Fl32_Web_Back_Handler_Static_A_Fallback$: fallback,
+            fs,
+            http2,
+            path,
+            logger,
+            helpMime,
+            resolver,
+            fallback,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */
@@ -26,10 +39,10 @@ export default class Fl32_Web_Back_Handler_Static_A_FileService {
         /**
          * Serve a file for given config and relative path.
          *
-         * @param {*} config
+         * @param {Fl32_Web_Back_Handler_Static_A_Config_Value} config
          * @param {string} rel
-         * @param {*} req
-         * @param {*} res
+         * @param {Fl32_Web_Node_Http_IncomingMessage|Fl32_Web_Node_Http2_ServerRequest} req
+         * @param {Fl32_Web_Back_Response_Target} res
          * @returns {Promise<boolean>} true if served
          */
         this.serve = async (config, rel, req, res) => {

package/src/Back/Handler/Static/A/{Registry.js → Registry.mjs}

@@ -1,24 +1,32 @@
+// @ts-check
+
+export const __deps__ = Object.freeze({
+    configFactory: 'Fl32_Web_Back_Handler_Static_A_Config$',
+    logger: 'Fl32_Web_Back_Logger$',
+});
+
 export default class Fl32_Web_Back_Handler_Static_A_Registry {
     /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
     /**
-     * @param {Fl32_Web_Back_Handler_Static_A_Config} configFactory
-     * @param {Fl32_Web_Back_Logger} logger
+     * @param {object} params
+     * @param {Fl32_Web_Back_Handler_Static_A_Config} params.configFactory
+     * @param {Fl32_Web_Back_Logger} params.logger
      */
     constructor(
         {
-            Fl32_Web_Back_Handler_Static_A_Config$: configFactory,
-            Fl32_Web_Back_Logger$: logger,
+            configFactory,
+            logger,
         }
     ) {
         /* eslint-enable jsdoc/check-param-names */
-        /** @type {Fl32_Web_Back_Dto_Handler_Source.Dto[]} */
+        /** @type {Fl32_Web_Back_Dto_Source[]} */
         let _configs = [];
 
         /**
          * Add configurations ensuring unique prefixes.
          * Existing entries are not modified.
          *
-         * @param {Fl32_Web_Back_Dto_Handler_Source.Dto[]} dtoList
+         * @param {Fl32_Web_Back_Dto_Source[]} dtoList
          */
         this.addConfigs = function (dtoList = []) {
             const list = dtoList.map(dto => configFactory.create(dto));
@@ -37,7 +45,7 @@ export default class Fl32_Web_Back_Handler_Static_A_Registry {
          * Find configuration by matching URL prefix.
          *
          * @param {string} url
-         * @returns {{config: *, rel: string}|null}
+         * @returns {Fl32_Web_Back_Handler_Static_A_Match|null}
          */
         this.find = function (url) {
             for (const cfg of _configs) {

package/src/Back/Handler/Static/A/{Resolver.js → Resolver.mjs}

@@ -1,17 +1,24 @@
+// @ts-check
+
 /**
  * Enforces allow‐list rules and security checks when resolving
  * a relative URL to an absolute filesystem path under a given root.
  */
+export const __deps__ = Object.freeze({
+    path: 'node_path',
+});
+
 export default class Fl32_Web_Back_Handler_Static_A_Resolver {
     /**
-     * @param {typeof import('node:path')} path
+     * @param {object} params
+     * @param {Fl32_Web_Node_Path} params.path
      */
-    constructor({'node:path': path}) {
+    constructor({path}) {
         /**
          * Resolve a filesystem path for given config and relative URL part.
          * Applies allow rules and prevents path traversal.
          *
-         * @param {{root: string, prefix: string, allow?: Record<string,string[]>}} config
+         * @param {Fl32_Web_Back_Handler_Static_A_Config_Value} config
          * @param {string} rel
          * @returns {string|null}
          * @throws {Error} On traversal or absolute rel paths.

package/src/Back/Handler/Static.mjs

@@ -0,0 +1,79 @@
+// @ts-check
+
+/**
+ * Universal static-file PROCESS handler.
+ *
+ * @implements Fl32_Web_Back_Api_Handler
+ */
+export const __deps__ = Object.freeze({
+    registry: 'Fl32_Web_Back_Handler_Static_A_Registry$',
+    fileService: 'Fl32_Web_Back_Handler_Static_A_FileService$',
+    respond: 'Fl32_Web_Back_Helper_Respond$',
+    logger: 'Fl32_Web_Back_Logger$',
+    dtoInfoFactory: 'Fl32_Web_Back_Dto_Info__Factory$',
+    STAGE: 'Fl32_Web_Back_Enum_Stage$',
+});
+
+export default class Fl32_Web_Back_Handler_Static {
+    /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+    /**
+     * @param {object} params
+     * @param {Fl32_Web_Back_Handler_Static_A_Registry} params.registry
+     * @param {Fl32_Web_Back_Handler_Static_A_FileService} params.fileService
+     * @param {Fl32_Web_Back_Helper_Respond} params.respond
+     * @param {Fl32_Web_Back_Logger} params.logger
+     * @param {Fl32_Web_Back_Dto_Info$Factory} params.dtoInfoFactory
+     * @param {Fl32_Web_Back_Enum_Stage} params.STAGE
+     */
+    constructor(
+        {
+            registry,
+            fileService,
+            respond,
+            logger,
+            dtoInfoFactory,
+            STAGE,
+        }
+    ) {
+        /* eslint-enable jsdoc/check-param-names */
+
+        const _info = dtoInfoFactory.create({
+            name: this.constructor.name,
+            stage: STAGE.PROCESS,
+        });
+
+        /**
+         * Initialize registry with provided sources.
+         *
+         * @param {{sources: Fl32_Web_Back_Dto_Source[]}} params
+         * @returns {Promise<void>}
+         */
+        this.init = async ({sources = []} = {}) => {
+            registry.addConfigs(sources);
+        };
+
+        /**
+         * Attempt to handle incoming request.
+         *
+         * @param {Fl32_Web_Back_Dto_RequestContext} context
+         * @returns {Promise<void>}
+         */
+        this.handle = async (context) => {
+            const req = context.request;
+            const res = context.response;
+            if (!respond.isWritable(res)) return;
+            const urlPath = decodeURIComponent(req.url.split('?')[0]);
+            const match = registry.find(urlPath);
+            if (!match) return;
+            const served = await fileService.serve(match.config, match.rel, req, res);
+            if (served) {
+                context.complete();
+            }
+        };
+
+        /**
+         * @returns {Fl32_Web_Back_Dto_Info}
+         */
+        this.getRegistrationInfo = () => _info;
+    }
+}

package/src/Back/Helper/Cast.mjs

@@ -0,0 +1,116 @@
+// @ts-check
+
+export default class Fl32_Web_Back_Helper_Cast {
+    constructor() {
+        /**
+         * Cast input data into an array. Ensures the result is always an array.
+         * Optionally casts each item using the provided itemCast function.
+         *
+         * @param {*} data - Input data to be cast to array.
+         * @param {function(*): *} [itemCast] - Optional function to cast each item.
+         * @returns {Array}
+         */
+        this.array = function (data, itemCast) {
+            let arr = [];
+
+            if (Array.isArray(data)) {
+                arr = data;
+            } else if (data !== null) {
+                arr = [data];
+            }
+
+            return (typeof itemCast === 'function')
+                ? arr.map(itemCast).filter(v => v !== undefined)
+                : arr;
+        };
+
+        /**
+         * Cast input data into decimal 'number' data type.
+         * @param {*} data
+         * @returns {number|undefined}
+         */
+        this.decimal = function (data) {
+            const res = Number.parseFloat(data);
+            return ((typeof res === 'number') && (!isNaN(res))) ? res : undefined;
+        };
+
+        /**
+         * Cast input data into a valid enumeration value.
+         * Supports case normalization (upper/lower).
+         * If both `upper` and `lower` are true, `upper` takes precedence.
+         *
+         * @param {*} data - The input to cast.
+         * @param {object} enu - Object whose values represent valid enum values.
+         * @param {object} [params] - Parameters object.
+         * @param {boolean} [params.lower] - Normalize input to lower case before comparison.
+         * @param {boolean} [params.upper] - Normalize input to upper case before comparison.
+         * @returns {string|undefined}
+         */
+        this.enum = function (data, enu, {lower, upper} = {}) {
+            let norm = data;
+
+            if (typeof data === 'string') {
+                if (upper) norm = data.toUpperCase();
+                else if (lower) norm = data.toLowerCase();
+            }
+
+            const values = Object.values(enu);
+            return values.includes(norm) ? norm : undefined;
+        };
+
+        /**
+         * Cast input data into integer 'number' data type.
+         * @param {*} data - Input data to be cast to integer.
+         * @returns {number|undefined}
+         */
+        this.int = function (data) {
+            const norm = (typeof data === 'string') ? data.trim() : data;
+            const res = Number.parseInt(norm);
+            return ((typeof res === 'number') && (!isNaN(res))) ? res : undefined;
+        };
+
+        /**
+         * Cast input data into 'string' data type.
+         * @param {*} data - Input data to be cast to string.
+         * @returns {string|undefined}
+         */
+        this.string = function (data) {
+            if (typeof data === 'string') {
+                return data;
+            } else if (typeof data === 'number') {
+                return String(data);
+            } else if (typeof data === 'boolean') {
+                return (data) ? 'true' : 'false';
+            }
+            return undefined;
+        };
+
+        /**
+         * Cast an object to a map with string keys and array-of-string values.
+         * Throws error on invalid structure or values.
+         *
+         * @param {*} data - Raw input to cast.
+         * @returns {Record<string, string[]>}
+         */
+        this.stringArrayMap = function (data) {
+            if (data === undefined) return {};
+            if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+                throw new Error('Invalid value for allow');
+            }
+            const res = {};
+            for (const [key, arr] of Object.entries(data)) {
+                if (!Array.isArray(arr)) throw new Error(`Invalid allow list for ${key}`);
+                const k = this.string(key);
+                if (!k) throw new Error('Invalid allow key');
+                const items = [];
+                for (const item of arr) {
+                    const val = this.string(item);
+                    if (!val) throw new Error(`Invalid allow list for ${k}`);
+                    items.push(val);
+                }
+                res[k] = items;
+            }
+            return res;
+        };
+    }
+}

package/src/Back/Helper/{Mime.js → Mime.mjs}

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * MIME type helper with built-in mapping for common file extensions.
  * Can be replaced or extended by the application via the DI container.

package/src/Back/Helper/Order/Kahn.mjs

@@ -0,0 +1,69 @@
+// @ts-check
+
+/**
+ * Sorts named handlers by relative `before` / `after` constraints using Kahn's algorithm.
+ */
+export default class Fl32_Web_Back_Helper_Order_Kahn {
+    constructor() {
+        /**
+         * Topologically sorts handlers with `name`, `before`, `after` fields.
+         *
+         * @param {Fl32_Web_Back_Api_Handler[]} handlers - Handlers to sort.
+         * @returns {Fl32_Web_Back_Api_Handler[]} - Sorted list.
+         * @throws {Error} - If circular dependency is detected.
+         */
+        this.sort = function (handlers) {
+            const nameToHandler = new Map();
+            const graph = new Map(); // name => Set of downstream nodes
+            const inDegree = new Map(); // name => number of incoming edges
+
+            // Initialize maps
+            for (const h of handlers) {
+                const info = h.getRegistrationInfo();
+                const name = info.name;
+                nameToHandler.set(name, h);
+                graph.set(name, new Set());
+                inDegree.set(name, 0);
+            }
+
+            // Build graph
+            for (const h of handlers) {
+                const {name, after = [], before = []} = h.getRegistrationInfo();
+
+                for (const dep of after) {
+                    if (!graph.has(dep)) continue;
+                    graph.get(dep).add(name);
+                    inDegree.set(name, inDegree.get(name) + 1);
+                }
+
+                for (const dep of before) {
+                    if (!graph.has(dep)) continue;
+                    graph.get(name).add(dep);
+                    inDegree.set(dep, inDegree.get(dep) + 1);
+                }
+            }
+
+            // Kahn's algorithm
+            const queue = [];
+            for (const [name, count] of inDegree.entries()) {
+                if (count === 0) queue.push(name);
+            }
+
+            const sorted = [];
+            while (queue.length > 0) {
+                const name = queue.shift();
+                sorted.push(nameToHandler.get(name));
+                for (const neighbor of graph.get(name)) {
+                    inDegree.set(neighbor, inDegree.get(neighbor) - 1);
+                    if (inDegree.get(neighbor) === 0) queue.push(neighbor);
+                }
+            }
+
+            if (sorted.length !== handlers.length) {
+                throw new Error('Circular dependency detected among handlers');
+            }
+
+            return sorted;
+        };
+    }
+}

package/src/Back/Helper/{Respond.js → Respond.mjs}

@@ -1,11 +1,18 @@
+// @ts-check
+
 /* eslint-disable jsdoc/require-param-description,jsdoc/check-param-names */
+export const __deps__ = Object.freeze({
+    http2: 'node_http2',
+});
+
 export default class Fl32_Web_Back_Helper_Respond {
     /**
-     * @param {typeof import('node:http2')} http2
+     * @param {object} params
+     * @param {Fl32_Web_Node_Http2} params.http2
      */
     constructor(
         {
-            'node:http2': http2,
+            http2,
         }
     ) {
         // VARS
@@ -36,9 +43,9 @@ export default class Fl32_Web_Back_Helper_Respond {
          * Sends an HTTP response with a given status code.
          *
          * @param {object} params
-         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} params.res - HTTP response object.
-         * @param {{[key: string]: string}} [params.headers={}] - Custom headers.
-         * @param {string|object} [params.body=''] - Response body.
+         * @param {Fl32_Web_Back_Response_Target} params.res - HTTP response object.
+         * @param {Fl32_Web_Back_Response_Headers} [params.headers={}] - Custom headers.
+         * @param {Fl32_Web_Back_Response_Body} [params.body=''] - Response body.
          * @param {number} status - HTTP status code.
          * @returns {boolean} - `true` if response was sent, `false` if headers were already sent.
          */
@@ -145,11 +152,11 @@ export default class Fl32_Web_Back_Helper_Respond {
 
         /**
          * Checks if the response is writable and not yet sent.
-         * @param {module:http.ServerResponse|module:http2.Http2ServerResponse} res
+         * @param {Fl32_Web_Back_Response_Target} res
          * @returns {boolean}
          */
         this.isWritable = function (res) {
             return !res.headersSent && !res.writableEnded;
         };
     }
-}
+}

package/src/Back/Logger.mjs

@@ -0,0 +1,57 @@
+// @ts-check
+
+/**
+ * Simple logger implementation that delegates to the native console.
+ */
+export default class Fl32_Web_Back_Logger {
+    constructor() {
+        /**
+         * Logs an error message.
+         * @param {...any} args - The error message or data.
+         */
+        this.error = function (...args) {
+            console.error('[ERROR]', ...args);
+        };
+
+        /**
+         * Logs a warning message.
+         * @param {...any} args - The warning message or data.
+         */
+        this.warn = function (...args) {
+            console.warn('[WARN]', ...args);
+        };
+
+        /**
+         * Logs an informational message.
+         * @param {...any} args - The informational message or data.
+         */
+        this.info = function (...args) {
+            console.info('[INFO]', ...args);
+        };
+
+        /**
+         * Logs a debug message.
+         * @param {...any} args - The debug message or data.
+         */
+        this.debug = function (...args) {
+            console.debug('[DEBUG]', ...args);
+        };
+
+        /**
+         * Logs a trace message.
+         * @param {...any} args - The trace message or data.
+         */
+        this.trace = function (...args) {
+            console.trace('[TRACE]', ...args);
+        };
+
+        /**
+         * Logs an exception with optional additional context.
+         * @param {Error} exception - The exception to log.
+         * @param {...any} context - Additional context or metadata.
+         */
+        this.exception = function (exception, ...context) {
+            console.error('[EXCEPTION]', exception.stack || exception.toString(), ...context);
+        };
+    }
+}