opticore-webapp-core 1.0.22 → 1.0.23

package/dist/index.cjs

@@ -546,7 +546,7 @@ var CLogLevel = {
 };
 
 // src/utils/parsing/parsingYaml.utils.ts
-var import_promises = require("fs/promises");
+var import_fs = require("fs");
 var import_opticore_http_response4 = require("opticore-http-response");
 var import_opticore_logger2 = require("opticore-logger");
 var import_opticore_translator4 = require("opticore-translator");
@@ -586,10 +586,21 @@ var YamlParsing = class {
   absolutPath() {
     return import_path2.default.join(process.cwd(), "src", "utils", "translations");
   }
-  async readFile(filePath) {
+  /**
+   * Reads and parses a YAML config file (relative to the process working directory) and RETURNS its content, so that
+   * it can be passed straight to a consumer:
+   *
+   *     new WebServer({ corsOriginOptions: yamlParsing.readFile(environment.corsOptions), ... })
+   *
+   * It used to parse the file and throw the result away (it returned `Promise<void>`), so such a call handed the
+   * consumer a Promise, and CORS silently ran with its defaults: any origin, no credentials.
+   *
+   * It is synchronous on purpose: a configuration is needed before the server starts. An unreadable or malformed
+   * file is logged and yields `{}`; callers that cannot run without a value must check for it.
+   */
+  readFile(filePath) {
     try {
-      const yamlContent = await (0, import_promises.readFile)(filePath, "utf-8");
-      await this.parsing(yamlContent);
+      return this.parsing((0, import_fs.readFileSync)(filePath, "utf-8"));
     } catch (error) {
       this.logger.error({
         message: error.message,
@@ -598,14 +609,50 @@ var YamlParsing = class {
         stackTrace: error.stack,
         httpCodeValue: import_opticore_http_response4.HttpStatusCode.NOT_ACCEPTABLE
       });
+      return {};
+    }
+  }
+  /**
+   * A YAML scalar as a typed value: `true` / `false` become booleans, `null` / `~` / empty become null,
+   * numbers become numbers, quoted text becomes the text inside the quotes, anything else the trimmed string.
+   *
+   * @param raw
+   * @private
+   */
+  scalar(raw) {
+    const value = (raw ?? "").trim();
+    if (value === "" || value === "~" || value === "null") return null;
+    if (value === "true") return true;
+    if (value === "false") return false;
+    if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+    if (value.length >= 2 && (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'"))) {
+      return value.slice(1, -1);
+    }
+    return value;
+  }
+  /**
+   * The value after `key:` — a scalar, or an inline list (`[a, b]`, `[]`).
+   *
+   * @param raw
+   * @private
+   */
+  value(raw) {
+    const value = (raw ?? "").replace(/\s+#.*$/, "").trim();
+    if (value.startsWith("[") && value.endsWith("]")) {
+      const inner = value.slice(1, -1).trim();
+      return inner === "" ? [] : inner.split(",").map((item) => this.scalar(item));
     }
+    return this.scalar(value);
   }
   /**
+   * Parses the supported YAML subset: `key: value` pairs (typed scalars), inline lists (`[a, b]`), block lists
+   * (`- item` lines under a key) and one level of nested `key: value` pairs. Full-line and trailing comments,
+   * and blank lines, are ignored.
    *
    * @param content
    * @private
    */
-  async parsing(content) {
+  parsing(content) {
     const result = {};
     const lines = content.split("\n");
     let currentKey = null;
@@ -613,15 +660,25 @@ var YamlParsing = class {
       if (!line.trim() || line.trim().startsWith("#")) {
         continue;
       }
+      const listItemMatch = line.match(/^\s*-\s+(.*)$/);
+      if (listItemMatch && currentKey) {
+        if (!Array.isArray(result[currentKey])) {
+          result[currentKey] = [];
+        }
+        result[currentKey].push(this.scalar(listItemMatch[1].replace(/\s+#.*$/, "")));
+        continue;
+      }
       const keyValueMatch = line.match(/^(\s*)([a-zA-Z0-9_]+):(?:\s*(.*))?$/);
       if (keyValueMatch) {
         const [, indent, key, value] = keyValueMatch;
         if (indent.length > 0 && currentKey) {
-          result[currentKey] = result[currentKey] || {};
-          result[currentKey][key] = value?.trim() || null;
+          if (result[currentKey] === null || typeof result[currentKey] !== "object" || Array.isArray(result[currentKey])) {
+            result[currentKey] = {};
+          }
+          result[currentKey][key] = this.value(value);
         } else {
           currentKey = key;
-          result[key] = value?.trim() || null;
+          result[key] = this.value(value);
         }
       } else {
         this.logger.error({
@@ -656,7 +713,7 @@ var import_node_process = __toESM(require("process"), 1);
 var import_chalk = __toESM(require("chalk"), 1);
 var import_ansi_colors = __toESM(require("ansi-colors"), 1);
 var import_path3 = __toESM(require("path"), 1);
-var import_fs = __toESM(require("fs"), 1);
+var import_fs2 = __toESM(require("fs"), 1);
 var import_opticore_translator5 = require("opticore-translator");
 var Utility = class {
   localLang;
@@ -733,8 +790,8 @@ var Utility = class {
    */
   getEnvFileLoading(filePath) {
     const fullPath = import_path3.default.resolve(import_node_process.default.cwd(), filePath);
-    if (import_fs.default.existsSync(fullPath)) {
-      const env = import_fs.default.readFileSync(fullPath, "utf-8");
+    if (import_fs2.default.existsSync(fullPath)) {
+      const env = import_fs2.default.readFileSync(fullPath, "utf-8");
       const lines = env.split("\n");
       lines.forEach((line) => {
         const match = line.match(/^([^#=]+)=([^#]+)$/);

package/dist/index.d.cts

@@ -135,8 +135,38 @@ declare class YamlParsing {
     private readonly localeLanguage;
     constructor(localeLanguage: string, environmentPath: any);
     absolutPath(): string;
-    readFile(filePath: string): Promise<void>;
     /**
+     * Reads and parses a YAML config file (relative to the process working directory) and RETURNS its content, so that
+     * it can be passed straight to a consumer:
+     *
+     *     new WebServer({ corsOriginOptions: yamlParsing.readFile(environment.corsOptions), ... })
+     *
+     * It used to parse the file and throw the result away (it returned `Promise<void>`), so such a call handed the
+     * consumer a Promise, and CORS silently ran with its defaults: any origin, no credentials.
+     *
+     * It is synchronous on purpose: a configuration is needed before the server starts. An unreadable or malformed
+     * file is logged and yields `{}`; callers that cannot run without a value must check for it.
+     */
+    readFile(filePath: string): Record<string, any>;
+    /**
+     * A YAML scalar as a typed value: `true` / `false` become booleans, `null` / `~` / empty become null,
+     * numbers become numbers, quoted text becomes the text inside the quotes, anything else the trimmed string.
+     *
+     * @param raw
+     * @private
+     */
+    private scalar;
+    /**
+     * The value after `key:` — a scalar, or an inline list (`[a, b]`, `[]`).
+     *
+     * @param raw
+     * @private
+     */
+    private value;
+    /**
+     * Parses the supported YAML subset: `key: value` pairs (typed scalars), inline lists (`[a, b]`), block lists
+     * (`- item` lines under a key) and one level of nested `key: value` pairs. Full-line and trailing comments,
+     * and blank lines, are ignored.
      *
      * @param content
      * @private

package/dist/index.d.ts

@@ -135,8 +135,38 @@ declare class YamlParsing {
     private readonly localeLanguage;
     constructor(localeLanguage: string, environmentPath: any);
     absolutPath(): string;
-    readFile(filePath: string): Promise<void>;
     /**
+     * Reads and parses a YAML config file (relative to the process working directory) and RETURNS its content, so that
+     * it can be passed straight to a consumer:
+     *
+     *     new WebServer({ corsOriginOptions: yamlParsing.readFile(environment.corsOptions), ... })
+     *
+     * It used to parse the file and throw the result away (it returned `Promise<void>`), so such a call handed the
+     * consumer a Promise, and CORS silently ran with its defaults: any origin, no credentials.
+     *
+     * It is synchronous on purpose: a configuration is needed before the server starts. An unreadable or malformed
+     * file is logged and yields `{}`; callers that cannot run without a value must check for it.
+     */
+    readFile(filePath: string): Record<string, any>;
+    /**
+     * A YAML scalar as a typed value: `true` / `false` become booleans, `null` / `~` / empty become null,
+     * numbers become numbers, quoted text becomes the text inside the quotes, anything else the trimmed string.
+     *
+     * @param raw
+     * @private
+     */
+    private scalar;
+    /**
+     * The value after `key:` — a scalar, or an inline list (`[a, b]`, `[]`).
+     *
+     * @param raw
+     * @private
+     */
+    private value;
+    /**
+     * Parses the supported YAML subset: `key: value` pairs (typed scalars), inline lists (`[a, b]`), block lists
+     * (`- item` lines under a key) and one level of nested `key: value` pairs. Full-line and trailing comments,
+     * and blank lines, are ignored.
      *
      * @param content
      * @private

package/dist/index.js

@@ -501,7 +501,7 @@ var CLogLevel = {
 };
 
 // src/utils/parsing/parsingYaml.utils.ts
-import { readFile } from "fs/promises";
+import { readFileSync } from "fs";
 import { HttpStatusCode as HttpStatusCode3 } from "opticore-http-response";
 import { LoggerCore as LoggerCore2 } from "opticore-logger";
 import { TranslationLoader as TranslationLoader4 } from "opticore-translator";
@@ -541,10 +541,21 @@ var YamlParsing = class {
   absolutPath() {
     return path2.join(process.cwd(), "src", "utils", "translations");
   }
-  async readFile(filePath) {
+  /**
+   * Reads and parses a YAML config file (relative to the process working directory) and RETURNS its content, so that
+   * it can be passed straight to a consumer:
+   *
+   *     new WebServer({ corsOriginOptions: yamlParsing.readFile(environment.corsOptions), ... })
+   *
+   * It used to parse the file and throw the result away (it returned `Promise<void>`), so such a call handed the
+   * consumer a Promise, and CORS silently ran with its defaults: any origin, no credentials.
+   *
+   * It is synchronous on purpose: a configuration is needed before the server starts. An unreadable or malformed
+   * file is logged and yields `{}`; callers that cannot run without a value must check for it.
+   */
+  readFile(filePath) {
     try {
-      const yamlContent = await readFile(filePath, "utf-8");
-      await this.parsing(yamlContent);
+      return this.parsing(readFileSync(filePath, "utf-8"));
     } catch (error) {
       this.logger.error({
         message: error.message,
@@ -553,14 +564,50 @@ var YamlParsing = class {
         stackTrace: error.stack,
         httpCodeValue: HttpStatusCode3.NOT_ACCEPTABLE
       });
+      return {};
+    }
+  }
+  /**
+   * A YAML scalar as a typed value: `true` / `false` become booleans, `null` / `~` / empty become null,
+   * numbers become numbers, quoted text becomes the text inside the quotes, anything else the trimmed string.
+   *
+   * @param raw
+   * @private
+   */
+  scalar(raw) {
+    const value = (raw ?? "").trim();
+    if (value === "" || value === "~" || value === "null") return null;
+    if (value === "true") return true;
+    if (value === "false") return false;
+    if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+    if (value.length >= 2 && (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'"))) {
+      return value.slice(1, -1);
+    }
+    return value;
+  }
+  /**
+   * The value after `key:` — a scalar, or an inline list (`[a, b]`, `[]`).
+   *
+   * @param raw
+   * @private
+   */
+  value(raw) {
+    const value = (raw ?? "").replace(/\s+#.*$/, "").trim();
+    if (value.startsWith("[") && value.endsWith("]")) {
+      const inner = value.slice(1, -1).trim();
+      return inner === "" ? [] : inner.split(",").map((item) => this.scalar(item));
     }
+    return this.scalar(value);
   }
   /**
+   * Parses the supported YAML subset: `key: value` pairs (typed scalars), inline lists (`[a, b]`), block lists
+   * (`- item` lines under a key) and one level of nested `key: value` pairs. Full-line and trailing comments,
+   * and blank lines, are ignored.
    *
    * @param content
    * @private
    */
-  async parsing(content) {
+  parsing(content) {
     const result = {};
     const lines = content.split("\n");
     let currentKey = null;
@@ -568,15 +615,25 @@ var YamlParsing = class {
       if (!line.trim() || line.trim().startsWith("#")) {
         continue;
       }
+      const listItemMatch = line.match(/^\s*-\s+(.*)$/);
+      if (listItemMatch && currentKey) {
+        if (!Array.isArray(result[currentKey])) {
+          result[currentKey] = [];
+        }
+        result[currentKey].push(this.scalar(listItemMatch[1].replace(/\s+#.*$/, "")));
+        continue;
+      }
       const keyValueMatch = line.match(/^(\s*)([a-zA-Z0-9_]+):(?:\s*(.*))?$/);
       if (keyValueMatch) {
         const [, indent, key, value] = keyValueMatch;
         if (indent.length > 0 && currentKey) {
-          result[currentKey] = result[currentKey] || {};
-          result[currentKey][key] = value?.trim() || null;
+          if (result[currentKey] === null || typeof result[currentKey] !== "object" || Array.isArray(result[currentKey])) {
+            result[currentKey] = {};
+          }
+          result[currentKey][key] = this.value(value);
         } else {
           currentKey = key;
-          result[key] = value?.trim() || null;
+          result[key] = this.value(value);
         }
       } else {
         this.logger.error({

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "opticore-webapp-core",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "description": "opticore Web Application core module",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node --test test/*.test.mjs",
     "build": "tsup"
   },
   "repository": {
@@ -30,11 +30,11 @@
     "dotenv": "^16.5.0",
     "mongodb": "^6.6.1",
     "mysql": "^2.18.1",
-    "opticore-catch-exception-error": "^1.0.30",
-    "opticore-env-access": "^1.0.25",
+    "opticore-catch-exception-error": "^1.0.31",
+    "opticore-env-access": "^1.0.27",
     "opticore-express": "^1.0.9",
-    "opticore-http-response": "^1.0.11",
-    "opticore-logger": "^1.0.33",
+    "opticore-http-response": "^1.0.12",
+    "opticore-logger": "^1.0.35",
     "opticore-translator": "^1.0.17",
     "pg": "^8.15.6"
   },

package/src/utils/parsing/parsingYaml.utils.ts

@@ -1,4 +1,4 @@
-import { readFile } from "fs/promises";
+import { readFileSync } from "fs";
 import { HttpStatusCode } from "opticore-http-response";
 import { ILoggerConfig, LoggerCore } from "opticore-logger";
 import { TranslationLoader } from "opticore-translator";
@@ -22,10 +22,21 @@ export class YamlParsing {
         return path.join(process.cwd(), "src", "utils", "translations");
     }
 
-    public async readFile(filePath: string): Promise<void> {
+    /**
+     * Reads and parses a YAML config file (relative to the process working directory) and RETURNS its content, so that
+     * it can be passed straight to a consumer:
+     *
+     *     new WebServer({ corsOriginOptions: yamlParsing.readFile(environment.corsOptions), ... })
+     *
+     * It used to parse the file and throw the result away (it returned `Promise<void>`), so such a call handed the
+     * consumer a Promise, and CORS silently ran with its defaults: any origin, no credentials.
+     *
+     * It is synchronous on purpose: a configuration is needed before the server starts. An unreadable or malformed
+     * file is logged and yields `{}`; callers that cannot run without a value must check for it.
+     */
+    public readFile(filePath: string): Record<string, any> {
         try {
-            const yamlContent: string = await readFile(filePath, "utf-8");
-            await this.parsing(yamlContent);
+            return this.parsing(readFileSync(filePath, "utf-8"));
         } catch (error: any) {
             this.logger.error({
                 message: error.message,
@@ -34,15 +45,53 @@ export class YamlParsing {
                 stackTrace: error.stack,
                 httpCodeValue: HttpStatusCode.NOT_ACCEPTABLE
             });
+            return {};
         }
     }
-    
+
     /**
+     * A YAML scalar as a typed value: `true` / `false` become booleans, `null` / `~` / empty become null,
+     * numbers become numbers, quoted text becomes the text inside the quotes, anything else the trimmed string.
+     *
+     * @param raw
+     * @private
+     */
+    private scalar(raw: string | undefined): any {
+        const value: string = (raw ?? "").trim();
+        if (value === "" || value === "~" || value === "null") return null;
+        if (value === "true") return true;
+        if (value === "false") return false;
+        if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+        if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+            return value.slice(1, -1);
+        }
+        return value;
+    }
+
+    /**
+     * The value after `key:` — a scalar, or an inline list (`[a, b]`, `[]`).
+     *
+     * @param raw
+     * @private
+     */
+    private value(raw: string | undefined): any {
+        const value: string = (raw ?? "").replace(/\s+#.*$/, "").trim();
+        if (value.startsWith("[") && value.endsWith("]")) {
+            const inner: string = value.slice(1, -1).trim();
+            return inner === "" ? [] : inner.split(",").map((item: string): any => this.scalar(item));
+        }
+        return this.scalar(value);
+    }
+
+    /**
+     * Parses the supported YAML subset: `key: value` pairs (typed scalars), inline lists (`[a, b]`), block lists
+     * (`- item` lines under a key) and one level of nested `key: value` pairs. Full-line and trailing comments,
+     * and blank lines, are ignored.
      *
      * @param content
      * @private
      */
-    private async parsing(content: string): Promise<Record<any, any>> {
+    private parsing(content: string): Record<any, any> {
         const result: Record<string, any> = {};
         const lines: string[] = content.split("\n");
         let currentKey: string | null = null;
@@ -53,16 +102,27 @@ export class YamlParsing {
                 continue;
             }
 
+            const listItemMatch: RegExpMatchArray | null = line.match(/^\s*-\s+(.*)$/);
+            if (listItemMatch && currentKey) {
+                if (!Array.isArray(result[currentKey])) {
+                    result[currentKey] = [];
+                }
+                result[currentKey].push(this.scalar(listItemMatch[1].replace(/\s+#.*$/, "")));
+                continue;
+            }
+
             const keyValueMatch: RegExpMatchArray | null = line.match(/^(\s*)([a-zA-Z0-9_]+):(?:\s*(.*))?$/);
             if (keyValueMatch) {
                 const [, indent, key, value] = keyValueMatch;
                 // Handle nested objects (simple one-level nesting)
                 if (indent.length > 0 && currentKey) {
-                    result[currentKey] = result[currentKey] || {};
-                    result[currentKey][key] = value?.trim() || null;
+                    if (result[currentKey] === null || typeof result[currentKey] !== "object" || Array.isArray(result[currentKey])) {
+                        result[currentKey] = {};
+                    }
+                    result[currentKey][key] = this.value(value);
                 } else {
                     currentKey = key;
-                    result[key] = value?.trim() || null;
+                    result[key] = this.value(value);
                 }
 
             } else {
@@ -78,4 +138,4 @@ export class YamlParsing {
 
         return result;
     }
-}
+}

package/test/regression.test.mjs

@@ -0,0 +1,76 @@
+// Regression test for YamlParsing.readFile — run with `npm run build && npm test`.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const entry = process.env.WEBAPP_CORE_DIST ?? path.join(packageRoot, "dist", "index.js");
+
+// opticore-logger fixes ./logs/app.log at import time and expects it to exist: run in a scratch directory.
+const run = (yaml) => {
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "yaml-parsing-"));
+    fs.mkdirSync(path.join(scratch, "logs"));
+    fs.writeFileSync(path.join(scratch, "logs", "app.log"), "");
+    fs.writeFileSync(path.join(scratch, ".env"), "DEFAULT_LOCAL_LANG=en\n");
+    if (yaml !== null) fs.writeFileSync(path.join(scratch, "config.yaml"), yaml);
+
+    const scenario = `
+        const { YamlParsing } = require(${JSON.stringify(entry)});
+        const log = console.log, error = console.error;
+        console.log = console.error = () => {};
+        const value = new YamlParsing("en", ${JSON.stringify(path.join(scratch, ".env"))}).readFile("config.yaml");
+        console.log = log; console.error = error;
+        process.stdout.write("RESULT:" + JSON.stringify({ isPromise: value instanceof Promise, value }));
+    `;
+    const output = execFileSync(process.execPath, ["-e", scenario], { cwd: scratch, encoding: "utf8" });
+    return JSON.parse(output.slice(output.indexOf("RESULT:") + 7));
+};
+
+test("readFile RETURNS the parsed content (it used to return a Promise<void>)", () => {
+    const { isPromise, value } = run("a: 1\n");
+    assert.equal(isPromise, false);
+    assert.deepEqual(value, { a: 1 });
+});
+
+test("scalars are typed: booleans, numbers, null, quoted text ('false' is no longer a truthy string)", () => {
+    const { value } = run([
+        "credentials: true", "flag: false", "maxAge: 600", "ratio: 1.5", "empty:", "nothing: null", "tilde: ~",
+        "text: hello world", "quoted: \"true\"", "single: 'x y'", "duration: 1d", "",
+    ].join("\n"));
+    assert.deepEqual(value, { credentials: true, flag: false, maxAge: 600, ratio: 1.5, empty: null, nothing: null, tilde: null, text: "hello world", quoted: "true", single: "x y", duration: "1d" });
+});
+
+test("inline lists and block lists are supported", () => {
+    const { value } = run([
+        "methods: [GET, POST, OPTIONS]", "none: []",
+        "origin:", "  - https://app.example.com", "  - http://localhost:3000   # dev", "",
+        "allowedHeaders:", "- Content-Type", "- X-Requested-With", "",
+    ].join("\n"));
+    assert.deepEqual(value, {
+        methods: ["GET", "POST", "OPTIONS"], none: [],
+        origin: ["https://app.example.com", "http://localhost:3000"],
+        allowedHeaders: ["Content-Type", "X-Requested-With"],
+    });
+});
+
+test("comments, blank lines and one level of nesting still work", () => {
+    const { value } = run(["# a comment", "", "server:", "  host: localhost", "  port: 4201", "name: app # trailing", ""].join("\n"));
+    assert.deepEqual(value, { server: { host: "localhost", port: 4201 }, name: "app" });
+});
+
+test("a missing file is reported and yields {} instead of undefined", () => {
+    const result = run(null);
+    assert.equal(result.isPromise, false);
+    assert.deepEqual(result.value, {});
+});
+
+test("the CORS use case: the result can be handed straight to cors()", () => {
+    const { value } = run(["origin:", "  - https://app.example.com", "methods: [GET, POST]", "credentials: true", "maxAge: 600", ""].join("\n"));
+    assert.equal(value.credentials, true);
+    assert.deepEqual(value.origin, ["https://app.example.com"]);
+    assert.equal(typeof value.maxAge, "number");
+});