zibri 2.2.1 → 2.4.0

package/src/preact/collector.ts

@@ -1,11 +1,25 @@
 import { ComponentChild, ComponentChildren, Fragment, VNode } from 'preact';
 
 import { stringAwareReplace } from './string-aware-replace.function';
-import { OmitStrict } from '../types/omit-strict.type';
+import { JsonUtilities } from '../utilities/json.utilities';
 import { ObjectUtilities } from '../utilities/object.utilities';
 
 const HANDLERS_DIRECTIVE: string = 'data-ssr-handlers';
 
+/**
+ * Context of a current loop iteration.
+ */
+type LoopContext = {
+    /**
+     * The name of the currently looped over value.
+     */
+    varName: string,
+    /**
+     * The currently looped over value.
+     */
+    value: unknown
+};
+
 /**
  * A registered event handler entry.
  */
@@ -22,14 +36,13 @@ type HandlerEntry = {
     /**
      * The prefix of the component instance whose rendered native element owns this handler.
      */
-    ownerPrefix: string | undefined
+    ownerPrefix: string | undefined,
+    /**
+     * Context of a current loop iteration that this handler is called from.
+     */
+    loopContext: LoopContext | undefined
 };
 
-/**
- * A serialized event handler entry.
- */
-type SerializedHandlerEntry = OmitStrict<HandlerEntry, 'ownerPrefix'>;
-
 /**
  * Result for a simple delegate (basically just a passthrough).
  */
