@expressots/shared 3.0.0 → 4.0.0-preview.1

package/lib/cjs/types/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./config";
-export * from "./env";
-export * from "./interfaces";
-export * from "./utils";
+export * from "./config/index.js";
+export * from "./env/index.js";
+export * from "./interfaces/index.js";
+export * from "./utils/index.js";

package/lib/cjs/types/interfaces/application-express.interface.d.ts

@@ -1,7 +1,6 @@
 import { Server as HTTPServer } from "http";
-import { IConsoleMessage } from "./console.interface";
-import { Environment, IEnvironment } from "./environment.interface";
-import { RenderEngine } from "./render/render.types";
+import { IConsoleMessage } from "./console.interface.js";
+import { RenderEngine } from "./render/render.types.js";
 /**
  * Namespace for the Server Application.
  * @namespace Server
@@ -12,7 +11,6 @@ export declare namespace Server {
      * Interface for the WebServer application implementation.
      */
     interface IWebServer {
-        initEnvironment(environment: Environment, options?: IEnvironment): Promise<void>;
         listen(port: number | string, appInfo?: IConsoleMessage): Promise<IWebServerPublic>;
         setEngine<T extends RenderEngine.EngineOptions>(engine: RenderEngine.Engine, options?: T): Promise<void>;
     }
@@ -45,6 +43,13 @@ export declare namespace Server {
          * @public API
          */
         getHttpServer(): Promise<HTTPServer>;
+        /**
+         * Get the port the server is listening on.
+         * Useful for dynamic port assignment (port: 0) in testing scenarios.
+         * @returns The actual port number the server is bound to.
+         * @public API
+         */
+        getPort(): Promise<number>;
     }
 }
 export type IWebServer = Server.IWebServer;

package/lib/cjs/types/interfaces/console.interface.d.ts

@@ -5,4 +5,10 @@
 export interface IConsoleMessage {
     appName: string;
     appVersion: string;
+    apiVersions?: Array<string>;
+    /** CI environment detection info (for bootstrap logging) */
+    ciDetection?: {
+        detected: boolean;
+        platform?: string;
+    };
 }

package/lib/cjs/types/interfaces/index.d.ts

@@ -1,5 +1,5 @@
-export { RenderEngine } from "./render/render.types";
-export { IConsoleMessage } from "./console.interface";
-export { IExpressoMiddleware } from "./middleware.interface";
-export { Environment, IEnvironment, Env } from "./environment.interface";
-export { IWebServer, IWebServerBuilder, IWebServerConstructor, IWebServerPublic, Server, } from "./application-express.interface";
+export { RenderEngine } from "./render/render.types.js";
+export type { IConsoleMessage } from "./console.interface.js";
+export type { IExpressoMiddleware } from "./middleware.interface.js";
+export type { Environment, IEnvironment, Env } from "./environment.interface.js";
+export { IWebServer, IWebServerBuilder, IWebServerConstructor, IWebServerPublic, Server, } from "./application-express.interface.js";

package/lib/cjs/types/interfaces/render/render.types.d.ts

@@ -1,4 +1,4 @@
-import { Options } from "./ejs.types";
+import { Options } from "./ejs.types.js";
 /**
  * The Render namespace contains all the types and interfaces related to rendering views.
  * @namespace Render

package/lib/cjs/types/utils/compiler.d.ts

@@ -1,5 +1,5 @@
 import { Service } from "ts-node";
-import { ExpressoConfig } from "../config";
+import { ExpressoConfig } from "../config/index.js";
 export declare function printError(message: string, component: string): void;
 /**
  * Singleton compiler class

package/lib/cjs/types/utils/index.d.ts

@@ -1 +1 @@
-export { Compiler } from "./compiler";
+export { Compiler } from "./compiler.js";

package/lib/cjs/utils/index.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Compiler = void 0;
-var compiler_1 = require("./compiler");
-Object.defineProperty(exports, "Compiler", { enumerable: true, get: function () { return compiler_1.Compiler; } });
+var compiler_js_1 = require("./compiler.js");
+Object.defineProperty(exports, "Compiler", { enumerable: true, get: function () { return compiler_js_1.Compiler; } });

package/lib/esm/config/index.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/config/project-config.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/env/cli-options.js

@@ -0,0 +1,15 @@
+import { ENV_VAR_REGEX } from "./constants.js";
+/**
+ * Matches the options passed in the command line
+ * @param args - The arguments passed in the command line
+ * @returns The options passed in the command line
+ */
+export function optionMatcher(args) {
+    return args.reduce((previous, current) => {
+        const matches = current.match(ENV_VAR_REGEX);
+        if (matches) {
+            previous[matches[1]] = matches[2];
+        }
+        return previous;
+    }, {});
+}

