@expressots/shared 3.0.0 → 4.0.0-preview.1

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

@@ -0,0 +1,83 @@
+import { IConfigOptions, IConfigOutput, IEnvObject } from "./interfaces.js";
+/**
+ * Module to parse the .env.vault file
+ * @param options - The configuration options
+ * @returns The parsed object
+ */
+declare function _parseVault(options: IConfigOptions): IEnvObject;
+/**
+ * Module to verify and return the .env.vault file path
+ * @param options - The configuration options
+ * @returns The .env.vault file path
+ */
+declare function _vaultPath(options: any): any;
+/**
+ * Module to verify and return the DOTENV_KEY vault key
+ * @param options - The configuration options
+ * @returns The DOTENV_KEY as a string
+ */
+declare function _dotenvKey(options?: IConfigOptions): string;
+/**
+ * Module to get instructions for decrypting the .env.vault file
+ * @param result -
+ * @param dotenvKey
+ * @returns
+ */
+declare function _instructions(result: IConfigOutput, dotenvKey: string): {
+    ciphertext: string;
+    key: any;
+};
+/**
+ * Module responsible to resolve home path
+ * @param envPath - The path to resolve
+ * @returns The resolved path
+ */
+declare function _resolveHome(envPath: string): string;
+/**
+ * Module to load environment variables from .env.vault file
+ * @param options - The configuration options
+ * @returns The parsed object
+ */
+export declare function _configVault(options: IConfigOptions): IConfigOutput;
+/**
+ * Module to load environment variables from .env file
+ * @param options - The configuration options
+ * @returns The parsed object
+ * @public API
+ */
+export declare function config(options?: IConfigOptions): IConfigOutput;
+/**
+ * Module to load environment variables from .env file
+ * @param options - The configuration options
+ * @returns The parsed object
+ * @public API
+ */
+export declare function configDotenv(options?: IConfigOptions): IConfigOutput;
+/**
+ * Module to load environment variables from .env file
+ * @param envFile - The source of the .env file
+ * @returns The parsed object
+ * @public API
+ */
+export declare function parse(envFile: Buffer | string): Record<string, string>;
+/**
+ * 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 declare function decrypt(encrypted: string, keyStr: string): string;
+/**
+ * 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 declare function populate(envObject: IEnvObject, // Usually process.env
+parsed: IEnvObject, options?: IConfigOptions): void;
+/**
+ * Test swap for private functions
+ */
+export { _parseVault, _vaultPath, _dotenvKey, _instructions, _resolveHome };

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

@@ -0,0 +1,2 @@
+export { IEnvObject, IConfigOptions, IConfigOutput } from "./interfaces.js";
+export * from "./environment.js";

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

@@ -0,0 +1,71 @@
+/**
+ * Interface for config options
+ * @public API
+ */
+export interface IConfigOptions {
+    /**
+     * Default: `path.resolve(process.cwd(), '.env')`
+     *
+     * Specify a custom path if your file containing environment variables is located elsewhere.
+     * Can also be an array of strings, specifying multiple paths.
+     *
+     * example: `require('dotenv').config({ path: '/custom/path/to/.env' })`
+     * example: `require('dotenv').config({ path: ['/path/to/first.env', '/path/to/second.env'] })`
+     */
+    path?: string | Array<string> | URL;
+    /**
+     * Default: `utf8`
+     *
+     * Specify the encoding of your file containing environment variables.
+     *
+     * example: `require('dotenv').config({ encoding: 'latin1' })`
+     */
+    encoding?: string;
+    /**
+     * Default: `false`
+     *
+     * Turn on logging to help debug why certain keys or values are not being set as you expect.
+     *
+     * example: `require('dotenv').config({ debug: process.env.DEBUG })`
+     */
+    debug?: boolean;
+    /**
+     * Default: `false`
+     *
+     * Override any environment variables that have already been set on your machine with values from your .env file.
+     *
+     * example: `require('dotenv').config({ override: true })`
+     */
+    override?: boolean;
+    /**
+     * Default: `process.env`
+     *
+     * Specify an object to write your secrets to. Defaults to process.env environment variables.
+     *
+     * example: `const processEnv = {}; require('dotenv').config({ processEnv: processEnv })`
+     */
+    envObject?: IEnvObject;
+    /**
+     * Default: `undefined`
+     *
+     * Pass the DOTENV_KEY directly to config options. Defaults to looking for process.env.DOTENV_KEY environment variable. Note this only applies to decrypting .env.vault files. If passed as null or undefined, or not passed at all, dotenv falls back to its traditional job of parsing a .env file.
+     *
+     * example: `require('dotenv').config({ DOTENV_KEY: 'dotenv://:key_1234…@dotenvx.com/vault/.env.vault?environment=production' })`
+     */
+    vaultEnvKey?: string;
+}
+/**
+ * Interface for environment variables
+ * @public API
+ */
+export interface IEnvObject {
+    [name: string]: string;
+}
+/**
+ * Interface for dotenv parse output
+ * @public API
+ */
+export interface IConfigOutput {
+    error?: Error;
+    parsed?: IEnvObject;
+}

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