@@ -118,6 +131,7 @@ export class PreactCollector {
     private readonly map: Map<string, HandlerEntry> = new Map();
     private readonly nestedComponents: NestedComponentEntry[] = [];
     private readonly componentCounters: Map<string, number> = new Map();
+    private readonly loopContextMap: WeakMap<object, LoopContext> = new WeakMap();
     private readonly handlerRegex: RegExp = /^on/i;
 
     /**
@@ -149,8 +163,8 @@ export class PreactCollector {
                     }
                 }
                 else if (typeof val === 'function') {
-                    // Non-event function prop — can't be JSON.stringify'd, handle as inline binding
-                    nonHandlerFns.set(key, val as Function);
+                    // Non-event function prop — can't be JsonUtilities.stringify'd, handle as inline binding
+                    nonHandlerFns.set(key, val);
                 }
                 else {
                     // Capture non-handler props (className, type, disabled, etc.)
@@ -160,9 +174,31 @@ export class PreactCollector {
 
             let rendered: ComponentChild;
             try {
-                this.validateSingleParam(node.type as Function);
-                // eslint-disable-next-line typescript/no-unsafe-assignment, typescript/no-unsafe-call
-                rendered = (node.type as Function)(node.props);
+                this.validateSingleParam(node.type);
+                const originalMap: typeof Array.prototype.map = Array.prototype.map;
+                // eslint-disable-next-line typescript/no-this-alias
+                const self: this = this;
+                Array.prototype.map = function patchedMap<T, U>(
+                    this: T[],
+                    cb: (value: T, index: number, array: T[]) => U,
+                    thisArg?: unknown
+                ): U[] {
+                    const varName: string | undefined = self.extractFirstParamName(cb.toString());
+                    return originalMap.call(this, (item: T, index: number, arr: T[]) => {
+                        const result: U = cb.call(thisArg, item, index, arr);
+                        if (varName && result !== null && typeof result === 'object') {
+                            self.loopContextMap.set(result as object, { varName, value: item });
+                        }
+                        return result;
+                    }) as U[];
+                } as typeof Array.prototype.map;
+                try {
+                    // eslint-disable-next-line typescript/no-unsafe-assignment, typescript/no-unsafe-call
+                    rendered = (node.type as Function)(node.props);
+                }
+                finally {
+                    Array.prototype.map = originalMap;
+                }
                 if (rendered instanceof Promise) {
                     throw new Error(
                         `[ssr] Nested component '${node.type.name}' is async. `
@@ -207,7 +243,7 @@ export class PreactCollector {
                         }
                     }
                     if (ObjectUtilities.keys(resolvedProps).length) {
-                        componentBindings[`__propsObj_${propsParamName}`] = JSON.stringify(resolvedProps);
+                        componentBindings[`__propsObj_${propsParamName}`] = JsonUtilities.stringify(resolvedProps);
                     }
                 }
             }
@@ -239,7 +275,8 @@ export class PreactCollector {
             const val: unknown = node.props[key];
             if (this.handlerRegex.test(key) && typeof val === 'function') {
                 const event: string = key.slice(2).toLowerCase();
-                const id: string = this.registerHandler(val, event, parentPrefix);
+                const loopContext: LoopContext | undefined = this.loopContextMap.get(node) ?? undefined;
+                const id: string = this.registerHandler(val, event, parentPrefix, loopContext);
                 handlers.push(`${id}:${event}`);
             }
         }
@@ -336,7 +373,10 @@ export class PreactCollector {
             }
             let src: string = entry.src;
             for (const [from, to] of sorted) {
-            // Pass 1 — expand shorthand destructure properties
+                if (from === entry.loopContext?.varName) {
+                    continue;
+                }
+                // Pass 1 — expand shorthand destructure properties
                 src = stringAwareReplace(
                     src,
                     new RegExp(`(?<=[{,]\\s*)${from}(?=\\s*[,}])`, 'g'),
@@ -350,7 +390,7 @@ export class PreactCollector {
                 );
             }
             if (src !== entry.src) {
-                this.map.set(id, { event: entry.event, src, ownerPrefix: entry.ownerPrefix });
+                this.map.set(id, { src, event: entry.event, ownerPrefix: entry.ownerPrefix, loopContext: entry.loopContext });
             }
         }
     }
@@ -384,36 +424,31 @@ export class PreactCollector {
      * @returns The js section as a string.
      */
     getHandlerReattachmentSectionForPrefix(ownerPrefix: string | undefined): string {
-        const filtered: Map<string, SerializedHandlerEntry> = new Map(
-            [...this.map.entries()]
-                // eslint-disable-next-line unusedImports/no-unused-vars
-                .filter(([_, e]) => e.ownerPrefix === ownerPrefix)
-                .map(([id, e]) => [id, { event: e.event, src: e.src }])
-        );
-        if (!filtered.size) {
+        const filtered: [string, HandlerEntry][] = [...this.map.entries()]
+            // eslint-disable-next-line unusedImports/no-unused-vars
+            .filter(([_, e]) => e.ownerPrefix === ownerPrefix);
+
+        if (!filtered.length) {
             return '';
         }
 
-        const json: string = JSON.stringify(Object.fromEntries(filtered), undefined, 4)
-            .split('\n')
-            .map((l, i) => i === 0 ? l : '            ' + l)
-            .join('\n');
+        const entries: string[] = filtered.map(([id, e]) => {
+            const safeSrc: string = e.src.replaceAll('</script>', '\\u003c/script>');
+            const fnExpr: string = e.loopContext
+                ? `((${e.loopContext.varName}) => (${safeSrc}))(${this.serializeLoopValue(e.loopContext.value)})`
+                : `(${safeSrc})`;
+            return `                ${JsonUtilities.stringify(id)}: { event: ${JsonUtilities.stringify(e.event)}, fn: ${fnExpr} }`;
+        });
 
         return [
             '    (function() {',
             '        try {',
-            `            const map = ${json};`,
+            '            const map = {',
+            entries.join(',\n'),
+            '            };',
             '            for (const id of Object.keys(map)) {',
             '                const info = map[id];',
-            '                const { event, src } = info;',
-            '                let fn;',
-            '                try {',
-            '                    fn = eval("(" + src + ")");',
-            '                }',
-            '                catch (error) {',
-            '                    console.error("ssr handler compile error", id, error);',
-            '                    continue;',
-            '                }',
+            '                const { event, fn } = info;',
             `                for (const el of document.querySelectorAll('[${HANDLERS_DIRECTIVE}]')) {`,
             `                    const raw = el.getAttribute('${HANDLERS_DIRECTIVE}');`,
             '                    if (!raw) { continue; }',
@@ -442,13 +477,33 @@ export class PreactCollector {
         return `${base}${count}_`;
     }
 
-    private registerHandler(fn: Function, event: string, ownerPrefix: string | undefined): string {
+    private registerHandler(
+        fn: Function,
+        event: string,
+        ownerPrefix: string | undefined,
+        loopContext: LoopContext | undefined
+    ): string {
         const src: string = fn.toString().replaceAll('</script>', '\\u003c/script>');
-        const result: DelegateResult | undefined = this.extractDelegateName(src);
         const id: string = `h${++this.seq}`;
+
+        // If there's a loop context we must keep the full source so the IIFE
+        // can pass the captured value through. extractDelegateName would discard
+        // the argument (e.g. tab.id) and only keep the callee name.
+        const srcDelegateName: DelegateResult | undefined = this.extractDelegateName(src);
+        const storedSrc: string = loopContext
+            ? src
+            : srcDelegateName?.kind === 'simple'
+                ? srcDelegateName.name
+                : src;
+
         // For simple delegations store just the name; for complex expressions store the full src.
         // Both are renamed uniformly by applyRenames().
-        this.map.set(id, { event, src: result?.kind === 'simple' ? result.name : src, ownerPrefix });
+        this.map.set(id, {
+            event,
+            ownerPrefix,
+            loopContext,
+            src: storedSrc
+        });
         return id;
     }
 
@@ -671,4 +726,33 @@ export class PreactCollector {
     private isVNode(node: unknown): node is VNode {
         return !(typeof node !== 'object' || !node || !('props' in node));
     }
+
+    private extractFirstParamName(fnSrc: string): string | undefined {
+        const s: string = fnSrc.trim().replace(/^async\s+/, '');
+        // (tab) => ... or (tab, index) => ...
+        const parenMatch: RegExpMatchArray | null = s.match(/^\(([^)]*)\)/);
+        if (parenMatch) {
+            const param: string = parenMatch[1].trim().split(',')[0].trim();
+            return param || undefined;
+        }
+        // tab => ...
+        const bareMatch: RegExpMatchArray | null = s.match(/^([$_a-z]\w*)\s*=>/i);
+        return bareMatch ? bareMatch[1] : undefined;
+    }
+
+    private serializeLoopValue(value: unknown): string {
+        if (typeof value === 'function') {
+            return value.toString();
+        }
+        if (Array.isArray(value)) {
+            return `[${value.map(v => this.serializeLoopValue(v)).join(', ')}]`;
+        }
+        if (value !== null && typeof value === 'object') {
+            const entries: string[] = Object.entries(value).map(
+                ([k, v]) => `${JsonUtilities.stringify(k)}: ${this.serializeLoopValue(v)}`
+            );
+            return `{ ${entries.join(', ')} }`;
+        }
+        return JsonUtilities.stringify(value);
+    }
 }

package/src/preact/generate-client-scripts.function.ts

@@ -1,22 +1,21 @@
 import { createRequire } from 'node:module';
 
-import { FsUtilities, Path } from '../utilities/fs.utilities';
+import { FsUtilities, FsPath } from '../utilities/fs.utilities';
+import { JsonUtilities } from '../utilities/json.utilities';
 import { toKebabCase } from '../utilities/to-kebab-case.function';
 
+const defaultGlobs: string[] = ['src/templates/pages/**/*.tsx', 'src/templates/components/**/*.tsx'];
+
 /**
- * Scans compiled JS files in srcDir for ?client imports, resolves their browser
- * distributions, and writes them to outputDir with predictable names.
+ * Scans compiled JS files in the given template files for ?client imports, resolves their browser
+ * distributions, and writes them to assets/public/vendor with predictable names.
  * Call this from your build plugin before compilation completes.
- * @example
- * // webpack plugin:
- * compiler.hooks.beforeCompile.tapPromise('ZibriClientScripts', () =>
- *     generateClientScripts({ srcDir: './dist', outputDir: './assets' })
- * );
+ * @param glob - The glob(s) to find your .tsx templates from.
  */
-export async function generateClientScripts(): Promise<void> {
+export async function generateClientScripts(glob: string | string[] = defaultGlobs): Promise<void> {
     const allPackages: Set<string> = new Set<string>();
     const packagesByComponent: Record<string, string[]> = {};
-    const templateFiles: Path[] = await FsUtilities.glob('src/templates/**/*.tsx');
+    const templateFiles: FsPath[] = await FsUtilities.glob(glob);
 
     await Promise.all(templateFiles.map(async f => {
         const src: string = await FsUtilities.readFile(f);
@@ -36,12 +35,12 @@ export async function generateClientScripts(): Promise<void> {
         }
     }));
 
-    const vendorPath: Path = FsUtilities.getPath('assets', 'public', 'vendor');
+    const vendorPath: FsPath = FsUtilities.getPath('assets', 'public', 'vendor');
     await FsUtilities.mkdir(vendorPath);
 
     await Promise.all([...allPackages].map(async pkg => {
         const code: string = await resolveBrowserDist(pkg);
-        const outFile: Path = FsUtilities.getPath(vendorPath, pkgToFilename(pkg));
+        const outFile: FsPath = FsUtilities.getPath(vendorPath, pkgToFilename(pkg));
         if (await FsUtilities.exists(outFile)) {
             const oldFileContent: string = await FsUtilities.readFile(outFile);
             if (oldFileContent.trim() === code.trim()) {
@@ -51,11 +50,11 @@ export async function generateClientScripts(): Promise<void> {
         await FsUtilities.upsertFile(outFile, code);
     }));
 
-    const manifestFile: Path = FsUtilities.getPath(vendorPath, 'manifest.json');
+    const manifestFile: FsPath = FsUtilities.getPath(vendorPath, 'manifest.json');
     const sorted: Record<string, string[]> = Object.fromEntries(
         Object.entries(packagesByComponent).sort(([a], [b]) => a.localeCompare(b))
     );
-    const newManifestContent: string = JSON.stringify(sorted, undefined, 4);
+    const newManifestContent: string = JsonUtilities.stringify(sorted, undefined, 4);
     if (await FsUtilities.exists(manifestFile)) {
         const oldFileContent: string = await FsUtilities.readFile(manifestFile);
         if (oldFileContent.trim() === newManifestContent.trim()) {
@@ -93,8 +92,8 @@ async function resolveBrowserDist(pkg: string): Promise<string> {
     // eslint-disable-next-line sonar/no-duplicate-string
     const userRequire: NodeJS.Require = createRequire(FsUtilities.getPath(process.cwd(), 'package.json'));
     const pkgDir: string = await findPackageDir(pkg, userRequire);
-    // eslint-disable-next-line typescript/no-unsafe-assignment
-    const pkgJson: Record<string, unknown> = JSON.parse(await FsUtilities.readFile(FsUtilities.getPath(pkgDir, 'package.json')));
+
+    const pkgJson: Record<string, unknown> = JsonUtilities.parse(await FsUtilities.readFile(FsUtilities.getPath(pkgDir, 'package.json')));
 
     const browserEntry: string | undefined = resolveBrowserEntry(pkgJson);
     if (!browserEntry) {
@@ -119,13 +118,13 @@ async function findPackageDir(pkg: string, userRequire: NodeJS.Require): Promise
     }
 
     // Fallback — resolve main entry and walk up to find the package root
-    const main: Path = FsUtilities.getPath(userRequire.resolve(pkg));
+    const main: FsPath = FsUtilities.getPath(userRequire.resolve(pkg));
     let dir: string = FsUtilities.dirName(main);
     while (true) {
-        const candidate: Path = FsUtilities.getPath(dir, 'package.json');
+        const candidate: FsPath = FsUtilities.getPath(dir, 'package.json');
         try {
-            // eslint-disable-next-line typescript/no-unsafe-assignment
-            const json: Record<string, unknown> = JSON.parse(await FsUtilities.readFile(candidate));
+
+            const json: Record<string, unknown> = JsonUtilities.parse(await FsUtilities.readFile(candidate));
             if (json['name'] === pkg) {
                 return dir;
             }

package/src/preact/preact-email-component.model.ts

@@ -0,0 +1,6 @@
+import { PreactComponent } from './preact-component.model';
+
+/**
+ * Definition of a valid preact email component that can be rendered by zibri.
+ */
+export type PreactEmailComponent<T = {}> = PreactComponent<T>;

package/src/preact/preact.utilities.ts

@@ -1,13 +1,19 @@
-import { VNode } from 'preact';
+import { JSX, VNode } from 'preact';
 import renderToString from 'preact-render-to-string';
 
 import { NestedComponentEntry, PreactCollector } from './collector';
 import { pkgToFilename } from './generate-client-scripts.function';
 import { preactHooks } from './hooks/hooks';
 import { PreactComponent } from './preact-component.model';
+import { PreactEmailComponent } from './preact-email-component.model';
 import { findStringEnd, stringAwareReplace } from './string-aware-replace.function';
-import { HtmlResponse } from '../parsing/html/html-response.model';
-import { FsUtilities, Path } from '../utilities/fs.utilities';
+import { HttpRequestContext } from '../context/request/http-request.context';
+import { ZIBRI_REQUEST_CONTEXT_TOKENS } from '../context/request/request-context-token.model';
+import { WebsocketRequestContext } from '../context/request/websocket-request.context';
+import { ZIBRI_DI_TOKENS } from '../di/default/zibri-di-tokens.default';
+import { inject } from '../di/inject.function';
+import { FsUtilities, FsPath } from '../utilities/fs.utilities';
+import { JsonUtilities } from '../utilities/json.utilities';
 import { ObjectUtilities } from '../utilities/object.utilities';
 
 /**
@@ -45,21 +51,46 @@ export abstract class PreactUtilities {
     private static clientManifest: Record<string, string[]> | undefined;
 
     /**
-     * Render a component and inline the component "body" (everything before the top-level return)
-     * into the same <script> tag that also contains the handler bootstrap.
+     * Renders the given component as an email, so no script injection is happening.
      * @example
      * ```ts
-     * PreactUtilities.render(TestPage, { initialCount: 1 });
+     * PreactUtilities.renderEmail(TestEmail, { recipient: 'James Smith' });
+     * ```
+     * @param args - Component and props.
+     * @param args.component - The function component to render.
+     * @param args.props - The properties to pass into the component.
+     * @returns The fully rendered html.
+     */
+    static renderEmail<T = {}>(
+        ...args: keyof T extends never
+            ? [component: PreactEmailComponent<T>]
+            : [component: PreactEmailComponent<T>, props: T]
+    ): string {
+        const [component, props] = args;
+        const node: JSX.Element = component(props ?? ({} as T));
+
+        return [
+            '<!DOCTYPE html>',
+            this.unescapeConditionalComments(renderToString(node))
+        ].join('\n');
+    }
+
+    /**
+     * Renders the given component as a page with the component "body" (everything before the top-level return)
+     * inlined into the same <script> tag that also contains the handler bootstrap.
+     * @example
+     * ```ts
+     * PreactUtilities.renderPage(TestPage, { initialCount: 1 });
      * ```
      * @param args - Component and props.
      * @param args.component - The function component to render.
      * @param args.props - The properties to pass into the component.
      * @returns The fully rendered html string, with the body and any handlers attached in a script tag.
      */
-    static async render<P = {}>(
-        ...args: keyof P extends never
-            ? [component: PreactComponent<P>]
-            : [component: PreactComponent<P>, props: P]
+    static async renderPage<T = {}>(
+        ...args: keyof T extends never
+            ? [component: PreactComponent<T>]
+            : [component: PreactComponent<T>, props: T]
     ): Promise<string> {
         const [component, props] = args;
         // ---------- extract component source and prepare inlined script ----------
@@ -74,7 +105,7 @@ export abstract class PreactUtilities {
         const propsSection: string = this.getInlinedPropsSection(paramsText, props ?? {});
 
         const collector: PreactCollector = new PreactCollector();
-        const rootVNode: VNode = component(props ?? ({} as P));
+        const rootVNode: VNode = component(props ?? ({} as T));
 
         if (rootVNode instanceof Promise) {
             throw new Error(
@@ -204,41 +235,48 @@ export abstract class PreactUtilities {
                 .join('\n')
                 .replaceAll('</script>', '\\u003c/script>');
 
+            const context: HttpRequestContext | WebsocketRequestContext | undefined = inject(ZIBRI_DI_TOKENS.CURRENT_REQUEST_CONTEXT);
+            const nonce: string | undefined = await context?.get(ZIBRI_REQUEST_CONTEXT_TOKENS.NONCE);
+            const nonceAttr: string = nonce ? ` nonce="${nonce}"` : '';
             if (html.includes('</body>')) {
                 html = html.replace(
                     '</body>',
-                    `<script>\n${scriptContent}\n</script>\n</body>`
+                    `<script ${nonceAttr}>\n${scriptContent}\n</script>\n</body>`
                 );
             }
             else {
-                html += `\n<script>\n${scriptContent}\n</script>`;
+                html += `\n<script ${nonceAttr}>\n${scriptContent}\n</script>`;
             }
         }
 
         return '<!DOCTYPE html>\n' + html;
     }
 
-    /**
-     * Render a component and inline the component "body" (everything before the top-level return)
-     * into the same <script> tag that also contains the handler bootstrap. Then wrap it into a html response..
-     * @example
-     * ```ts
-     * PreactUtilities.renderResponse(TestPage, { initialCount: 1 });
-     * ```
-     * @param args - Component and props.
-     * @param args.component - The function component to render.
-     * @param args.props - The properties to pass into the component.
-     * @returns The fully rendered html as a ready to return html response.
-     */
-    static async renderResponse<P = {}>(
-        ...args: keyof P extends never
-            ? [component: PreactComponent<P>]
-            : [component: PreactComponent<P>, props: P]
-    ): Promise<HtmlResponse> {
-        const [component, props] = args;
-        // eslint-disable-next-line typescript/no-explicit-any
-        const htmlString: string = await this.render<any>(component, props);
-        return HtmlResponse.fromString(htmlString);
+    private static unescapeConditionalComments(html: string): string {
+        let result: string = html;
+        // Standard MSO blocks — both opening and closing are escaped
+        // &lt;!--[if ...]>...&lt;![endif]-->
+        result = result.replaceAll(
+            /&lt;!--\[if ([^\]]*)]>([\S\s]*?)&lt;!\[endif]-->/g,
+            (_match, condition, inner: string) => {
+                const unescaped: string = inner
+                    .replaceAll('&lt;', '<')
+                    .replaceAll('&gt;', '>')
+                    .replaceAll('&quot;', '"')
+                    .replaceAll('&amp;', '&');
+                return `<!--[if ${condition}]>${unescaped}<![endif]-->`;
+            }
+        );
+
+        // "Show in non-MSO" open: &lt;!--[if !mso]>&lt;!-->
+        result = result.replaceAll(
+            /&lt;!--\[if ([^\]]*)]>&lt;!-->/g,
+            '<!--[if $1]><!-->'
+        );
+
+        // "Show in non-MSO" close: <!--<![endif]--> (already unescaped by preact, no change needed)
+
+        return result;
     }
 
     private static resolveInAncestors(
@@ -286,9 +324,8 @@ export abstract class PreactUtilities {
             return this.clientManifest;
         }
         try {
-            const manifestPath: Path = FsUtilities.getPath(process.cwd(), 'assets', 'public', 'vendor', 'manifest.json');
-            // eslint-disable-next-line typescript/no-unsafe-assignment
-            this.clientManifest = JSON.parse(await FsUtilities.readFile(manifestPath));
+            const manifestPath: FsPath = FsUtilities.getPath(process.cwd(), 'assets', 'public', 'vendor', 'manifest.json');
+            this.clientManifest = JsonUtilities.parse(await FsUtilities.readFile(manifestPath));
         }
         catch {
             this.clientManifest = {};
@@ -707,7 +744,7 @@ export abstract class PreactUtilities {
             }
         }
 
-        const safe: string = JSON.stringify(serializableProps, undefined, 4)
+        const safe: string = JsonUtilities.stringify(serializableProps, undefined, 4)
             .split('\n')
             .map((l, i) => i === 0 ? l : '    ' + l)
             .join('\n')
@@ -993,8 +1030,7 @@ export abstract class PreactUtilities {
 
             for (const [key, value] of ObjectUtilities.entries(propBindings)) {
                 if (key.startsWith('__propsObj_')) {
-                    // eslint-disable-next-line typescript/no-unsafe-assignment
-                    const parsed: Record<string, string> = JSON.parse(value);
+                    const parsed: Record<string, string> = JsonUtilities.parse(value);
                     for (const [propName, resolvedName] of ObjectUtilities.entries(parsed)) {
                         entries.push(`${propName}: ${resolveValue(resolvedName)}`);
                     }
@@ -1013,7 +1049,7 @@ export abstract class PreactUtilities {
             }
 
             for (const [propName, val] of ObjectUtilities.entries(propValues)) {
-                entries.push(`${propName}: ${JSON.stringify(val)}`);
+                entries.push(`${propName}: ${JsonUtilities.stringify(val)}`);
             }
 
             if (entries.length) {
@@ -1053,7 +1089,7 @@ export abstract class PreactUtilities {
                 const propName: string = destructureRenameMap.get(localName) ?? localName;
 
                 if (propName in propValues) {
-                    lines.push(`    const ${prefix}${localName} = ${JSON.stringify(propValues[propName])};`);
+                    lines.push(`    const ${prefix}${localName} = ${JsonUtilities.stringify(propValues[propName])};`);
                     continue;
                 }
                 if (defaultSrc !== undefined) {

package/src/preact/validate-email-templates.function.ts

@@ -0,0 +1,8 @@
+// TODO
+
+/**
+ * Validates that all email templates have a valid structure.
+ */
+export function validateEmailTemplates(): void {
+
+}

package/src/rate-limiting/rate-limiter.ts

@@ -52,6 +52,16 @@ export class RateLimiter {
         return new this(max, Ms.SECOND);
     }
 
+    /**
+     * Creates a rate limiter with a custom interval.
+     * @param max - The maximum available per the given interval.
+     * @param intervalInMs - The interval in ms.
+     * @returns The RateLimiter.
+     */
+    static custom(max: number, intervalInMs: number): RateLimiter {
+        return new this(max, intervalInMs);
+    }
+
     private refill(): void {
         const now: number = Date.now();
         const elapsedMs: number = now - this.lastRefill;

package/src/routing/decorators/body.decorator.ts

@@ -7,11 +7,12 @@ import { Newable } from '../../types/newable.type';
 import { OmitStrict } from '../../types/omit-strict.type';
 import { MetadataUtilities } from '../../utilities/metadata.utilities';
 import { Ms } from '../../utilities/ms';
+import { BigNumber } from '../../utilities/number.utilities';
 
 /**
  * Base metadata shared by all possible http request body properties.
  */
-type BaseBodyMetadata = OmitStrict<BasePropertyMetadata, 'excludeFromChangeSets'> & {
+type BaseBodyMetadata = OmitStrict<BasePropertyMetadata, 'excludeFromChangeSets' | 'exclude'> & {
     /**
      * The class that defines the structure of the body.
      */

package/src/routing/decorators/controller.decorator.ts

@@ -1,18 +1,38 @@
 import { GlobalRegistry } from '../../global/global-registry';
 import { Newable } from '../../types/newable.type';
+import { OmitStrict } from '../../types/omit-strict.type';
 import { MetadataUtilities } from '../../utilities/metadata.utilities';
 import { Route } from '../controller-route-configuration.model';
 
+/**
+ * Data of a controller.
+ */
+export type ControllerData = {
+    /**
+     * The base route of the controller. Any endpoints inside this class will be prefixed with this.
+     */
+    baseRoute: Route,
+    /**
+     * Whether or not this controller is allowed to exist without being registered in the application.
+     */
+    allowOrphan: boolean
+};
+
 /**
  * Marks a controller class to be registered under the provided base route.
  * @param baseRoute - The base route of the controller. Any endpoints inside this class will be prefixed with this.
+ * @param options - Additional options for the controller.
  */
-export function Controller(baseRoute: Route): ClassDecorator {
+export function Controller(baseRoute: Route, options: Partial<OmitStrict<ControllerData, 'baseRoute'>> = {}): ClassDecorator {
+    const { allowOrphan = false } = options;
     return target => {
         // eslint-disable-next-line unicorn/error-message
         const stack: string = new Error().stack ?? '';
         MetadataUtilities.setFilePath(target, stack);
-        MetadataUtilities.setControllerBaseRoute(target, baseRoute);
+        MetadataUtilities.setControllerData(target, {
+            baseRoute,
+            allowOrphan
+        });
         GlobalRegistry.injectables.push({
             token: target as unknown as Newable<unknown>,
             useClass: target as unknown as Newable<unknown>