zibri 2.2.0 → 2.3.0

package/src/global/global-registry.ts

@@ -1,21 +1,12 @@
 import { ZibriApplicationOptions } from '../application-options.model';
-import { UserRepositories } from '../auth';
-import { BackupResourceInterface } from '../backup';
-import { DataSourceInterface } from '../data-source';
-import { DiProvider } from '../di';
+import { AppState } from './app-state.enum';
+import { UserRepositories } from '../auth/models/user-repositories.model';
+import { BackupResourceInterface } from '../backup/backup-resource.interface';
+import { DiProvider } from '../di/models/di-provider.model';
 import { BaseEntity } from '../entity/base-entity.model';
-import { BodyParserInterface } from '../parsing';
-import { Newable, Version } from '../types';
-
-/**
- * The possible state that the app can be in.
- */
-export enum AppState {
-    OFFLINE = 'offline',
-    CREATED = 'created',
-    INITIALIZED = 'initialized',
-    RUNNING = 'running'
-}
+import { BodyParserInterface } from '../parsing/body-parser.interface';
+import { Newable } from '../types/newable.type';
+import { Version } from '../types/version.type';
 
 /**
  * The data of the app.
@@ -50,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.
      */
@@ -58,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.
      */
@@ -89,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}".`);
                 }
             }
         }
@@ -167,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;
@@ -191,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/ast.model.ts

@@ -1,5 +1,5 @@
 /* eslint-disable jsdoc/require-jsdoc */
-import { OmitStrict } from '../types';
+import { OmitStrict } from '../types/omit-strict.type';
 
 export type AstProgram = OmitStrict<hbs.AST.Program, 'body'> & { body: AstStatement[] };
 
@@ -19,7 +19,7 @@ export type AstBlockPathExpression = OmitStrict<AstPathExpression, 'original'> &
 export type AstSubExpression = OmitStrict<hbs.AST.SubExpression, 'path' | 'params' | 'hash'> & {
     path: AstPathExpression,
     params: AstExpression[],
-    hash: AstHash
+    hash: AstHash | undefined
 };
 
 export type AstStringLiteral = hbs.AST.StringLiteral;
@@ -87,7 +87,7 @@ export type AstPartialBlockStatement = OmitStrict<
     name: AstPathExpression,
     params: AstExpression[],
     hash: AstHash,
-    program: AstProgram
+    program: AstProgram | undefined
 };
 
 export type AstStatement = AstBlockStatement

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

@@ -1,24 +1,23 @@
-import { readFile, writeFile, stat } from 'fs/promises';
-import { dirname, basename, join } from 'path';
-
-import { sync as globSync } from 'glob';
-import { parse } from 'handlebars';
-
-import { ObjectUtilities, pathExists } from '../utilities';
 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, FsPath } from '../utilities/fs.utilities';