@@ -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/types/interfaces/application-express.interface.d.ts

@@ -0,0 +1,58 @@
+import { Server as HTTPServer } from "http";
+import { IConsoleMessage } from "./console.interface.js";
+import { RenderEngine } from "./render/render.types.js";
+/**
+ * Namespace for the Server Application.
+ * @namespace Server
+ * @public API
+ */
+export declare namespace Server {
+    /**
+     * Interface for the WebServer application implementation.
+     */
+    interface IWebServer {
+        listen(port: number | string, appInfo?: IConsoleMessage): Promise<IWebServerPublic>;
+        setEngine<T extends RenderEngine.EngineOptions>(engine: RenderEngine.Engine, options?: T): Promise<void>;
+    }
+    /**
+     * Constructor type for IWebServer.
+     */
+    interface IWebServerConstructor<T extends IWebServer> {
+        new (): T;
+    }
+    /**
+     * Interface for the WebServerBuilder.
+     * @public API
+     */
+    interface IWebServerBuilder {
+        /**
+         * Start listening on the given port.
+         * @param port - The port number to listen on.
+         * @param consoleMessage - Optional App info message to display on startup.
+         */
+        listen(port: number | string, consoleMessage?: IConsoleMessage): Promise<IWebServerPublic>;
+    }
+    /**
+     * Public Interface for the WebServer application.
+     * @public API
+     */
+    interface IWebServerPublic {
+        /**
+         * Get the underlying HTTP server. (default: Express.js)
+         * @returns The underlying HTTP server after initialization.
+         * @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;
+export type IWebServerConstructor<T extends IWebServer> = Server.IWebServerConstructor<T>;
+export type IWebServerBuilder = Server.IWebServerBuilder;
+export type IWebServerPublic = Server.IWebServerPublic;

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

@@ -0,0 +1,14 @@
+/**
+ * Interface representing application message details for console output.
+ * @public API
+ */
+export interface IConsoleMessage {
+    appName: string;
+    appVersion: string;
+    apiVersions?: Array<string>;
+    /** CI environment detection info (for bootstrap logging) */
+    ciDetection?: {
+        detected: boolean;
+        platform?: string;
+    };
+}

package/lib/esm/types/interfaces/environment.interface.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Environment namespace contains all the types and interfaces related to environment configuration.
+ * @namespace Environment
+ * @public API
+ */
+export declare namespace Env {
+    /**
+     * Enum representing possible server environments.
+     * @public API
+     */
+    enum ServerEnvironment {
+        Development = "development",
+        Production = "production",
+        Remote = "remote"
+    }
+    /**
+     * Type representing possible server environments.
+     */
+    type TypeServerEnvironment = "development" | "production" | "remote";
+    /**
+     * Interface for environment configuration options.
+     * @public API
+     */
+    interface IEnvironment {
+        env: {
+            development?: string;
+            production?: string;
+        };
+    }
+    /**
+     * Type representing possible server environments.
+     * @public API
+     */
+    type Environment = ServerEnvironment | TypeServerEnvironment | undefined;
+}
+export type Environment = Env.Environment;
+export type IEnvironment = Env.IEnvironment;

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

@@ -0,0 +1,5 @@
+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/esm/types/interfaces/middleware.interface.d.ts

@@ -0,0 +1,7 @@
+import { Request, Response, NextFunction } from "express";
+/**
+ * ExpressoTS Class middleware interface.
+ */
+export interface IExpressoMiddleware {
+    use(req: Request, res: Response, next: NextFunction): Promise<void> | void;
+}

package/lib/esm/types/interfaces/render/ejs.types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * An object where {@link filename} is the final parsed path or {@link template} is the content of the included template
+ */
+export type IncluderResult = {
+    filename: string;
+    template?: never;
+} | {
+    template: string;
+    filename?: never;
+};
+/**
+ * @param originalPath the path as it appears in the include statement
+ * @param parsedPath the previously resolved path
+ *
+ * @return An {@link IncluderResult} object containing the filename or template data.
+ */
+type IncluderCallback = (originalPath: string, parsedPath: string) => IncluderResult;
+/**
+ * Escapes a string using HTML/XML escaping rules.
+ *
+ * Returns the empty string for `null` or `undefined`.
+ *
+ * @param markup Input string
+ * @return Escaped string
+ */
+type EscapeCallback = (markup?: any) => string;
+export interface Options {
+    /**
+     * Log the generated JavaScript source for the EJS template to the console.
+     *
+     * @default false
+     */
+    debug?: boolean | undefined;
+    /**
+     * Include additional runtime debugging information in generated template
+     * functions.
+     *
+     * @default true
+     */
+    compileDebug?: boolean | undefined;
+    /**
+     * Whether or not to use `with () {}` construct in the generated template
+     * functions. If set to `false`, data is still accessible through the object
+     * whose name is specified by `ejs.localsName` (defaults to `locals`).
+     *
+     * @default true
+     */
+    _with?: boolean | undefined;
+    /**
+     * Whether to run in strict mode or not.
+     * Enforces `_with=false`.
+     *
+     * @default false
+     */
+    strict?: boolean | undefined;
+    /**
+     * An array of local variables that are always destructured from `localsName`,
+     * available even in strict mode.
+     *
+     * @default []
+     */
+    destructuredLocals?: Array<string> | undefined;
+    /**
+     * Remove all safe-to-remove whitespace, including leading and trailing
+     * whitespace. It also enables a safer version of `-%>` line slurping for all
+     * scriptlet tags (it does not strip new lines of tags in the middle of a
+     * line).
+     *
+     * @default false
+     */
+    rmWhitespace?: boolean | undefined;
+    /**
+     * Whether or not to compile a `ClientFunction` that can be rendered
+     * in the browser without depending on ejs.js. Otherwise, a `TemplateFunction`
+     * will be compiled.
+     *
+     * @default false
+     */
+    client?: boolean | undefined;
+    /**
+     * The escaping function used with `<%=` construct. It is used in rendering
+     * and is `.toString()`ed in the generation of client functions.
+     *
+     * @default ejs.escapeXML
+     */
+    escape?: EscapeCallback | undefined;
+    /**
+     * The filename of the template. Required for inclusion and caching unless
+     * you are using `renderFile`. Also used for error reporting.
+     *
+     * @default undefined
+     */
+    filename?: string | undefined;
+    /**
+     * The path to templates root(s). When this is set, absolute paths for includes
+     * (/filename.ejs) will be relative to the templates root(s).
+     *
+     * @default undefined
+     */
+    root?: Array<string> | string | undefined;
+    /**
+     * The opening delimiter for all statements. This allows you to clearly delinate
+     * the difference between template code and existing delimiters. (It is recommended
+     * to synchronize this with the closeDelimiter property.)
+     *
+     * @default ejs.openDelimiter
+     */
+    openDelimiter?: string | undefined;
+    /**
+     * The closing delimiter for all statements. This allows to to clearly delinate
+     * the difference between template code and existing delimiters. (It is recommended
+     * to synchronize this with the openDelimiter property.)
+     *
+     * @default ejs.closeDelimiter
+     */
+    closeDelimiter?: string | undefined;
+    /**
+     * Character to use with angle brackets for open/close
+     * @default '%'
+     */
+    delimiter?: string | undefined;
+    /**
+     * Whether or not to enable caching of template functions. Beware that
+     * the options of compilation are not checked as being the same, so
+     * special handling is required if, for example, you want to cache client
+     * and regular functions of the same file.
+     *
+     * Requires `filename` to be set. Only works with rendering function.
+     *
+     * @default false
+     */
+    cache?: boolean | undefined;
+    /**
+     * The Object to which `this` is set during rendering.
+     *
+     * @default this
+     */
+    context?: any;
+    /**
+     * Whether or not to create an async function instead of a regular function.
+     * This requires language support.
+     *
+     * @default false
+     */
+    async?: boolean | undefined;
+    /**
+     * Make sure to set this to 'false' in order to skip UglifyJS parsing,
+     * when using ES6 features (`const`, etc) as UglifyJS doesn't understand them.
+     * @default true
+     */
+    beautify?: boolean | undefined;
+    /**
+     * Name to use for the object storing local variables when not using `with` or destructuring.
+     *
+     * @default ejs.localsName
+     */
+    localsName?: string | undefined;
+    /** Set to a string (e.g., 'echo' or 'print') for a function to print output inside scriptlet tags. */
+    outputFunctionName?: string | undefined;
+    /**
+     * An array of paths to use when resolving includes with relative paths
+     */
+    views?: Array<string> | undefined;
+    /**
+     * Custom function to handle EJS includes
+     */
+    includer?: IncluderCallback;
+}
+export {};

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

@@ -0,0 +1,71 @@
+import { Options } from "./ejs.types.js";
+/**
+ * The Render namespace contains all the types and interfaces related to rendering views.
+ * @namespace Render
+ * @public API
+ */
+export declare namespace RenderEngine {
+    /**
+     * Ejs options
+     * @typedef {Object} EjsOptions
+     * @property {string | Array<string>} viewsDir - The path to the views folder
+     * @property {string} viewEngine - The view engine
+     * @property {ejs.Options} [serverOptions] - The server options
+     * @public API
+     */
+    type EjsOptions = {
+        viewsDir?: string | Array<string>;
+        viewEngine?: string;
+        serverOptions?: Options;
+    };
+    /**
+     * Handlebars options
+     * @typedef {Object} HandlebarsOptions
+     * @property {string} viewsDir - The path to the views folder
+     * @property {string} viewEngine - The view engine to be used
+     * @property {ConfigOptions} [serverOptions] - The server options
+     * @public API
+     */
+    type HandlebarsOptions = {
+        viewEngine?: string;
+        viewsDir?: string;
+        partialsDir?: string;
+    };
+    /**
+     * Pug options
+     * @typedef {Object} PugOptions
+     * @property {string} viewEngine - The view engine to be used
+     * @property {string} viewsDir - The path to the views folder
+     * @public API
+     */
+    type PugOptions = {
+        viewEngine?: string;
+        viewsDir?: string;
+    };
+    /**
+     * The configuration options for the view engine.
+     * @typedef {HandlebarsOptions | EjsOptions | PugOptions} RenderOptions
+     * @public API
+     */
+    type RenderOptions = {
+        engine: Engine;
+        options?: EngineOptions;
+    };
+    /**
+     * The supported view engines.
+     * @enum {string} Engine - The supported view engines.
+     * @readonly - This enum is read-only.
+     * @public API
+     */
+    enum Engine {
+        HBS = "hbs",
+        EJS = "ejs",
+        PUG = "pug"
+    }
+    /**
+     * The configuration options for the view engine.
+     * @typedef {HandlebarsOptions | EjsOptions} EngineOptions
+     * @public API
+     */
+    type EngineOptions = HandlebarsOptions | EjsOptions | PugOptions;
+}

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

@@ -0,0 +1,17 @@
+import { Service } from "ts-node";
+import { ExpressoConfig } from "../config/index.js";
+export declare function printError(message: string, component: string): void;
+/**
+ * Singleton compiler class
+ */
+export declare class Compiler {
+    private static instance;
+    private constructor();
+    static get Instance(): Compiler;
+    getService(): Promise<Service>;
+    static interopRequireDefault(obj: any): {
+        default: any;
+    };
+    static findConfig(dir: string): Promise<string>;
+    static loadConfig(): Promise<ExpressoConfig>;
+}

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

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

package/lib/esm/types/utils/logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Logger utility for dotenv
+ */
+export declare enum LogLevel {
+    Info = "info",
+    Warn = "warn",
+    Debug = "debug"
+}
+/**
+ * Log a message
+ * @param message - The message to log
+ * @param logLevel - The log level. Defaults to LogLevel.Info
+ */
+export declare function log(message: string, logLevel?: LogLevel): void;
+export declare function printError(message: string, component: string): void;
+export declare function printSuccess(message: string, component: string): void;
+export declare function printWarning(message: string, component?: string): void;
+export declare function printGenerateError(schematic: string, file: string): Promise<void>;
+export declare function printGenerateSuccess(schematic: string, file: string): Promise<void>;

package/lib/esm/utils/compiler.js

@@ -0,0 +1,69 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { existsSync } from "node:fs";
+import path from "path";
+import chalk from "chalk";
+export function printError(message, component) {
+    console.error(chalk.red(`${message}:`, chalk.bold(chalk.white(`[${component}] ❌`))));
+}
+/**
+ * The path to the expressots.config.ts file
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const EXPRESSOTS_CONFIG = path.join(process.cwd(), "expressots.config.ts");
+/**
+ * The config object
+ */
+let globalConfigObject = null;
+/**
+ * The ts-node register options
+ */
+const regOpt = {
+    compilerOptions: {
+        module: "commonjs",
+    },
+    moduleTypes: {
+        "**": "cjs",
+    },
+};
+/**
+ * Singleton compiler class
+ */
+export class Compiler {
+    static instance;
+    constructor() { }
+    static get Instance() {
+        if (!Compiler.instance) {
+            Compiler.instance = new Compiler();
+        }
+        return Compiler.instance;
+    }
+    async getService() {
+        const tsnode = await import("ts-node");
+        const compiler = tsnode.register(regOpt);
+        return compiler;
+    }
+    static interopRequireDefault(obj) {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const module = require(obj);
+        return module && module.__esModule ? module : { default: module };
+    }
+    static async findConfig(dir) {
+        const configPath = path.join(dir, "expressots.config.ts");
+        const exists = existsSync(configPath);
+        if (exists)
+            return configPath;
+        const parentDir = path.join(dir, "..");
+        if (parentDir === dir) {
+            printError("No config file found!", "expressots.config.ts");
+            process.exit(1);
+        }
+        return Compiler.findConfig(parentDir);
+    }
+    static async loadConfig() {
+        const compiler = await Compiler.Instance.getService();
+        compiler.enabled(true);
+        globalConfigObject = Compiler.interopRequireDefault(await Compiler.findConfig(process.cwd()));
+        compiler.enabled(false);
+        return globalConfigObject.default;
+    }
+}

package/lib/esm/utils/index.js

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