@privateaim/server-kit 0.8.20 → 0.8.22

package/src/core/component/caller/compound/module.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import type { ObjectLiteral } from '../../../../type';
+import type { ComponentEventMap } from '../../type';
+import type { ComponentCaller, ComponentCallerPayload } from '../types';
+
+export class CompoundComponentCaller<
+    EventMap extends ComponentEventMap = ComponentEventMap,
+    Metadata extends ObjectLiteral = ObjectLiteral,
+> implements ComponentCaller<EventMap, Metadata> {
+    protected callers : ComponentCaller<EventMap, Metadata>[];
+
+    constructor(callers: ComponentCaller<EventMap, Metadata>[]) {
+        this.callers = callers;
+    }
+
+    async call<Key extends keyof ComponentEventMap>(
+        key: Key & string,
+        ...payload: ComponentCallerPayload<ComponentEventMap[Key], Metadata>
+    ): Promise<void> {
+        const [data, metadata] = payload;
+
+        for (let i = 0; i < this.callers.length; i++) {
+            const caller = this.callers[i];
+
+            try {
+                await caller.call(key, data, metadata);
+
+                return;
+            } catch (e) {
+                // continue;
+            }
+        }
+
+        throw new Error('No caller could call component.');
+    }
+}

package/src/core/component/caller/direct/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './module';
+export * from './types';

package/src/core/component/caller/direct/module.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+import { createNanoID } from '@privateaim/kit';
+import type { ComponentCaller, ComponentCallerPayload } from '../types';
+import type { Component, ComponentEventMap, ComponentHandleOptions } from '../../type';
+import type { ComponentDirectCallerResponse } from './types';
+
+export class DirectComponentCaller<
+    EventMap extends ComponentEventMap = ComponentEventMap,
+> implements ComponentCaller<EventMap> {
+    protected component: Component<EventMap>;
+
+    constructor(component : Component<EventMap>) {
+        this.component = component;
+    }
+
+    /**
+     * Call a specific handler and collect all unhandled events.
+     *
+     * @param key
+     * @param payload
+     */
+    async call<Key extends keyof EventMap>(
+        key: Key & string,
+        ...payload: ComponentCallerPayload<EventMap[Key]>
+    ): Promise<void> {
+        const [data, metadata] = payload;
+
+        await this.callAndWait(key, data, metadata);
+    }
+
+    async callWith<Key extends keyof EventMap>(
+        key: Key & string,
+        data: ComponentCallerPayload<EventMap[Key]>[0],
+        metadata: ComponentCallerPayload<EventMap[Key]>[1],
+        options: ComponentHandleOptions<EventMap>,
+    ) {
+        if (!this.component.handle) {
+            throw new Error(`Component ${this.component.constructor.name} can not be called.`);
+        }
+
+        metadata.correlationId = metadata.correlationId || createNanoID();
+
+        await this.component.handle(
+            key,
+            data,
+            metadata,
+            options,
+        );
+    }
+
+    /**
+     * Call a specific handler and collect all unhandled events.
+     *
+     * @param key
+     * @param payload
+     */
+    async callAndWait<Key extends keyof EventMap>(
+        key: Key & string,
+        ...payload: ComponentCallerPayload<EventMap[Key]>
+    ): Promise<ComponentDirectCallerResponse<EventMap>> {
+        const [data, metadata] = payload;
+        if (!this.component.handle) {
+            throw new Error(`Component ${this.component.constructor.name} can not be called.`);
+        }
+
+        const events : ComponentDirectCallerResponse<EventMap> = {};
+
+        const options : ComponentHandleOptions<EventMap> = {
+            handle: (childValue, childContext) => {
+                events[childContext.key] = childValue;
+            },
+        };
+
+        await this.callWith(key, data, metadata, options);
+
+        return events;
+    }
+}

package/src/core/component/caller/direct/types.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+import type { ComponentEventMap } from '../../type';
+
+export type ComponentDirectCallerResponse<
+    EventMap extends ComponentEventMap = ComponentEventMap,
+> = {
+    [K in keyof EventMap]?: EventMap[K][0]
+};

package/src/core/component/caller/index.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './compound';
+export * from './direct';
+export * from './queue-dispatch';
+export * from './queue-worker';
+
+export * from './types';