package/lib/esm/env/constants.js

@@ -0,0 +1,10 @@
+/**
+ * LINE_REGEX is a regular expression that matches a line in a .env file.
+ * It is used to parse the content of the .env file.
+ */
+export const LINE_REGEX = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
+/**
+ * ENV_VAR_REGEX is a regular expression that matches an environment variable in the command line.
+ * It is used to parse the options passed in the command line.
+ */
+export const ENV_VAR_REGEX = /^dotenv_config_(encoding|path|debug|override|vaultEnvKey)=(.+)$/;

package/lib/esm/env/env-options.js

@@ -0,0 +1,19 @@
+/**
+ * The options for the dotenv configuration.
+ */
+export const OPTIONS = {};
+if (process.env.DOTENV_CONFIG_ENCODING != null) {
+    OPTIONS.encoding = process.env.DOTENV_CONFIG_ENCODING;
+}
+if (process.env.DOTENV_CONFIG_PATH != null) {
+    OPTIONS.path = process.env.DOTENV_CONFIG_PATH;
+}
+if (process.env.DOTENV_CONFIG_DEBUG != null) {
+    OPTIONS.debug = process.env.DOTENV_CONFIG_DEBUG === "true";
+}
+if (process.env.DOTENV_CONFIG_OVERRIDE != null) {
+    OPTIONS.override = process.env.DOTENV_CONFIG_OVERRIDE === "true";
+}
+if (process.env.DOTENV_CONFIG_DOTENV_KEY != null) {
+    OPTIONS.vaultEnvKey = process.env.DOTENV_CONFIG_DOTENV_KEY;
+}

package/lib/esm/env/environment.js

