zibri 2.2.1 → 2.3.0

package/src/global/after-app-shutdown.interface.ts

@@ -0,0 +1,46 @@
+import { ShutdownSignal, ZibriApplication } from '../application';
+
+/**
+ * Runs just after the app shuts down.
+ * This is useful for things like the data source service,
+ * which should still be available at the OnAppShutdown hooks.
+ *
+ * In most cases you probably want to implement OnAppShutdown.
+ */
+export interface AfterAppShutdown {
+    /**
+     * Runs just after the app shuts down.
+     * This is useful for things like the data source service,
+     * which should still be available at the OnAppShutdown hooks.
+     *
+     * In most cases you probably want to implement OnAppShutdown.
+     */
+    afterAppShutdown: (app: ZibriApplication, signal: ShutdownSignal | undefined) => void | Promise<void>,
+    /**
+     * The timeout for after which the graceful shutdown should fail.
+     * @default 30 seconds
+     */
+    readonly shutdownTimeoutInMs?: number
+}
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Checks if the given value implements the AfterAppShutdown interface.
+ * @param value - The value to check.
+ */
+export function implementsAfterAppShutdown(value: unknown): value is AfterAppShutdown {
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (value == undefined) {
+        return false;
+    }
+    if (!('afterAppShutdown' in value)) {
+        return false;
+    }
+
+    if (typeof value.afterAppShutdown !== 'function') {
+        return false;
+    }
+    return true;
+}

package/src/global/app-state.enum.ts

@@ -0,0 +1,10 @@
+/**
+ * The possible state that the app can be in.
+ */
+export enum AppState {
+    OFFLINE = 'offline',
+    CREATED = 'created',
+    INITIALIZED = 'initialized',
+    STARTED = 'started',
+    SHUTTING_DOWN = 'shutting down'
+}

package/src/global/before-app-init.interface.ts

@@ -0,0 +1,39 @@
+import { ZibriApplication } from '../application';
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Checks if the given value implements the BeforeAppInit interface.
+ * @param value - The value to check.
+ */
+export function implementsBeforeAppInit(value: unknown): value is BeforeAppInit {
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (value == undefined) {
+        return false;
+    }
+    if (!('beforeAppInit' in value)) {
+        return false;
+    }
+
+    if (typeof value.beforeAppInit !== 'function') {
+        return false;
+    }
+    return true;
+}
+
+/**
+ * Runs just before the app initializes.
+ * This is useful for things like the data source service, which other services might rely on being available on initialization.
+ *
+ * In most cases you probably want to implement OnAppInit, as your service probably does not fall in that category.
+ */
+export interface BeforeAppInit {
+    /**
+     * Runs just before the app initializes.
+     * This is useful for things like the data source service, which other services might rely on being available on initialization.
+     *
+     * In most cases you probably want to implement OnAppInit, as your service probably does not fall in that category.
+     */
+    beforeAppInit: (app: ZibriApplication) => void | Promise<void>
+}

package/src/global/before-app-shutdown.interface.ts

@@ -0,0 +1,48 @@
+import { ShutdownSignal, ZibriApplication } from '../application';
+
+/**
+ * Runs just before the app shuts down.
+ * This is useful for things like the cron or websocket service,
+ * which creates new work that might rely on other services still being operational.
+ *
+ * In most cases you probably want to implement OnAppShutdown.
+ * Most relevant things like eg. The data source service are still operational there, as they implement the AfterAppShutdown interface.
+ */
+export interface BeforeAppShutdown {
+    /**
+     * Runs just before the app shuts down.
+     * This is useful for things like the cron or websocket service,
+     * which creates new work that might rely on other services still being operational.
+     *
+     * In most cases you probably want to implement OnAppShutdown.
+     * Most relevant things like eg. The data source service are still operational there, as they implement the AfterAppShutdown interface.
+     */
+    beforeAppShutdown: (app: ZibriApplication, signal: ShutdownSignal | undefined) => void | Promise<void>,
+    /**
+     * The timeout for after which the graceful shutdown should fail.
+     * @default 30 seconds
+     */
+    readonly shutdownTimeoutInMs?: number
+}
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Checks if the given value implements the BeforeAppShutdown interface.
+ * @param value - The value to check.
+ */
+export function implementsBeforeAppShutdown(value: unknown): value is BeforeAppShutdown {
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (value == undefined) {
+        return false;
+    }
+    if (!('beforeAppShutdown' in value)) {
+        return false;
+    }
+
+    if (typeof value.beforeAppShutdown !== 'function') {
+        return false;
+    }
+    return true;
+}