package/src/core/component/caller/queue-dispatch/index.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './module';

package/src/core/component/caller/queue-dispatch/module.ts

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+import type { ComponentEventMap } from '../../type';
+import type { ComponentCaller, ComponentCallerPayload } from '../types';
+import { buildQueueRouterPublishPayload, isQueueRouterUsable, useQueueRouter } from '../../../queue-router';
+import { useLogger } from '../../../../services';
+import type { QueueDispatchComponentCallerOptions } from './types';
+
+export class QueueDispatchComponentCaller<
+    EventMap extends ComponentEventMap = ComponentEventMap,
+> implements ComponentCaller<EventMap> {
+    protected options : QueueDispatchComponentCallerOptions;
+
+    constructor(options: QueueDispatchComponentCallerOptions) {
+        this.options = options;
+    }
+
+    async call<K extends keyof EventMap>(
+        type: K & string,
+        ...payload: ComponentCallerPayload<EventMap[K]>
+    ): Promise<void> {
+        const [data, metadata] = payload;
+
+        if (!isQueueRouterUsable()) {
+            useLogger().warn(`Can not publish ${type} event.`);
+            return;
+        }
+
+        const client = useQueueRouter();
+        await client.publish(
+            buildQueueRouterPublishPayload({
+                type,
+                data,
+                metadata: {
+                    ...metadata,
+                    routing: this.options.queue,
+                },
+            }),
+            {
+                logging: this.options.logging ?? true,
+            },
+        );
+    }
+}

package/src/core/component/caller/queue-dispatch/types.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+import type { QueueRouterRouting } from '../../../queue-router';
+
+export type QueueDispatchComponentCallerOptions = {
+    queue: QueueRouterRouting,
+    logging?: boolean
+};

package/src/core/component/caller/queue-worker/index.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './module';

package/src/core/component/caller/queue-worker/module.ts

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+import type { Component, ComponentEventMap, ComponentHandleOptions } from '../../type';
+import { buildQueueRouterPublishPayload, isQueueRouterUsable, useQueueRouter } from '../../../queue-router';
+import type { ComponentCaller, ComponentCallerPayload } from '../types';
+import type { QueueSelfComponentCallerOptions } from './types';
+import { useLogger } from '../../../../services';
+
+export class QueueWorkerComponentCaller<
+    EventMap extends ComponentEventMap = ComponentEventMap,
+> implements ComponentCaller<EventMap>, Component<EventMap> {
+    protected component: Component<EventMap>;
+
+    protected options: QueueSelfComponentCallerOptions;
+
+    constructor(component: Component<EventMap>, options: QueueSelfComponentCallerOptions) {
+        this.component = component;
+        this.options = options;
+    }
+
+    async start() {
+        if (!isQueueRouterUsable()) {
+            useLogger().warn(`Can not consume queue for component ${this.component.constructor.name}`);
+            return;
+        }
+
+        const client = useQueueRouter();
+        await client.consumeAny(
+            this.options.consumeQueue,
+            async (payload) => {
+                await this.call(payload.type, payload.data, payload.metadata);
+            },
+        );
+    }
+
+    /**
+     * Call a specific handler and collect all unhandled events.
+     *
+     * @param key
+     * @param payload
+     */
+    async call<Key extends keyof EventMap>(
+        key: Key & string,
+        ...payload: ComponentCallerPayload<EventMap[Key]>
+    ): Promise<void> {
+        const [data, metadata] = payload;
+        if (!this.component.handle) {
+            throw new Error(`Component ${this.component.constructor.name} can not be called.`);
+        }
+
+        const client = useQueueRouter();
+        const options : ComponentHandleOptions<EventMap> = {
+            handle: async (
+                childValue,
+                childContext,
+            ) => {
+                if (this.options.publishQueue) {
+                    /**
+                     *
+                     * publish unhandled requests to publish queue.
+                     */
+                    await client.publish(buildQueueRouterPublishPayload({
+                        type: childContext.key,
+                        data: childValue,
+                        metadata: {
+                            ...(metadata || {}),
+                            ...childContext.metadata,
+                            routing: this.options.publishQueue,
+                        },
+                    }));
+                } else {
+                    useLogger().warn(
+                        `Component ${this.component.constructor.name} event ${childContext.key} could not be handled.`,
+                    );
+                }
+            },
+        };
+
+        await this.component.handle(
+            key,
+            data,
+            metadata,
+            options,
+        );
+    }
+}