@@ -0,0 +1,304 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import fs from "fs";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+import { LINE_REGEX } from "./constants.js";
+import { log, LogLevel } from "../utils/logger.js";
+/**
+ * Module to parse the .env.vault file
+ * @param options - The configuration options
+ * @returns The parsed object
+ */
+function _parseVault(options) {
+    const vaultPath = _vaultPath(options);
+    const result = configDotenv({ path: vaultPath });
+    if (!result.parsed) {
+        const err = new Error(`MISSING_DATA: Cannot parse ${vaultPath} for an unknown reason`);
+        err.name = "MISSING_DATA";
+        throw err;
+    }
+    //DOTENV_KEY="dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=prod, // dotenv://:key_7890@dotenvx.com/vault/.env.vault?environment=prod"
+    const keys = _dotenvKey(options).split(",");
+    const length = keys.length;
+    let decrypted = "";
+    for (let i = 0; i < length; i++) {
+        try {
+            const key = keys[i].trim();
+            const attrs = _instructions(result, key);
+            decrypted = decrypt(attrs.ciphertext, attrs.key);
+            break;
+        }
+        catch (error) {
+            if (i + 1 >= length) {
+                throw error;
+            }
+        }
+    }
+    return parse(decrypted);
+}
+/**
+ * Module to verify and return the .env.vault file path
+ * @param options - The configuration options
+ * @returns The .env.vault file path
+ */
+function _vaultPath(options) {
+    let possibleVaultPath = null;
+    if (options && options.path && options.path.length > 0) {
+        if (Array.isArray(options.path)) {
+            for (const filepath of options.path) {
+                if (fs.existsSync(filepath)) {
+                    possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
+                }
+            }
+        }
+        else {
+            possibleVaultPath = options.path.endsWith(".vault") ? options.path : `${options.path}.vault`;
+        }
+    }
+    else {
+        possibleVaultPath = path.resolve(process.cwd(), ".env.vault");
+    }
+    if (fs.existsSync(possibleVaultPath)) {
+        return possibleVaultPath;
+    }
+    return null;
+}
+/**
+ * Module to verify and return the DOTENV_KEY vault key
+ * @param options - The configuration options
+ * @returns The DOTENV_KEY as a string
+ */
+function _dotenvKey(options) {
+    if (options && options.vaultEnvKey && options.vaultEnvKey.length > 0) {
+        return options.vaultEnvKey;
+    }
+    if (process.env.DOTENV_KEY && process.env.DOTENV_KEY.length > 0) {
+        return process.env.DOTENV_KEY;
+    }
+    return "";
+}
+/**
+ * Module to get instructions for decrypting the .env.vault file
+ * @param result -
+ * @param dotenvKey
+ * @returns
+ */
+function _instructions(result, dotenvKey) {
+    let uri = null;
+    try {
+        uri = new URL(dotenvKey);
+    }
+    catch (error) {
+        if (error.code === "ERR_INVALID_URL") {
+            const err = new Error("INVALID_DOTENV_KEY: Wrong format. Must be in valid uri format like dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=development");
+            err.code = "INVALID_DOTENV_KEY";
+            throw err;
+        }
+        throw error;
+    }
+    // Get decrypt key
+    const key = uri.password;
+    if (!key) {
+        const err = new Error("INVALID_DOTENV_KEY: Missing key part");
+        err.code = "INVALID_DOTENV_KEY";
+        throw err;
+    }
+    // Get environment
+    const environment = uri.searchParams.get("environment");
+    if (!environment) {
+        const err = new Error("INVALID_DOTENV_KEY: Missing environment part");
+        err.code = "INVALID_DOTENV_KEY";
+        throw err;
+    }
+    // Get ciphertext payload
+    const environmentKey = `DOTENV_VAULT_${environment.toUpperCase()}`;
+    const ciphertext = result.parsed[environmentKey]; // DOTENV_VAULT_PRODUCTION
+    if (!ciphertext) {
+        const err = new Error(`NOT_FOUND_DOTENV_ENVIRONMENT: Cannot locate environment ${environmentKey} in your .env.vault file.`);
+        err.code = "NOT_FOUND_DOTENV_ENVIRONMENT";
+        throw err;
+    }
+    return { ciphertext, key };
+}
+/**
+ * Module responsible to resolve home path
+ * @param envPath - The path to resolve
+ * @returns The resolved path
+ */
+function _resolveHome(envPath) {
+    return envPath[0] === "~" ? path.join(os.homedir(), envPath.slice(1)) : envPath;
+}
+/**
+ * Module to load environment variables from .env.vault file
+ * @param options - The configuration options
+ * @returns The parsed object
+ */
+export function _configVault(options) {
+    log("Loading env from encrypted .env.vault");
+    const parsed = _parseVault(options);
+    let processEnv = process.env;
+    if (options && options.envObject != null) {
+        processEnv = options.envObject;
+    }
+    populate(processEnv, parsed, options);
+    return { parsed };
+}
+/**
+ * Module to load environment variables from .env file
+ * @param options - The configuration options
+ * @returns The parsed object
+ * @public API
+ */
+export function config(options) {
+    if (_dotenvKey(options).length === 0) {
+        return configDotenv(options);
+    }
+    const vaultPath = _vaultPath(options);
+    if (!vaultPath) {
+        const expected = path.resolve(process.cwd(), ".env.vault");
+        log(`You set DOTENV_KEY but no .env.vault file was found (expected at ${expected}). Did you forget to build it?`, LogLevel.Warn);
+        return configDotenv(options);
+    }
+    return _configVault(options);
+}
+/**
+ * Module to load environment variables from .env file
+ * @param options - The configuration options
+ * @returns The parsed object
+ * @public API
+ */
+export function configDotenv(options) {
+    const dotenvPath = path.resolve(process.cwd(), String(options?.path ?? ".env"));
+    const encoding = (options.encoding ?? "utf8");
+    const debug = !!options.debug;
+    const paths = Array.isArray(options.path)
+        ? options.path.map(_resolveHome)
+        : [_resolveHome(dotenvPath)];
+    const parsed = {};
+    let lastError;
+    for (const envPath of paths) {
+        try {
+            const fileContent = fs.readFileSync(envPath, { encoding });
+            const parsedContent = parse(fileContent);
+            populate(process.env, parsedContent, options);
+        }
+        catch (error) {
+            lastError = error;
+            if (debug) {
+                log(`Failed to load ${envPath} file with error: ${error.message}`, LogLevel.Debug);
+            }
+        }
+    }
+    return { parsed, error: lastError };
+}
+/**
+ * Module to load environment variables from .env file
+ * @param envFile - The source of the .env file
+ * @returns The parsed object
+ * @public API
+ */
+export function parse(envFile) {
+    const obj = {};
+    const lines = envFile.toString().replace(/\r\n?/gm, "\n");
+    let match;
+    while ((match = LINE_REGEX.exec(lines)) != null) {
+        const key = match[1].trim();
+        let value = match[2]?.trim() ?? "";
+        if (["'", '"', "`"].includes(value[0])) {
+            value = value.slice(1, -1);
+        }
+        value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+        if (match[2]?.[0] === '"') {
+            value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r");
+        }
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * Decrypts a base64 encoded string
+ * @param encrypted - The base64 encoded string to decrypt
+ * @param keyStr - The key to use for decryption
+ * @returns The decrypted string
+ * @public API
+ */
+export function decrypt(encrypted, keyStr) {
+    const key = Buffer.from(keyStr.slice(-64), "hex");
+    let ciphertext = Buffer.from(encrypted, "base64");
+    const nonce = ciphertext.subarray(0, 12);
+    const authTag = ciphertext.subarray(-16);
+    ciphertext = ciphertext.subarray(12, -16);
+    try {
+        const aesgcm = crypto.createDecipheriv("aes-256-gcm", key, nonce);
+        aesgcm.setAuthTag(authTag);
+        return `${aesgcm.update(ciphertext)}${aesgcm.final()}`;
+    }
+    catch (error) {
+        const isRange = error instanceof RangeError;
+        const invalidKeyLength = error.message === "Invalid key length";
+        const decryptionFailed = error.message === "Unsupported state or unable to authenticate data";
+        if (isRange || invalidKeyLength) {
+            const err = new Error("INVALID_DOTENV_KEY: It must be 64 characters long (or more)");
+            err.name = "INVALID_DOTENV_KEY";
+            throw err;
+        }
+        else if (decryptionFailed) {
+            const err = new Error("DECRYPTION_FAILED: Please check your DOTENV_KEY");
+            err.name = "DECRYPTION_FAILED";
+            throw err;
+        }
+        else {
+            throw error;
+        }
+    }
+}
+/**
+ * Populates the environment with the given parsed object
+ * @param envObject - The object to populate the environment with (e.g. process.env)
+ * @param parsed - The parsed object
+ * @param options - The configuration options
+ * @public API
+ */
+export function populate(envObject, // Usually process.env
+parsed, options = {}) {
+    const debug = Boolean(options && options.debug);
+    const override = Boolean(options && options.override);
+    if (typeof parsed !== "object") {
+        const err = new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
+        err.name = "OBJECT_REQUIRED";
+        throw err;
+    }
+    // Set process.env (envObject)
+    for (const key of Object.keys(parsed)) {
+        const parsedValue = parsed[key];
+        // Decide whether to override existing env var or not
+        if (Object.prototype.hasOwnProperty.call(envObject, key)) {
+            if (override) {
+                envObject[key] = parsedValue;
+                if (debug) {
+                    log(`"${key}" was overwritten to "${parsedValue}"`, LogLevel.Debug);
+                }
+            }
+            else if (debug) {
+                log(`"${key}" was NOT overwritten (already exists)`, LogLevel.Debug);
+            }
+        }
+        else {
+            // Variable doesn't exist in process.env, so set it
+            envObject[key] = parsedValue;
+            if (debug) {
+                log(`"${key}" was set to "${parsedValue}"`, LogLevel.Debug);
+            }
+        }
+    }
+    // Final debug log to ensure variables are correctly populated
+    if (debug) {
+        console.log("Final process.env object:", envObject);
+    }
+}
+/**
+ * Test swap for private functions
+ */
+export { _parseVault, _vaultPath, _dotenvKey, _instructions, _resolveHome };

package/lib/esm/env/index.js

@@ -0,0 +1 @@
+export * from "./environment.js";

package/lib/esm/env/interfaces.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/index.mjs

@@ -0,0 +1,4 @@
+export * from "./config/index.js";
+export * from "./env/index.js";
+export * from "./interfaces/index.js";
+export * from "./utils/index.js";

package/lib/esm/interfaces/application-express.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/interfaces/console.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/interfaces/environment.interface.js

@@ -0,0 +1,19 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+/**
+ * The Environment namespace contains all the types and interfaces related to environment configuration.
+ * @namespace Environment
+ * @public API
+ */
+export var Env;
+(function (Env) {
+    /**
+     * Enum representing possible server environments.
+     * @public API
+     */
+    let ServerEnvironment;
+    (function (ServerEnvironment) {
+        ServerEnvironment["Development"] = "development";
+        ServerEnvironment["Production"] = "production";
+        ServerEnvironment["Remote"] = "remote";
+    })(ServerEnvironment = Env.ServerEnvironment || (Env.ServerEnvironment = {}));
+})(Env || (Env = {}));

package/lib/esm/interfaces/index.js

@@ -0,0 +1 @@
+export { RenderEngine } from "./render/render.types.js";

package/lib/esm/interfaces/middleware.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/interfaces/render/ejs.types.js

@@ -0,0 +1,2 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export {};

package/lib/esm/interfaces/render/render.types.js

@@ -0,0 +1,20 @@
+/**
+ * The Render namespace contains all the types and interfaces related to rendering views.
+ * @namespace Render
+ * @public API
+ */
+export var RenderEngine;
+(function (RenderEngine) {
+    /**
+     * The supported view engines.
+     * @enum {string} Engine - The supported view engines.
+     * @readonly - This enum is read-only.
+     * @public API
+     */
+    let Engine;
+    (function (Engine) {
+        Engine["HBS"] = "hbs";
+        Engine["EJS"] = "ejs";
+        Engine["PUG"] = "pug";
+    })(Engine = RenderEngine.Engine || (RenderEngine.Engine = {}));
+})(RenderEngine || (RenderEngine = {}));

package/lib/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/lib/esm/types/config/index.d.ts

@@ -0,0 +1 @@
+export { Pattern, ExpressoConfig } from "./project-config.js";

package/lib/esm/types/config/project-config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Enum representing different string patterns.
+ *
+ * - LOWER_CASE: Represents strings in all lowercase letters. E.g. "hello"
+ * - KEBAB_CASE: Represents strings separated by hyphens. E.g. "hello-world"
+ * - PASCAL_CASE: Represents strings where the first letter of each word is capitalized. E.g. "HelloWorld"
+ * - CAMEL_CASE: Represents strings where the first letter of the first word is lowercase and the first letter of subsequent words are capitalized. E.g. "helloWorld"
+ * @public API
+ */
+export declare const enum Pattern {
+    LOWER_CASE = "lowercase",
+    KEBAB_CASE = "kebab-case",
+    PASCAL_CASE = "PascalCase",
+    CAMEL_CASE = "camelCase"
+}
+/**
+ * The configuration object for the Expresso CLI.
+ * @property {Pattern} scaffoldPattern - The pattern to use when scaffolding files.
+ * @property {string} sourceRoot - The root directory for the source files.
+ * @property {boolean} opinionated - Whether or not to use the opinionated configuration.
+ * @property {IProviders} providers - Specific configuration for each provider added.
+ * @public API
+ */
+export interface ExpressoConfig {
+    scaffoldPattern: Pattern;
+    sourceRoot: string;
+    entryPoint: string;
+    opinionated: boolean;
+    scaffoldSchematics?: {
+        entity?: string;
+        controller?: string;
+        usecase?: string;
+        dto?: string;
+        module?: string;
+        provider?: string;
+        middleware?: string;
+        interceptor?: string;
+        event?: string;
+        handler?: string;
+        guard?: string;
+        config?: string;
+    };
+}

package/lib/esm/types/env/cli-options.d.ts

@@ -0,0 +1,7 @@
+import { IConfigOptions } from "./interfaces.js";
+/**
+ * Matches the options passed in the command line
+ * @param args - The arguments passed in the command line
+ * @returns The options passed in the command line
+ */
+export declare function optionMatcher(args: Array<string>): IConfigOptions;

package/lib/esm/types/env/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * LINE_REGEX is a regular expression that matches a line in a .env file.
+ * It is used to parse the content of the .env file.
+ */
+export declare const LINE_REGEX: RegExp;
+/**
+ * ENV_VAR_REGEX is a regular expression that matches an environment variable in the command line.
+ * It is used to parse the options passed in the command line.
+ */
+export declare const ENV_VAR_REGEX: RegExp;

package/lib/esm/types/env/env-options.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Module EnvOptions
+ * Responsible for setting the options for the dotenv configuration if provided otherwise it will use the default values.
+ */
+import { IConfigOptions } from "./interfaces.js";
+/**
+ * The options for the dotenv configuration.
+ */
+export declare const OPTIONS: IConfigOptions;