package/src/global/global-registry.ts

@@ -1,23 +1,13 @@
 import { ZibriApplicationOptions } from '../application-options.model';
+import { AppState } from './app-state.enum';
 import { UserRepositories } from '../auth/models/user-repositories.model';
 import { BackupResourceInterface } from '../backup/backup-resource.interface';
-import { DataSourceInterface } from '../data-source/data-sources/data-source.interface';
 import { DiProvider } from '../di/models/di-provider.model';
 import { BaseEntity } from '../entity/base-entity.model';
 import { BodyParserInterface } from '../parsing/body-parser.interface';
 import { Newable } from '../types/newable.type';
 import { Version } from '../types/version.type';
 
-/**
- * The possible state that the app can be in.
- */
-export enum AppState {
-    OFFLINE = 'offline',
-    CREATED = 'created',
-    INITIALIZED = 'initialized',
-    RUNNING = 'running'
-}
-
 /**
  * The data of the app.
  */
@@ -51,6 +41,10 @@ export abstract class GlobalRegistry {
      * All injectables registered eg. Via \@Injectable.
      */
     static readonly injectables: DiProvider<unknown>[] = [];
+    /**
+     * All injectables registered via \@Injectable but with the { register: 'onUse' } flag.
+     */
+    static readonly lazyInjectables: DiProvider<unknown>[] = [];
     /**
      * All controllers registered with \@Controller.
      */
@@ -59,10 +53,6 @@ export abstract class GlobalRegistry {
      * All websocket controllers registered with \@WebsocketController.
      */
     static readonly websocketControllerClasses: Newable<unknown>[] = [];
-    /**
-     * All datasources registered with \@DataSource.
-     */
-    static readonly dataSourceClasses: Newable<DataSourceInterface>[] = [];
     /**
      * All entities registered with \@Entity.
      */
@@ -90,45 +80,67 @@ export abstract class GlobalRegistry {
                     return;
                 }
                 case AppState.CREATED: {
-                    throw new Error('The app has already been marked as created.');
+                    throw new Error(`The app has already been marked as "${AppState.CREATED}".`);
                 }
                 case AppState.INITIALIZED: {
-                    throw new Error('The app has already been marked as initialized.');
+                    throw new Error(`The app has already been marked as "${AppState.INITIALIZED}".`);
                 }
-                case AppState.RUNNING: {
-                    throw new Error('The app has already been marked as running.');
+                case AppState.STARTED: {
+                    throw new Error(`The app has already been marked as "${AppState.STARTED}".`);
+                }
+                case AppState.SHUTTING_DOWN: {
+                    throw new Error(`The app has already been marked as "${AppState.SHUTTING_DOWN}".`);
                 }
             }
         },
         [AppState.INITIALIZED]: () => {
             switch (this.appData.state) {
                 case AppState.OFFLINE: {
-                    throw new Error('The app has not been marked as created yet.');
+                    throw new Error(`The app has not been marked as "${AppState.CREATED}" yet.`);
                 }
                 case AppState.CREATED: {
                     return;
                 }
                 case AppState.INITIALIZED: {
-                    throw new Error('The app has already been marked as initialized.');
+                    throw new Error(`The app has already been marked as "${AppState.INITIALIZED}".`);
+                }
+                case AppState.STARTED: {
+                    throw new Error(`The app has already been marked as "${AppState.STARTED}".`);
                 }
-                case AppState.RUNNING: {
-                    throw new Error('The app has already been marked as running');
+                case AppState.SHUTTING_DOWN: {
+                    throw new Error(`The app has already been marked as "${AppState.SHUTTING_DOWN}".`);
                 }
             }
         },
-        [AppState.RUNNING]: () => {
+        [AppState.STARTED]: () => {
             switch (this.appData.state) {
+                case AppState.CREATED:
                 case AppState.OFFLINE: {
-                    throw new Error('The app has not been marked as initialized yet.');
-                }
-                case AppState.CREATED: {
-                    throw new Error('The app has not been marked as initialized yet.');
+                    throw new Error(`The app has not been marked as "${AppState.INITIALIZED}" yet.`);
                 }
                 case AppState.INITIALIZED: {
                     return;
                 }
-                case AppState.RUNNING: {
-                    throw new Error('The app has already been marked as running.');
+                case AppState.STARTED: {
+                    throw new Error(`The app has already been marked as "${AppState.STARTED}".`);
+                }
+                case AppState.SHUTTING_DOWN: {
+                    throw new Error(`The app has already been marked as "${AppState.SHUTTING_DOWN}".`);
+                }
+            }
+        },
+        [AppState.SHUTTING_DOWN]: () => {
+            switch (this.appData.state) {
+                case AppState.CREATED:
+                case AppState.INITIALIZED:
+                case AppState.STARTED: {
+                    return;
+                }
+                case AppState.OFFLINE: {
+                    throw new Error(`The app has not been marked as "${AppState.CREATED}" yet.`);
+                }
+                case AppState.SHUTTING_DOWN: {
+                    throw new Error(`The app has already been marked as "${AppState.SHUTTING_DOWN}".`);
                 }
             }
         }
@@ -168,23 +180,30 @@ export abstract class GlobalRegistry {
     }
 
     /**
-     * Marks the app as running.
+     * Marks the app as started.
+     */
+    static markAppAsStarted(): void {
+        this.changeAppState(AppState.STARTED);
+    }
+
+    /**
+     * Marks the app as shutting down.
      */
-    static markAppAsRunning(): void {
-        this.changeAppState(AppState.RUNNING);
+    static markAppAsShuttingDown(): void {
+        this.changeAppState(AppState.SHUTTING_DOWN);
     }
 
     /**
-     * Checks if the app is running.
-     * @returns True when the app has the state of running, false otherwise.
+     * Checks if the app has been started.
+     * @returns True when the app has the state of AppState.STARTED, false otherwise.
      */
-    static isAppRunning(): boolean {
-        return this.appData.state === AppState.RUNNING;
+    static isAppStarted(): boolean {
+        return this.appData.state === AppState.STARTED;
     }
 
     /**
      * Checks if the app is initialized.
-     * @returns True when the app has the state of initialized, false otherwise.
+     * @returns True when the app has the state of AppState.INITIALIZED, false otherwise.
      */
     static isAppInitialized(): boolean {
         return this.appData.state === AppState.INITIALIZED;
@@ -192,12 +211,20 @@ export abstract class GlobalRegistry {
 
     /**
      * Checks if the app is created.
-     * @returns True when the app has the state of created, false otherwise.
+     * @returns True when the app has the state of AppState.CREATED, false otherwise.
      */
     static isAppCreated(): boolean {
         return this.appData.state === AppState.CREATED;
     }
 
+    /**
+     * Checks if the app is shutting down.
+     * @returns True when the app has the state of AppState.SHUTTING_DOWN, false otherwise.
+     */
+    static isAppShuttingDown(): boolean {
+        return this.appData.state === AppState.SHUTTING_DOWN;
+    }
+
     private static changeAppState(state: AppState): void {
         this.validateAppStateChange[state]();
         this.appData.state = state;

package/src/global/on-app-init.interface.ts

@@ -0,0 +1,33 @@
+import { ZibriApplication } from '../application';
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Checks if the given value implements the OnAppInit interface.
+ * @param value - The value to check.
+ */
+export function implementsOnAppInit(value: unknown): value is OnAppInit {
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (value == undefined) {
+        return false;
+    }
+    if (!('onAppInit' in value)) {
+        return false;
+    }
+
+    if (typeof value.onAppInit !== 'function') {
+        return false;
+    }
+    return true;
+}
+
+/**
+ * Runs when the app initializes.
+ */
+export interface OnAppInit {
+    /**
+     * Runs when the app initializes.
+     */
+    onAppInit: (app: ZibriApplication) => void | Promise<void>
+}

package/src/global/on-app-shutdown.interface.ts

@@ -0,0 +1,38 @@
+import { ShutdownSignal, ZibriApplication } from '../application';
+
+/**
+ * Runs when the app shuts down.
+ */
+export interface OnAppShutdown {
+    /**
+     * Runs when the app shuts down.
+     */
+    onAppShutdown: (app: ZibriApplication, signal: ShutdownSignal | undefined) => void | Promise<void>,
+    /**
+     * The timeout for after which the graceful shutdown should fail.
+     * @default 30 seconds
+     */
+    readonly shutdownTimeoutInMs?: number
+}
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Checks if the given value implements the OnAppShutdown interface.
+ * @param value - The value to check.
+ */
+export function implementsOnAppShutdown(value: unknown): value is OnAppShutdown {
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (value == undefined) {
+        return false;
+    }
+    if (!('onAppShutdown' in value)) {
+        return false;
+    }
+
+    if (typeof value.onAppShutdown !== 'function') {
+        return false;
+    }
+    return true;
+}

package/src/global/on-app-start.interface.ts

@@ -0,0 +1,33 @@
+import { ZibriApplication } from '../application';
+
+// eslint-disable-next-line jsdoc/require-returns
+/**
+ * Checks if the given value implements the OnAppStart interface.
+ * @param value - The value to check.
+ */
+export function implementsOnAppStart(value: unknown): value is OnAppStart {
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (value == undefined) {
+        return false;
+    }
+    if (!('onAppStart' in value)) {
+        return false;
+    }
+
+    if (typeof value.onAppStart !== 'function') {
+        return false;
+    }
+    return true;
+}
+
+/**
+ * Runs when the app starts.
+ */
+export interface OnAppStart {
+    /**
+     * Runs when the app starts.
+     */
+    onAppStart: (app: ZibriApplication) => void | Promise<void>
+}

package/src/handlebars/generate-handlebar-type-files.function.ts

@@ -2,7 +2,7 @@ import { AstProgram } from './ast.model';
 import { HandlebarUtilities } from './handlebar.utilities';
 import { resolveAllArrayKeys } from './resolve-all-array-keys.function';
 import { resolveTree } from './resolve-tree.function';
-import { FsUtilities, Path } from '../utilities/fs.utilities';
+import { FsUtilities, FsPath } from '../utilities/fs.utilities';
 import { ObjectUtilities } from '../utilities/object.utilities';
 
 // eslint-disable-next-line jsdoc/require-jsdoc
@@ -10,11 +10,14 @@ export type PathTree = {
     [key: string]: PathTree
 };
 
+const defaultGlobs: string[] = ['src/templates/**/*.hbs'];
+
 /**
- * Generate type files for handlebar files (.hbs), so that they expose a correctly typed "renderTemplate" function.
+ * Generate type files for handlebar files, so that they expose a correctly typed "renderTemplate" function.
+ * @param glob - The glob(s) to find your handlebar files from.
  */
-export async function generateHandlebarTypeFiles(): Promise<void> {
-    const templateFiles: Path[] = await FsUtilities.glob('src/templates/**/*.hbs');
+export async function generateHandlebarTypeFiles(glob: string | string[] = defaultGlobs): Promise<void> {
+    const templateFiles: FsPath[] = await FsUtilities.glob(glob);
 
     for (const file of templateFiles) {
         if (await canBeSkipped(file)) {
@@ -34,7 +37,7 @@ export async function generateHandlebarTypeFiles(): Promise<void> {
 }
 
 // eslint-disable-next-line jsdoc/require-jsdoc
-export async function generateHandlebarType(ast: AstProgram, file: Path): Promise<string[]> {
+export async function generateHandlebarType(ast: AstProgram, file: FsPath): Promise<string[]> {
     const arrayKeys: string[] = [...new Set(resolveAllArrayKeys(ast, undefined))];
     const tree: PathTree = resolveTree(ast, arrayKeys);
     const arrayKeysWithoutThis: string[] = arrayKeys.map(k => k.replaceAll('this.', ''));
@@ -42,7 +45,7 @@ export async function generateHandlebarType(ast: AstProgram, file: Path): Promis
 }
 
 // eslint-disable-next-line jsdoc/require-jsdoc
-async function generateTypeFile(tree: PathTree, arrayKeys: string[], file: Path): Promise<string[]> {
+async function generateTypeFile(tree: PathTree, arrayKeys: string[], file: FsPath): Promise<string[]> {
     const typeLines: string[] = generateInterfaceLines(tree, arrayKeys);
     const type: string[] = typeLines.length
         ? [
@@ -64,7 +67,7 @@ async function generateTypeFile(tree: PathTree, arrayKeys: string[], file: Path)
         .join('\n')
         .replace('mailingListData:', 'mailingListData?:');
 
-    const outFile: Path = FsUtilities.getPath(FsUtilities.dirName(file), `${FsUtilities.baseName(file)}.ts`);
+    const outFile: FsPath = FsUtilities.getPath(FsUtilities.dirName(file), `${FsUtilities.baseName(file)}.ts`);
     await FsUtilities.upsertFile(outFile, content);
 
     return content.split('\n');
@@ -105,8 +108,8 @@ function generateInterfaceLines(
 }
 
 // eslint-disable-next-line jsdoc/require-jsdoc
-async function canBeSkipped(hbsFile: Path): Promise<boolean> {
-    const tsFile: Path = FsUtilities.getPath(`${hbsFile}.ts`);
+async function canBeSkipped(hbsFile: FsPath): Promise<boolean> {
+    const tsFile: FsPath = FsUtilities.getPath(`${hbsFile}.ts`);
 
     if (!await FsUtilities.exists(tsFile)) {
         return false;

package/src/handlebars/handlebar.utilities.ts

@@ -1,9 +1,7 @@
 import handlebars, { ParseOptions } from 'handlebars';
 
 import { AstProgram } from './ast.model';
-import { ZIBRI_DI_TOKENS } from '../di/default/zibri-di-tokens.default';
-import { inject } from '../di/inject.function';
-import { FsUtilities, Path } from '../utilities/fs.utilities';
+import { FsUtilities, FsPath } from '../utilities/fs.utilities';
 import { MaskUtilities } from '../utilities/mask.utilities';
 import { toCamelCase } from '../utilities/to-camel-case.function';
 
@@ -16,8 +14,9 @@ export abstract class HandlebarUtilities {
     /**
      * Initializes the handlebar utilities.
      * @param H - The external handlebar object. Is needed so helpers can be registered both inside and outside of Zibri.
+     * @param componentsDir - The directory where components reside.
      */
-    static async init(H: typeof Handlebars): Promise<void> {
+    static async init(H: typeof Handlebars, componentsDir: string): Promise<void> {
         this.H = H;
         this.registerHelper('json', (context) => JSON.stringify(context));
         this.registerHelper('concat', (...args: unknown[]) => {
@@ -44,8 +43,7 @@ export abstract class HandlebarUtilities {
             return new handlebars.SafeString(MaskUtilities.mask(value));
         });
 
-        const componentsDir: string = inject(ZIBRI_DI_TOKENS.ASSET_SERVICE).componentTemplatePath;
-        const files: Path[] = await FsUtilities.glob(FsUtilities.getPath(componentsDir, '*.hbs'));
+        const files: FsPath[] = await FsUtilities.glob(FsUtilities.getPath(componentsDir, '*.hbs'));
         for (const file of files) {
             const src: string = await FsUtilities.readFile(file);
             const base: string = FsUtilities.baseName(file).split('.hbs')[0];
@@ -67,6 +65,32 @@ export abstract class HandlebarUtilities {
         return this.H.compile(input, options);
     }
 
+    /**
+     * Renders the template at the given path with the given data.
+     * @param path - The path of the handlebars template file.
+     * @param data - The data to fill into the template.
+     * @returns The rendered html string.
+     */
+    static async renderTemplate<T extends Record<string, unknown>>(path: `${FsPath}.hbs`, data: T): Promise<string> {
+        const source: string = await FsUtilities.readFile(path as FsPath);
+        return this.renderTemplateString(source, data);
+    }
+
+    /**
+     * Renders the given handlebars template string as html, using the provided data as variables.
+     * @param templateString - The handlebars template string.
+     * @param data - The data to use inside the template.
+     * @returns The rendered html content.
+     */
+    static renderTemplateString<T extends Record<string, unknown>>(
+        templateString: string,
+        data: T
+    ): string {
+        const template: HandlebarsTemplateDelegate<T> = this.render(templateString);
+        const html: string = template(data);
+        return html;
+    }
+
     /**
      * Parses the given handlebars string into an AST.
      * @param input - The handlebars template in form of a string.

package/src/http-client/http-client.error.ts

@@ -0,0 +1,94 @@
+import { HttpClientResponse } from './http-client-response.model';
+import { HttpMethod } from '../http/http-method.enum';
+import { OmitStrict } from '../types/omit-strict.type';
+
+/**
+ * Data of the http request that was sent.
+ */
+export type HttpClientErrorRequestData = {
+    /**
+     * The request method.
+     */
+    method: HttpMethod,
+    /**
+     * The body of the request.
+     */
+    body: unknown,
+    /**
+     * The headers of the request.
+     */
+    headers: Record<string, unknown>,
+    /**
+     * The full url of the request.
+     */
+    url: string
+};
+
+/**
+ * Data of the http response that was received.
+ */
+export type HttpClientErrorResponseData = OmitStrict<HttpClientResponse<unknown, Record<string, unknown>>, 'rawBody'>;
+
+/**
+ * Options for creating a http client error.
+ */
+export type HttpClientErrorOptions = {
+    /**
+     * The data of the response, if one could be received.
+     */
+    responseData: HttpClientErrorResponseData | undefined,
+    /**
+     * The data of the request, if one could be made.
+     */
+    requestData: HttpClientErrorRequestData | undefined
+};
+
+/**
+ * Error that is thrown when a request from the http client didn't work.
+ */
+export class HttpClientError extends Error {
+    /**
+     * The data of the response, if one could be received.
+     */
+    readonly responseData?: HttpClientErrorResponseData;
+    /**
+     * The data of the request, if one could be made.
+     */
+    readonly requestData?: HttpClientErrorRequestData;
+
+    constructor(message: string, data: HttpClientErrorOptions, options?: ErrorOptions | undefined) {
+        super(getErrorMessage(message, data), options);
+        this.name = 'HttpClientError';
+        this.responseData = data.responseData;
+        this.requestData = data.requestData;
+
+        Object.defineProperty(this, 'message', { enumerable: true });
+    }
+}
+
+/**
+ * Check whether or not the given value is a http client error.
+ * @param value - The value to check.
+ * @returns True when the values name is 'HttpClientError', false otherwise.
+ */
+export function isHttpClientError(value: unknown): value is HttpClientError {
+    return typeof value === 'object' && value != undefined && 'name' in value && value.name === 'HttpClientError';
+}
+
+// eslint-disable-next-line jsdoc/require-jsdoc
+function getErrorMessage(message: string, data: HttpClientErrorOptions): string {
+    if (!data.responseData) {
+        if (data.requestData) {
+            return `No response received for ${data.requestData.method.toUpperCase()} ${data.requestData.url}:\n${message}`;
+        }
+        return `Could not send the request:\n${message}`;
+    }
+
+    if (!data.requestData) {
+        return `Could not send the request:\n${message}`;
+    }
+
+    const fullUrl: string = `${data.requestData.method.toUpperCase()} ${data.requestData.url}`;
+
+    return `Request ${fullUrl} failed with ${data.responseData.status} ${data.responseData.statusText}`;
+}