diff --git a/package.json b/package.json index 3cdacbf..3711554 100644 --- a/package.json +++ b/package.json @@ -47,9 +47,6 @@ "backend", "library" ], - "engines": { - "node": ">=18.10.0" - }, "scripts": { "prepare": "husky", "clean": "node scripts/rm.js lib", diff --git a/src/index.ts b/src/index.ts index 3a3b486..bdc2e58 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,3 +1,4 @@ export * from "./config"; export * from "./env"; +export * from "./interfaces"; export * from "./utils"; diff --git a/src/interfaces/application-express.interface.ts b/src/interfaces/application-express.interface.ts new file mode 100644 index 0000000..8a77bb1 --- /dev/null +++ b/src/interfaces/application-express.interface.ts @@ -0,0 +1,57 @@ +/* eslint-disable @typescript-eslint/no-namespace */ +import express from "express"; +import { Environment, IEnvironment } from "./environment.interface"; +import { IConsoleMessage } from "./console.interface"; +import { RenderEngine } from "./render/render.types"; + +/** + * Namespace for the Server Application. + * @namespace Server + * @public API + */ +export namespace Server { + /** + * Interface for the WebServer application implementation. + */ + export interface IWebServer { + initEnvironment(environment: Environment, options?: IEnvironment): void; + + listen(port: number | string, appInfo?: IConsoleMessage): Promise; + + setEngine( + engine: RenderEngine.Engine, + options?: T, + ): Promise; + } + + /** + * Constructor type for IWebServer. + */ + export interface IWebServerConstructor { + new (): T; + } + + /** + * Public Interface for the WebServer application. + * @public API + */ + export interface IWebServerPublic { + /** + * 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; + + /** + * Get the underlying HTTP server. (default: Express.js) + * @returns The underlying HTTP server after initialization. + * @public API + */ + getHttpServer(): Promise; + } +} + +export type IWebServer = Server.IWebServer; +export type IWebServerConstructor = Server.IWebServerConstructor; +export type IWebServerPublic = Server.IWebServerPublic; diff --git a/src/interfaces/console.interface.ts b/src/interfaces/console.interface.ts new file mode 100644 index 0000000..bfd3e35 --- /dev/null +++ b/src/interfaces/console.interface.ts @@ -0,0 +1,8 @@ +/** + * Interface representing application message details for console output. + * @public API + */ +export interface IConsoleMessage { + appName: string; + appVersion: string; +} diff --git a/src/interfaces/environment.interface.ts b/src/interfaces/environment.interface.ts new file mode 100644 index 0000000..980cfee --- /dev/null +++ b/src/interfaces/environment.interface.ts @@ -0,0 +1,43 @@ +/* eslint-disable @typescript-eslint/no-namespace */ + +/** + * The Environment namespace contains all the types and interfaces related to environment configuration. + * @namespace Environment + * @public API + */ +export namespace Env { + /** + * Enum representing possible server environments. + * @public API + */ + export enum ServerEnvironment { + Development = "development", + Production = "production", + Remote = "remote", + } + + /** + * Type representing possible server environments. + */ + export type TypeServerEnvironment = "development" | "production" | "remote"; + + /** + * Interface for environment configuration options. + * @public API + */ + export interface IEnvironment { + env: { + development?: string; + production?: string; + }; + } + + /** + * Type representing possible server environments. + * @public API + */ + export type Environment = ServerEnvironment | TypeServerEnvironment | undefined; +} + +export type Environment = Env.Environment; +export type IEnvironment = Env.IEnvironment; diff --git a/src/interfaces/index.ts b/src/interfaces/index.ts new file mode 100644 index 0000000..befed99 --- /dev/null +++ b/src/interfaces/index.ts @@ -0,0 +1,10 @@ +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, + IWebServerConstructor, + IWebServerPublic, + Server, +} from "./application-express.interface"; diff --git a/src/interfaces/middleware.interface.ts b/src/interfaces/middleware.interface.ts new file mode 100644 index 0000000..6bf6683 --- /dev/null +++ b/src/interfaces/middleware.interface.ts @@ -0,0 +1,10 @@ +import { Request, Response, NextFunction } from 'express'; + +/** + * ExpressoTS Class middleware interface. + */ +export interface IExpressoMiddleware { + //readonly name: string; + use(req: Request, res: Response, next: NextFunction): Promise | void; + } + \ No newline at end of file diff --git a/src/interfaces/render/ejs.types.ts b/src/interfaces/render/ejs.types.ts new file mode 100644 index 0000000..c5c5cb3 --- /dev/null +++ b/src/interfaces/render/ejs.types.ts @@ -0,0 +1,189 @@ +/* eslint-disable @typescript-eslint/no-explicit-any */ + +/** + * 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 | 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 | 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 | undefined; + + /** + * Custom function to handle EJS includes + */ + includer?: IncluderCallback; +} diff --git a/src/interfaces/render/render.types.ts b/src/interfaces/render/render.types.ts new file mode 100644 index 0000000..91218d9 --- /dev/null +++ b/src/interfaces/render/render.types.ts @@ -0,0 +1,78 @@ +/* eslint-disable @typescript-eslint/no-namespace */ +import { Options } from "./ejs.types"; + +/** + * The Render namespace contains all the types and interfaces related to rendering views. + * @namespace Render + * @public API + */ +export namespace RenderEngine { + /** + * Ejs options + * @typedef {Object} EjsOptions + * @property {string | Array} viewsDir - The path to the views folder + * @property {string} viewEngine - The view engine + * @property {ejs.Options} [serverOptions] - The server options + * @public API + */ + export type EjsOptions = { + viewsDir?: string | Array; + 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 + */ + export 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 + */ + export type PugOptions = { + viewEngine?: string; + viewsDir?: string; + }; + + /** + * The configuration options for the view engine. + * @typedef {HandlebarsOptions | EjsOptions | PugOptions} RenderOptions + * @public API + */ + export 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 + */ + export enum Engine { + HBS = "hbs", + EJS = "ejs", + PUG = "pug", + } + + /** + * The configuration options for the view engine. + * @typedef {HandlebarsOptions | EjsOptions} EngineOptions + * @public API + */ + export type EngineOptions = HandlebarsOptions | EjsOptions | PugOptions; +}