@privateaim/server-kit 0.8.16 → 0.8.18

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@privateaim/server-kit",
-    "version": "0.8.16",
+    "version": "0.8.18",
     "exports": {
         "./package.json": "./package.json",
         ".": {
@@ -29,13 +29,14 @@
     "dependencies": {
         "@ebec/http": "^2.3.0",
         "@isaacs/ttlcache": "^1.4.1",
-        "@privateaim/kit": "^0.8.16",
+        "@privateaim/kit": "^0.8.18",
         "@socket.io/redis-emitter": "^5.1.0",
         "envix": "^1.5.0",
         "hapic": "^2.7.0",
         "singa": "^1.1.0",
         "triple-beam": "^1.4.1",
-        "winston": "^3.17.0"
+        "winston": "^3.17.0",
+        "winston-transport": "^4.9.0"
     },
     "devDependencies": {
         "@authup/core-http-kit": "^1.0.0-beta.27",

package/src/constants.ts

@@ -0,0 +1,12 @@
+/*
+ * 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 enum EnvironmentName {
+    TEST = 'test',
+    DEVELOPMENT = 'development',
+    PRODUCTION = 'production',
+}

package/src/index.ts

@@ -5,6 +5,7 @@
  * view the LICENSE file that was distributed with this source code.
  */
 
+export * from './constants';
 export * from './core';
 export * from './services';
 export * from './type';

package/src/services/entity-event/handlers/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 './redis';
+export * from './socket';

package/src/services/{domain-event → entity-event/handlers}/redis/helpers.ts

@@ -1,15 +1,15 @@
 /*
  * 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.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
  */
 
 function stringify(input: string | string[]) {
     return typeof input === 'string' ? input : input.join('/');
 }
 
-export function buildDomainEventRedisChannel(
+export function buildEntityEventRedisChannel(
     channel: string | string[],
     namespace?: string | string[],
 ) {

package/src/services/{domain-event → entity-event/handlers}/redis/module.ts

@@ -7,22 +7,22 @@
 
 import type { Client } from 'redis-extension';
 import type { DomainEventRecord } from '@privateaim/kit';
-import type { DomainEventPublishOptions, IDomainEventConsumer } from '../types';
-import { transformEventData } from '../utils';
-import { buildDomainEventRedisChannel } from './helpers';
+import type { EntityEventHandleOptions, IEntityEventHandler } from '../../types';
+import { transformEntityEventData } from '../../utils';
+import { buildEntityEventRedisChannel } from './helpers';
 
-export class DomainEventRedisPublisher implements IDomainEventConsumer {
+export class EntityEventRedisHandler implements IEntityEventHandler {
     protected driver : Client;
 
     constructor(client: Client) {
         this.driver = client;
     }
 
-    async consume(ctx: DomainEventPublishOptions) : Promise<void> {
+    async handle(ctx: EntityEventHandleOptions) : Promise<void> {
         const payload : DomainEventRecord = {
-            type: ctx.metadata.domain,
+            type: ctx.metadata.ref_type,
             event: ctx.metadata.event,
-            data: transformEventData(ctx.data),
+            data: transformEntityEventData(ctx.data),
         };
 
         const payloadSerialized = JSON.stringify(payload);
@@ -31,7 +31,7 @@ export class DomainEventRedisPublisher implements IDomainEventConsumer {
         for (let i = 0; i < ctx.destinations.length; i++) {
             const destination = ctx.destinations[i];
 
-            const key = buildDomainEventRedisChannel(
+            const key = buildEntityEventRedisChannel(
                 destination.channel,
                 destination.namespace,
             );

package/src/services/{domain-event → entity-event/handlers}/socket/index.ts

@@ -6,4 +6,3 @@
  */
 
 export * from './module';
-export * from './helpers';

package/src/services/entity-event/handlers/socket/module.ts

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2022-2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import { buildDomainEventFullName } from '@privateaim/kit';
+import { Emitter } from '@socket.io/redis-emitter';
+import type { Client } from 'redis-extension';
+import type { EntityEventHandleOptions, IEntityEventHandler } from '../../types';
+import { transformEntityEventData } from '../../utils';
+
+export class EntityEventSocketHandler implements IEntityEventHandler {
+    protected client : Client;
+
+    constructor(client: Client) {
+        this.client = client;
+    }
+
+    async handle(ctx: EntityEventHandleOptions) : Promise<void> {
+        ctx.data = transformEntityEventData(ctx.data);
+
+        for (let i = 0; i < ctx.destinations.length; i++) {
+            const destination = ctx.destinations[i];
+
+            const namespace = this.buildNamespace(destination.namespace);
+            const roomName = this.buildChannel(destination.channel);
+
+            const fullEventName = buildDomainEventFullName(
+                ctx.metadata.ref_type,
+                ctx.metadata.event,
+            );
+
+            const emitter = new Emitter(this.client, {}, namespace);
+
+            emitter
+                .in(roomName)
+                .emit(fullEventName, {
+                    data: ctx.data,
+                    meta: {
+                        refType: ctx.metadata.ref_type,
+                        refId: ctx.metadata.ref_id,
+                        event: ctx.metadata.event,
+                        namespace,
+                        roomName,
+                    },
+                });
+        }
+    }
+
+    protected buildNamespace(namespace?: string | string[]) {
+        if (typeof namespace === 'undefined') {
+            return '/';
+        }
+
+        if (typeof namespace === 'string') {
+            return namespace.startsWith('/') ? namespace : `/${namespace}`;
+        }
+
+        return `/${namespace.join('/')}`;
+    }
+
+    protected buildChannel(channel: string | string[]) {
+        if (typeof channel === 'string') {
+            return channel;
+        }
+
+        return channel.join('/');
+    }
+}

package/src/services/{domain-event → entity-event}/index.ts

@@ -6,7 +6,6 @@
  */
 
 export * from './module';
-export * from './redis';
+export * from './handlers';
 export * from './singleton';
-export * from './socket';
 export * from './types';

package/src/services/{domain-event → entity-event}/module.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024-2024.
+ * Copyright (c) 2024-2025.
  * Author Peter Placzek (tada5hi)
  * For the full copyright and license information,
  * view the LICENSE file that was distributed with this source code.
@@ -9,63 +9,67 @@ import type { ObjectLiteral } from '@privateaim/kit';
 import { buildDomainEventFullName } from '@privateaim/kit';
 import { isLoggerUsable, useLogger } from '../logger';
 import type {
-    DomainEventConsumeOptions, DomainEventDestination,
-    DomainEventPublishOptions,
-    IDomainEventConsumer,
-    IDomainEventPublisher,
+    EntityEventDestination,
+    EntityEventHandleOptions,
+    EntityEventPublishOptions,
+    IEntityEventHandler,
+    IEntityEventPublisher,
 } from './types';
 
-export class DomainEventPublisher implements IDomainEventPublisher {
-    protected consumers : Set<IDomainEventConsumer>;
+export class EntityEventPublisher implements IEntityEventPublisher {
+    protected handlers : Set<IEntityEventHandler>;
 
     constructor() {
-        this.consumers = new Set<IDomainEventConsumer>();
+        this.handlers = new Set<IEntityEventHandler>();
     }
 
-    addConsumer(consumer: IDomainEventConsumer) {
-        this.consumers.add(consumer);
+    register(consumer: IEntityEventHandler) {
+        this.handlers.add(consumer);
     }
 
     async safePublish<T extends ObjectLiteral = ObjectLiteral>(
-        ctx: DomainEventPublishOptions<T>,
+        ctx: EntityEventPublishOptions<T>,
     ) : Promise<void> {
         try {
             await this.publish(ctx);
         } catch (e) {
             if (isLoggerUsable()) {
-                useLogger().error(`Publishing event ${buildDomainEventFullName(ctx.metadata.domain, ctx.metadata.event)} failed`);
+                useLogger().error(`Publishing event ${buildDomainEventFullName(ctx.metadata.ref_type, ctx.metadata.event)} failed`);
                 useLogger().error(e);
             }
         }
     }
 
     async publish<T extends ObjectLiteral = ObjectLiteral>(
-        ctx: DomainEventPublishOptions<T>,
+        ctx: EntityEventPublishOptions<T>,
     ) : Promise<void> {
         if (isLoggerUsable()) {
-            useLogger().info(`Publishing event ${buildDomainEventFullName(ctx.metadata.domain, ctx.metadata.event)}`);
+            useLogger()
+                .debug(
+                    `Publishing event ${buildDomainEventFullName(ctx.metadata.ref_type, ctx.metadata.event)}`,
+                );
         }
 
-        let destinations : DomainEventDestination[] = [];
+        let destinations : EntityEventDestination[] = [];
         if (typeof ctx.destinations === 'function') {
             destinations = ctx.destinations(ctx.data);
         } else {
             destinations = ctx.destinations;
         }
 
-        const consumeContext : DomainEventConsumeOptions = {
+        const consumeContext : EntityEventHandleOptions = {
             ...ctx,
             destinations,
         };
 
-        const consumers = this.consumers.values();
+        const handlers = this.handlers.values();
         while (true) {
-            const it = consumers.next();
-            if (it.done) {
+            const handler = handlers.next();
+            if (handler.done) {
                 return;
             }
 
-            await it.value.consume(consumeContext);
+            await (handler.value as IEntityEventHandler).handle(consumeContext);
         }
     }
 }

package/src/services/entity-event/singleton.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import type { Factory } from 'singa';
+import { singa } from 'singa';
+import type { EntityEventPublisher } from './module';
+
+const instance = singa<EntityEventPublisher>({
+    name: 'entityEventPublisher',
+});
+
+export function setEntityEventPublisherFactory(factory: Factory<EntityEventPublisher>) {
+    instance.setFactory(factory);
+}
+
+export function useEntityEventPublisher() {
+    return instance.use();
+}

package/src/services/{domain-event → entity-event}/types.ts

@@ -7,19 +7,21 @@
 
 import type { ObjectLiteral } from '@privateaim/kit';
 
-export type DomainEventDestination = {
+export type EntityEventDestination = {
     namespace?: string | string[],
     channel: string | string[]
 };
 
-export type DomainEventDestinations = DomainEventDestination[];
+export type EntityEventDestinations = EntityEventDestination[];
 
-export type DomainEventDestinationsFn<
+export type EntityEventDestinationsFn<
     T extends ObjectLiteral =ObjectLiteral,
-> = (data: T) => DomainEventDestination[];
+> = (data: T) => EntityEventDestination[];
+
+export type EntityEventMetadata = {
+    ref_type: string,
+    ref_id?: string,
 
-export type DomainEventMetadata = {
-    domain: string,
     event: string,
 
     request_path?: string | null,
@@ -32,28 +34,28 @@ export type DomainEventMetadata = {
     actor_name?: string | null;
 };
 
-export type DomainEventPublishOptions<
+export type EntityEventPublishOptions<
     T extends ObjectLiteral = ObjectLiteral,
 > = {
     data: T,
     dataPrevious?: T,
-    metadata: DomainEventMetadata,
-    destinations: DomainEventDestinations | DomainEventDestinationsFn<T>
+    metadata: EntityEventMetadata,
+    destinations: EntityEventDestinations | EntityEventDestinationsFn<T>
 };
 
-export interface IDomainEventPublisher {
-    publish(ctx: DomainEventPublishOptions) : Promise<void>;
+export interface IEntityEventPublisher {
+    publish(ctx: EntityEventPublishOptions) : Promise<void>;
 }
 
-export type DomainEventConsumeOptions<
+export type EntityEventHandleOptions<
     T extends ObjectLiteral = ObjectLiteral,
 > = {
     data: T,
     dataPrevious?: T,
-    metadata: DomainEventMetadata,
-    destinations: DomainEventDestinations
+    metadata: EntityEventMetadata,
+    destinations: EntityEventDestinations
 };
 
-export interface IDomainEventConsumer {
-    consume(ctx: DomainEventConsumeOptions) : Promise<void>;
+export interface IEntityEventHandler {
+    handle(ctx: EntityEventHandleOptions) : Promise<void>;
 }

package/src/services/{domain-event → entity-event}/utils.ts

@@ -7,7 +7,7 @@
 
 import { isObject } from '@privateaim/kit';
 
-export function transformEventData<T>(input: T) : T {
+export function transformEntityEventData<T>(input: T) : T {
     if (isObject(input)) {
         const keys = Object.keys(input);
         for (let i = 0; i < keys.length; i++) {

package/src/services/index.ts

@@ -9,7 +9,7 @@ export * from './amqp';
 export * from './authup';
 export * from './authup-client-authentication-hook';
 export * from './cache';
-export * from './domain-event';
+export * from './entity-event';
 export * from './logger';
 export * from './redis';
 export * from './vault';

package/src/services/logger/index.ts

@@ -8,3 +8,4 @@
 export * from './module';
 export * from './types';
 export * from './singleton';
+export * from './transports';

package/src/services/logger/module.ts

@@ -5,32 +5,19 @@
  * view the LICENSE file that was distributed with this source code.
  */
 
-import { read } from 'envix';
-import { EnvironmentName } from 'typeorm-extension';
-import type { Logger } from 'winston';
-import { createLogger as create, format, transports } from 'winston';
-import type { LoggerCreateContext, LoggerTransports } from './types';
-
-function toTransports(input: LoggerTransports) {
-    return Array.isArray(input) ? input : [input];
-}
+import { createLogger as create, format } from 'winston';
+import { createLoggerConsoleTransport } from './transports';
+import type {
+    Logger, LoggerCreateContext, LoggerTransport,
+} from './types';
 
 export function createLogger(ctx: LoggerCreateContext = {}) : Logger {
-    let loggerTransports : LoggerTransports;
-    if (read('env') === EnvironmentName.PRODUCTION) {
-        loggerTransports = [
-            new transports.Console({
-                level: 'info',
-            }),
-            ...(ctx.transports ? toTransports(ctx.transports) : []),
-        ];
-    } else {
-        loggerTransports = [
-            new transports.Console({
-                level: 'debug',
-            }),
-            ...(ctx.transports ? toTransports(ctx.transports) : []),
-        ];
+    const transports : LoggerTransport[] = [
+        ...(ctx.transports || []),
+    ];
+
+    if (transports.length === 0) {
+        transports.push(createLoggerConsoleTransport());
     }
 
     return create({
@@ -40,7 +27,7 @@ export function createLogger(ctx: LoggerCreateContext = {}) : Logger {
             format.simple(),
         ),
         level: 'debug',
-        transports: loggerTransports,
+        transports,
         // todo: deeply merge options
         ...(ctx.options || {}),
     });

package/src/services/logger/singleton.ts

@@ -6,7 +6,7 @@
  */
 
 import { type Factory, singa } from 'singa';
-import type { Logger } from 'winston';
+import type { Logger } from './types';
 
 const instance = singa<Logger>({
     name: 'logger',

package/src/services/logger/transports/console.ts

@@ -0,0 +1,27 @@
+/*
+ * 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 { read } from 'envix';
+import { transports } from 'winston';
+import type { TransportStreamOptions } from 'winston-transport';
+import { EnvironmentName } from '../../../constants';
+import type { LoggerTransport } from '../types';
+
+export class LoggerConsoleTransport extends transports.Console {
+    constructor(options: TransportStreamOptions = {}) {
+        super({
+            level: read('env') === EnvironmentName.PRODUCTION ?
+                'info' :
+                'debug',
+            ...options,
+        });
+    }
+}
+
+export function createLoggerConsoleTransport(options: TransportStreamOptions = {}) : LoggerTransport {
+    return new LoggerConsoleTransport(options);
+}

package/src/services/logger/transports/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 './console';
+export * from './memory';

package/src/services/logger/transports/memory.ts

@@ -0,0 +1,18 @@
+/*
+ * 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 Transport from 'winston-transport';
+
+export class LoggerMemoryTransport extends Transport {
+    public items : Record<PropertyKey, any>[] = [];
+
+    log(info: Record<PropertyKey, any>, next: () => void): any {
+        this.items.push(info);
+
+        next();
+    }
+}

package/src/services/logger/types.ts

@@ -5,15 +5,37 @@
  * view the LICENSE file that was distributed with this source code.
  */
 
-import type { Logger, LoggerOptions } from 'winston';
+import type Transport from 'winston-transport';
+import type { LoggerOptions } from 'winston';
 
-export type LoggerTransports = LoggerOptions['transports'];
+export type LoggerTransport = Transport;
 
 export type LoggerCreateContext = {
     options?: Partial<LoggerOptions>,
-    transports?: LoggerTransports
+    transports?: LoggerTransport[]
 };
 
-export type {
-    Logger,
+type LogEntry = {
+    /**
+     * Log message.
+     */
+    message: string | Error,
+    [key: string]: any
+};
+
+export interface LoggerLevelFn<OUT = any> {
+    (message: string, ...meta: Omit<LogEntry, 'message'>[]): OUT,
+    (message: LogEntry): OUT,
+    (message:string): OUT,
+}
+
+export type Logger = {
+    emerg: LoggerLevelFn<Logger>,
+    alert: LoggerLevelFn<Logger>,
+    crit: LoggerLevelFn<Logger>,
+    error: LoggerLevelFn<Logger>,
+    warn: LoggerLevelFn<Logger>,
+    notice: LoggerLevelFn<Logger>,
+    info: LoggerLevelFn<Logger>,
+    debug: LoggerLevelFn<Logger>,
 };

package/test/data/error.ts

@@ -0,0 +1,16 @@
+/*
+ * 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 class CustomError extends Error {
+    code: string;
+
+    constructor(message: string, options: ErrorOptions = {}) {
+        super(message, options);
+
+        this.code = 'foo';
+    }
+}

package/test/unit/logger.spec.ts

@@ -0,0 +1,57 @@
+/*
+ * 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 { createLogger } from 'winston';
+import { LoggerMemoryTransport } from '../../src';
+import { CustomError } from '../data/error';
+
+describe('src/logger', () => {
+    it('should log simple message', () => {
+        const memoryTransport = new LoggerMemoryTransport();
+
+        const logger = createLogger({
+            transports: [
+                memoryTransport,
+            ],
+        });
+
+        logger.info('This is a log message', {
+            foo: 'bar',
+        });
+
+        const [item] = memoryTransport.items;
+        expect(item).toBeDefined();
+        expect(item.message).toEqual('This is a log message');
+        expect(item.foo).toEqual('bar');
+    });
+
+    it('should log error', () => {
+        const memoryTransport = new LoggerMemoryTransport();
+
+        const logger = createLogger({
+            transports: [
+                memoryTransport,
+            ],
+        });
+
+        const error = new CustomError('This is a log message');
+        logger.info({
+            message: error,
+            foo: 'bar',
+        });
+
+        const [item] = memoryTransport.items;
+        expect(item).toBeDefined();
+
+        expect(item.message?.message).toEqual(error.message);
+        expect(item.message?.stack).toEqual(error.stack);
+        expect(item.message?.code).toEqual(error.code);
+
+        expect(item.foo).toEqual('bar');
+        expect(item.code).toBeUndefined();
+    });
+});

package/dist/services/domain-event/index.d.ts

@@ -1,6 +0,0 @@
-export * from './module';
-export * from './redis';
-export * from './singleton';
-export * from './socket';
-export * from './types';
-//# sourceMappingURL=index.d.ts.map