package/src/core/component/caller/queue-worker/types.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+import type { QueueRouterRouting } from '../../../queue-router';
+
+export type QueueSelfComponentCallerOptions = {
+    publishQueue?: QueueRouterRouting,
+    consumeQueue: QueueRouterRouting,
+};

package/src/core/component/caller/types.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+import type { ObjectLiteral } from '../../../type';
+import type { ComponentEventMap, ComponentEventMapValue } from '../type';
+
+export type ComponentCallerPayload<
+    EventMapValue extends ComponentEventMapValue = ComponentEventMapValue,
+    Metadata extends ObjectLiteral = ObjectLiteral,
+> = [data: EventMapValue[0], metadata: EventMapValue[1] & Metadata];
+
+export type ComponentCallerFnArgsForMap<
+    EventMap extends ComponentEventMap = ComponentEventMap,
+    Metadata extends ObjectLiteral = ObjectLiteral,
+> = {
+    [K in keyof EventMap]: [
+        key: K,
+        ...ComponentCallerPayload<EventMap[K], Metadata>,
+    ]
+}[keyof EventMap];
+
+export interface ComponentCaller<
+    EventMap extends ComponentEventMap = ComponentEventMap,
+    Metadata extends ObjectLiteral = ObjectLiteral,
+> {
+    call(
+        ...input: ComponentCallerFnArgsForMap<EventMap, Metadata>
+    ) : Promise<void>;
+}

package/src/core/component/error.ts