+import { ObjectUtilities } from '../utilities/object.utilities';
 
 // eslint-disable-next-line jsdoc/require-jsdoc
 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: string[] = globSync('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)) {
@@ -26,8 +25,8 @@ export async function generateHandlebarTypeFiles(): Promise<void> {
         }
 
         try {
-            const src: string = await readFile(file, 'utf8');
-            const ast: AstProgram = parse(src, { srcName: file }) as AstProgram;
+            const src: string = await FsUtilities.readFile(file);
+            const ast: AstProgram = HandlebarUtilities.parse(src, { srcName: file });
             await generateHandlebarType(ast, file);
         }
         catch (error) {
@@ -38,7 +37,7 @@ export async function generateHandlebarTypeFiles(): Promise<void> {
 }
 
 // eslint-disable-next-line jsdoc/require-jsdoc
-export async function generateHandlebarType(ast: AstProgram, file: string): 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.', ''));
@@ -46,14 +45,21 @@ export async function generateHandlebarType(ast: AstProgram, file: string): Prom
 }
 
 // eslint-disable-next-line jsdoc/require-jsdoc
-async function generateTypeFile(tree: PathTree, arrayKeys: string[], file: string): Promise<string[]> {
+async function generateTypeFile(tree: PathTree, arrayKeys: string[], file: FsPath): Promise<string[]> {
+    const typeLines: string[] = generateInterfaceLines(tree, arrayKeys);
+    const type: string[] = typeLines.length
+        ? [
+            'type Context = {',
+            ...typeLines,
+            '};'
+        ]
+        : ['type Context = Record<string, never>;'];
+
     const content: string = [
         '// auto-generated — do not edit',
-        `import raw from './${basename(file)}';`,
+        `import raw from './${FsUtilities.baseName(file)}';`,
         '',
-        'interface Context {',
-        ...generateInterfaceLines(tree, arrayKeys),
-        '}',
+        ...type,
         '',
         'const renderTemplate: (ctx: Context) => string = raw;',
         'export default renderTemplate;'
@@ -61,8 +67,8 @@ async function generateTypeFile(tree: PathTree, arrayKeys: string[], file: strin
         .join('\n')
         .replace('mailingListData:', 'mailingListData?:');
 
-    const outFile: string = join(dirname(file), `${basename(file)}.ts`);
-    await writeFile(outFile, content, 'utf8');
+    const outFile: FsPath = FsUtilities.getPath(FsUtilities.dirName(file), `${FsUtilities.baseName(file)}.ts`);
+    await FsUtilities.upsertFile(outFile, content);
 
     return content.split('\n');
 }
@@ -102,13 +108,13 @@ function generateInterfaceLines(
 }
 
 // eslint-disable-next-line jsdoc/require-jsdoc
-async function canBeSkipped(hbsFile: string): Promise<boolean> {
-    const tsFile: string = `${hbsFile}.ts`;
+async function canBeSkipped(hbsFile: FsPath): Promise<boolean> {
+    const tsFile: FsPath = FsUtilities.getPath(`${hbsFile}.ts`);
 
-    if (!await pathExists(tsFile)) {
+    if (!await FsUtilities.exists(tsFile)) {
         return false;
     }
 
-    const [hbsStats, tsStats] = await Promise.all([stat(hbsFile), stat(tsFile)]);
+    const [hbsStats, tsStats] = await Promise.all([FsUtilities.stat(hbsFile), FsUtilities.stat(tsFile)]);
     return tsStats.mtimeMs >= hbsStats.mtimeMs;
 }

package/src/handlebars/handlebar.utilities.ts

@@ -1,6 +1,9 @@
-import handlebars from 'handlebars';
+import handlebars, { ParseOptions } from 'handlebars';
 
-import { TreeNode } from '../assets';
+import { AstProgram } from './ast.model';
+import { FsUtilities, FsPath } from '../utilities/fs.utilities';
+import { MaskUtilities } from '../utilities/mask.utilities';
+import { toCamelCase } from '../utilities/to-camel-case.function';
 
 /**
  * Utilities for handling handlebar templates.
@@ -11,10 +14,15 @@ 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 init(H: typeof Handlebars): 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[]) => {
+            args.pop();
+            return args.join('');
+        });
         // eslint-disable-next-line typescript/no-unsafe-return
         this.registerHelper('??', (a, b) => a ?? b);
         this.registerHelper('and',
@@ -32,44 +40,101 @@ export abstract class HandlebarUtilities {
             if (typeof value !== 'string') {
                 return '';
             }
-            return new handlebars.SafeString(mask(value));
+            return new handlebars.SafeString(MaskUtilities.mask(value));
         });
-        this.registerHelper(
-            'renderTree',
-            function(
-                this: handlebars.HelperOptions, // ← explicitly type `this`
-                nodes: TreeNode[]
-            ): handlebars.SafeString {
-                let out: string = '';
-                for (const node of nodes) {
-                    if (node.type === 'directory') {
-                        out += `<details><summary>${handlebars.escapeExpression(node.name)
-                        }</summary>`;
-                        // 2) Call the helper recursively using `apply` so `this` stays typed
-                        out += (handlebars.helpers.renderTree as Function).apply(this, [node.children]);
-                        out += '</details>';
-                    }
-                    else {
-                        out += `<a class="file-link" href="${handlebars.escapeExpression(node.route)
-                        }">${handlebars.escapeExpression(node.name)}</a>`;
-                    }
-                }
-                return new handlebars.SafeString(out);
-            }
-        );
+
+        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];
+            const partialName: string = toCamelCase(base);
+            this.registerPartial(partialName, src);
+        }
+    }
+
+    /**
+     * Compiles the given handlebars string.
+     * @param input - The handlebars template in form of a string.
+     * @param options - Additional options for compilation.
+     * @returns The compiled template function.
+     */
+    static render<T>(input: string, options?: CompileOptions): HandlebarsTemplateDelegate<T> {
+        if (typeof this.H.compile !== 'function') {
+            return handlebars.compile(input, options);
+        }
+        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.
+     * @param options - Additional options for parsing the template.
+     * @returns The abstract syntax tree of the template.
+     */
+    static parse(input: string, options?: ParseOptions): AstProgram {
+        return handlebars.parse(input, options) as AstProgram;
     }
 
     private static registerHelper(name: string, fn: Handlebars.HelperDelegate): void {
         handlebars.registerHelper(name, fn);
         this.H.registerHelper(name, fn);
     }
-}
 
-// eslint-disable-next-line jsdoc/require-jsdoc
-function mask(input: string): string {
-    if (input.length <= 3) {
-        return input;
+    private static registerPartial(name: string, template: string): void {
+        let compiledFn: HandlebarsTemplateDelegate;
+
+        // 1) If injected instance has a compiler, prefer it (keeps compile + runtime identical)
+        if (typeof this.H.compile === 'function') {
+            compiledFn = this.H.compile(template);
+        }
+        else {
+            // 2) Injected runtime is probably runtime-only. Create a template function that runtime understands:
+            //    a) precompile with local full compiler -> returns a JS string for the templateSpec
+            //    b) evaluate that spec to an object and call this.H.template(spec) to get a function
+            if (typeof this.H.template !== 'function') {
+                // Unexpected: fallback to local compile (best-effort)
+                compiledFn = handlebars.compile(template);
+            }
+            else {
+                // Precompile to a template spec text
+                const specSource: TemplateSpecification = handlebars.precompile(template);
+                // specSource is JS source that evaluates to the templateSpec object.
+                // Convert it into an object by evaluating it in a safe local function scope.
+                // This uses `new Function` which is the same approach Handlebars' CLI/runtime uses.
+                // eslint-disable-next-line typescript/no-unsafe-assignment, typescript/no-implied-eval, typescript/no-unsafe-call, typescript/no-base-to-string
+                const specObj: TemplateSpecification = new Function(`return (${specSource})`)();
+                // Now produce a runtime function using the injected runtime
+                compiledFn = this.H.template(specObj);
+            }
+        }
+
+        handlebars.registerPartial(name, compiledFn);
+        this.H.registerPartial(name, compiledFn);
     }
-    const starsCount: number = input.length - 3;
-    return input[0] + '*'.repeat(starsCount) + input.slice(-2);
 }

package/src/handlebars/resolve-all-array-keys.function.ts

@@ -1,4 +1,4 @@
-import { AstBlockStatement, AstExpression, AstProgram } from './ast.model';
+import { AstBlockStatement, AstExpression, AstProgram, AstStatement } from './ast.model';
 import { resolveKeyForPathExpression } from './resolve-key-for-path-expression.function';
 
 // eslint-disable-next-line jsdoc/require-jsdoc
@@ -10,6 +10,13 @@ export function resolveAllArrayKeys(ast: AstProgram, parentKey: string | undefin
                 res.push(...resolveArrayKeysForBlockStatement(element, parentKey));
                 break;
             }
+            case 'PartialBlockStatement': {
+                // nested program, but do NOT mark params as arrays
+                if (element.program) {
+                    res.push(...resolveAllArrayKeys(element.program, parentKey));
+                }
+                break;
+            }
             case 'PartialStatement':
             case 'CommentStatement':
             case 'MustacheStatement':
@@ -17,9 +24,8 @@ export function resolveAllArrayKeys(ast: AstProgram, parentKey: string | undefin
                 // reached leaf
                 break;
             }
-            case 'PartialBlockStatement':
             default: {
-                throw new Error(`Unknown AST Element ${element.type}`);
+                throw new Error(`Unknown AST Element ${(element as AstStatement).type}`);
             }
         }
     }

package/src/handlebars/resolve-keys-for-partial-statement.function.ts

@@ -14,7 +14,7 @@ export function resolveKeysForPartialStatement(
     }
 
     // 2) named params (hash)
-    for (const pair of stmt.hash.pairs) {
+    for (const pair of stmt.hash?.pairs ?? []) {
         res.push(...resolveKeysForExpression(pair.value, parentKey));
     }
 
@@ -40,7 +40,7 @@ export function resolveKeysForExpression(
             for (const p of param.params.slice(1)) {
                 out.push(...resolveKeysForExpression(p, parentKey));
             }
-            for (const pair of param.hash.pairs) {
+            for (const pair of param.hash?.pairs ?? []) {
                 out.push(...resolveKeysForExpression(pair.value, parentKey));
             }
             return out;