@@ -8,7 +8,7 @@
 import type { ComponentErrorOptions } from './type';
 
 export class ComponentError extends Error {
-    public code?: string | null;
+    public readonly code?: string | null;
 
     constructor(input: ComponentErrorOptions) {
         super(input.message, { cause: input.cause });

package/src/core/component/handler/index.ts

@@ -5,5 +5,5 @@
  * view the LICENSE file that was distributed with this source code.
  */
 
-export * from './module';
+export * from './check';
 export * from './types';

package/src/core/component/handler/types.ts

@@ -5,24 +5,26 @@
  * view the LICENSE file that was distributed with this source code.
  */
 
-import type { ObjectLiteral } from '../../../type';
+import type { ComponentEventMap, ComponentHandlerCallFnForMap } from '../type';
 
 export type ComponentHandlerContext<
-    KEY extends string = string,
+    EventMap extends ComponentEventMap = ComponentEventMap,
+    Key extends keyof EventMap = keyof EventMap,
 > = {
-    key: KEY,
-    metadata: ObjectLiteral
+    key: Key & string,
+    metadata: EventMap[Key][1],
+    handle: ComponentHandlerCallFnForMap<EventMap>
 };
 
 export type ComponentHandlerFn<
-    KEY extends string = string,
-    VALUE extends ObjectLiteral = ObjectLiteral,
-> = (value: VALUE, context: ComponentHandlerContext<KEY>) => Promise<void> | void;
+    EventMap extends ComponentEventMap = ComponentEventMap,
+    Key extends keyof EventMap = keyof EventMap,
+> = (value: EventMap[Key][0], context: ComponentHandlerContext<EventMap, Key>) => Promise<void> | void;
 
 export type ComponentHandler<
-    KEY extends string = string,
-    VALUE extends ObjectLiteral = ObjectLiteral,
+    EventMap extends ComponentEventMap = ComponentEventMap,
+    Key extends keyof EventMap = keyof EventMap,
 > = {
     initialize?: () => Promise<void> | void;
-    handle: ComponentHandlerFn<KEY, VALUE>
+    handle: ComponentHandlerFn<EventMap, Key>
 };

package/src/core/component/index.ts

@@ -5,7 +5,9 @@
  * view the LICENSE file that was distributed with this source code.
  */
 
+export * from './caller';
 export * from './error';
 export * from './handler';
+export * from './module';
 export * from './helper';
 export * from './type';

package/src/core/component/module.ts

@@ -0,0 +1,158 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import type {
+    Component, ComponentEventMap, ComponentHandleOptions, ComponentHandlers,
+} from './type';
+import type {
+    ComponentHandler, ComponentHandlerContext, ComponentHandlerFn,
+} from './handler';
+
+export abstract class BaseComponent<
+    EventMap extends ComponentEventMap = ComponentEventMap,
+> implements Component<EventMap> {
+    private initializePromise : Promise<void> | undefined;
+
+    protected initialized : boolean;
+
+    protected handlers: ComponentHandlers<EventMap>;
+
+    protected constructor() {
+        this.initializePromise = undefined;
+        this.initialized = false;
+        this.handlers = new Map();
+    }
+
+    mount<Key extends keyof EventMap>(
+        key: Key,
+        fn: ComponentHandler<EventMap, Key> | ComponentHandlerFn<EventMap, Key>
+    ) : void;
+
+    mount(
+        key: '*',
+        fn: ComponentHandler<EventMap> | ComponentHandlerFn<EventMap>
+    ) : void;
+
+    mount(
+        key: PropertyKey,
+        fn: ComponentHandler<EventMap> | ComponentHandlerFn<EventMap>,
+    ) : void {
+        this.handlers.set(key as keyof EventMap, fn);
+    }
+
+    unmount<Key extends keyof EventMap>(key: Key) {
+        this.handlers.delete(key);
+    }
+
+    async initialize() : Promise<void> {
+        if (this.initialized) {
+            return Promise.resolve();
+        }
+
+        if (this.initializePromise) {
+            return this.initializePromise;
+        }
+
+        const promises: Promise<void>[] = [];
+        const keys = Array.from(this.handlers.keys());
+        for (let i = 0; i < keys.length; i++) {
+            const handler = this.handlers.get(keys[i]);
+
+            if (
+                typeof handler !== 'function' &&
+                handler.initialize
+            ) {
+                promises.push(Promise.resolve().then(() => handler.initialize()));
+            }
+        }
+
+        this.initializePromise = new Promise<void>((resolve, reject) => {
+            Promise.all(promises)
+                .then(() => resolve())
+                .catch((err) => reject(err));
+        });
+
+        this.initializePromise.finally(() => {
+            setTimeout(() => {
+                this.initialized = true;
+                this.initializePromise = undefined;
+            }, 0);
+        });
+
+        return this.initializePromise;
+    }
+
+    /**
+     * Handle specific component event.
+     *
+     * @param key
+     * @param data
+     * @param metadata
+     * @param options
+     */
+    async handle<Key extends keyof EventMap>(
+        key: Key & string,
+        data: EventMap[Key][0],
+        metadata: EventMap[Key][1] = {},
+        options: ComponentHandleOptions<EventMap> = {},
+    ) : Promise<void> {
+        await this.initialize();
+
+        const context : ComponentHandlerContext<EventMap, Key> = {
+            key,
+            metadata,
+            handle: (
+                childKey,
+                childData,
+                childMetadata,
+            ) => {
+                this.handle(
+                    childKey as Key & string,
+                    childData as EventMap[Key][0],
+                    {
+                        ...metadata,
+                        ...(childMetadata || {}),
+                    } as EventMap[Key][1],
+                    {
+                        ...options,
+                        ...(options || {}),
+                    },
+                );
+            },
+        };
+
+        let handler = this.handlers.get(key) as ComponentHandler<EventMap, Key> |
+        ComponentHandlerFn<EventMap, Key>;
+
+        if (handler) {
+            if (typeof handler === 'function') {
+                return handler(data, context);
+            }
+
+            return handler.handle(data, context);
+        }
+
+        handler = this.handlers.get('*') as ComponentHandler<EventMap, Key> |
+        ComponentHandlerFn<EventMap, Key>;
+
+        if (handler) {
+            if (typeof handler === 'function') {
+                return handler(data, context);
+            }
+
+            return handler.handle(data, context);
+        }
+
+        if (options.handle) {
+            return options.handle(data, context);
+        }
+
+        return Promise.resolve();
+    }
+
+    abstract start() : Promise<void> | void;
+}