@zyno-io/dk-server-foundation 26.216.430

package/src/helpers/data/objects.ts

@@ -0,0 +1,64 @@
+import { isEqual, isMatch } from 'lodash';
+
+export function objectKeys<T extends object>(object: T): (keyof T)[] {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return Object.keys(object) as any[];
+}
+
+export function objectAssign<T extends object>(object: T, ...values: Partial<T>[]): T {
+    return Object.assign(object, ...values);
+}
+
+type Entries<T> = {
+    [K in keyof T]: [K, T[K]];
+}[keyof T][];
+export function objectEntries<T extends object>(object: T): Entries<T> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return Object.entries(object) as any;
+}
+
+export function extractValues<T extends object, K extends readonly (keyof T)[]>(state: T, fields: K): Pick<T, K[number]> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result: Pick<T, K[number]> = {} as any;
+    for (const key of fields) {
+        if (state[key] !== undefined) {
+            result[key] = state[key];
+        }
+    }
+    return result;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function doesMatch(original: any, updated: any, method?: 'equals' | 'matches'): boolean {
+    if (method === 'matches' && typeof original === 'object' && typeof updated === 'object') {
+        return isMatch(original, updated);
+    }
+    return isEqual(original, updated);
+}
+
+export function extractUpdates<T extends object>(state: T, updates: Partial<T>, fields?: Array<keyof T>, method?: 'equals' | 'matches'): Partial<T> {
+    const result: Partial<T> = {};
+    const updateFields = fields ?? objectKeys(updates);
+    for (const key of updateFields) {
+        if (updates[key] !== undefined && !doesMatch(state[key], updates[key], method)) {
+            result[key] = updates[key];
+        }
+    }
+    return result;
+}
+
+export function patchObject<T extends object>(state: T, updates: Partial<T>, fields?: Array<keyof T>, method?: 'equals' | 'matches'): T {
+    const effectiveUpdates = extractUpdates(state, updates, fields, method);
+    objectAssign(state, effectiveUpdates);
+    return state;
+}
+
+export function extractKV<T, K extends keyof T, V extends keyof T>(arr: T[], keyCol: K, valCol: V) {
+    return arr.reduce(
+        (acc, cur) => {
+            acc[cur[keyCol] as string] = cur[valCol];
+            return acc;
+        },
+        {} as Record<string, T[V]>
+    );
+}

package/src/helpers/data/serialization.ts

@@ -0,0 +1,11 @@
+import { Serializable } from '../../types';
+
+export function toJson(data: Serializable) {
+    return JSON.stringify(data);
+}
+
+export function fromJson<T>(serialized: string): T {
+    return JSON.parse(serialized);
+}
+
+// todo: use the serializer from WsRpc

package/src/helpers/data/transformer.ts

@@ -0,0 +1,54 @@
+import { pick } from 'lodash';
+
+import { asyncMap } from './array';
+
+export class Transformer<I> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private executor?: (input: I[]) => any[] | Promise<any[]>;
+
+    static create<I>(input: I[]): Transformer<I> {
+        return new Transformer(input);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(private input: I[] | Transformer<any>) {}
+
+    apply<O>(fn: (input: I[]) => O[] | Promise<O[]>, shouldApply = true): Transformer<O> {
+        this.executor = shouldApply ? fn : input => input;
+        return new Transformer<O>(this);
+    }
+
+    applyEach<O>(fn: (input: I) => O, shouldApply = true): Transformer<O> {
+        return this.apply(arr => arr.map(fn), shouldApply);
+    }
+
+    applyEachAsync<O>(fn: (input: I) => Promise<O>, shouldApply = true): Transformer<O> {
+        return this.apply(arr => asyncMap(arr, fn), shouldApply);
+    }
+
+    narrow<K extends (keyof I)[]>(...keys: K): Transformer<Pick<I, K[number]>> {
+        return this.apply(input => {
+            return input.map(i => {
+                return pick(i, ...keys) as Pick<I, K[number]>;
+            });
+        });
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async execute(): Promise<any[]> {
+        if (!this.executor) {
+            throw new Error('No executor defined');
+        }
+
+        const input = await this.get();
+        return this.executor(input);
+    }
+
+    async get(): Promise<I[]> {
+        if (this.input instanceof Transformer) {
+            return await this.input.execute();
+        } else {
+            return this.input;
+        }
+    }
+}

package/src/helpers/framework/decorators.ts

@@ -0,0 +1,27 @@
+import { ClassType } from '@deepkit/core';
+
+export function createSymbolAttachmentClassDecorator(aSymbol: symbol) {
+    return (): ClassDecorator => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (target: any) => {
+            target[aSymbol] = aSymbol;
+            return target;
+        };
+    };
+}
+
+const DecoratorRegistry = new Map<symbol, ClassType[]>();
+export function createRegistryClassDecorator(aSymbol: symbol) {
+    return (): ClassDecorator => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (target: any) => {
+            const classes = DecoratorRegistry.get(aSymbol) ?? [];
+            classes.push(target);
+            DecoratorRegistry.set(aSymbol, classes);
+            return target;
+        };
+    };
+}
+export function getRegisteredClasses<T extends ClassType>(aSymbol: symbol): T[] {
+    return (DecoratorRegistry.get(aSymbol) as T[]) ?? [];
+}

package/src/helpers/framework/event.ts

@@ -0,0 +1,11 @@
+import { ClassType } from '@deepkit/core';
+import { eventClass, eventDispatcher } from '@deepkit/event';
+
+export function applyParentEventHandlers(target: ClassType) {
+    const parent = Object.getPrototypeOf(target);
+    const config = eventClass._fetch(parent);
+    config?.listeners.forEach(listener => {
+        eventDispatcher.listen(listener.eventToken, listener.order)(target.prototype, listener.methodName);
+    });
+    return target;
+}

package/src/helpers/framework/injection.ts

@@ -0,0 +1,47 @@
+import { getClassName, isClass } from '@deepkit/core';
+import { InjectorModule, isClassProvider, isExistingProvider, isFactoryProvider, isValueProvider } from '@deepkit/injector';
+import { compact } from 'lodash';
+
+export function getProviderTree(module: InjectorModule) {
+    const result = compact(
+        module.providers.map(p => {
+            if (isClass(p)) {
+                const name = getProviderName(p);
+                if (name) {
+                    return {
+                        name,
+                        module,
+                        provide: p
+                    };
+                }
+            } else if (isValueProvider(p) || isClassProvider(p) || isExistingProvider(p) || isFactoryProvider(p)) {
+                if (p.scope) return null;
+
+                const name = getProviderName(p.provide);
+                if (name) {
+                    return {
+                        name,
+                        module,
+                        provide: p.provide
+                    };
+                }
+            }
+            return null;
+        })
+    );
+
+    for (const anImport of module.imports) {
+        result.push(...getProviderTree(anImport));
+    }
+
+    return result;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getProviderName(p: any) {
+    if (typeof p === 'string') {
+        return p;
+    }
+    const className = getClassName(p);
+    return className !== 'undefined' && className !== 'anonymous class' ? className : null;
+}

package/src/helpers/index.ts

@@ -0,0 +1,34 @@
+// Data manipulation
+export * from './data/array';
+export * from './data/objects';
+export * from './data/serialization';
+export * from './data/transformer';
+
+// Async & concurrency
+export * from './async/context';
+export * from './async/process';
+export * from './async/promise';
+
+// Redis-based features
+export * from './redis/broadcast';
+export * from './redis/cache';
+export * from './redis/mutex';
+export * from './redis/redis';
+
+// I/O operations
+export * from './io/package';
+export * from './io/stream';
+
+// Security & cryptography
+export * from './security/crypto';
+export * from './security/validation';
+
+// Framework helpers
+export * from './framework/event';
+export * from './framework/injection';
+
+// Utilities
+export * from './utils/date';
+export * from './utils/error';
+export * from './utils/jsx';
+export * from './utils/uuid';

package/src/helpers/io/package.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'fs';
+import { memoize } from 'lodash';
+import { join } from 'path';
+import { cwd } from 'process';
+import type { PackageJson } from 'type-fest';
+
+export const getPackageJson: () => PackageJson | undefined = memoize(() => {
+    try {
+        const pkgJsonStr = readFileSync(join(cwd(), 'package.json'), 'utf8');
+        const pkgJson = JSON.parse(pkgJsonStr);
+        return pkgJson;
+        // eslint-disable-next-line unused-imports/no-unused-vars
+    } catch (err) {
+        return undefined;
+    }
+});
+
+export function getPackageVersion() {
+    const pkgJson = getPackageJson();
+    return pkgJson?.version;
+}
+
+export function getPackageName() {
+    const pkgJson = getPackageJson();
+    return pkgJson?.name;
+}

package/src/helpers/io/stream.ts

@@ -0,0 +1,79 @@
+import { unlink } from 'fs/promises';
+import { Readable, Writable } from 'stream';
+
+export class PipeError extends Error {
+    constructor(
+        public readonly cause: Error,
+        public readonly side: 'input' | 'output'
+    ) {
+        super(cause.message);
+    }
+}
+
+export function safePipe(input: Readable, output: Writable) {
+    return new Promise<void>((resolve, reject) => {
+        input.on('close', () => {
+            if (!input.readableEnded) {
+                if (!output.destroyed) output.destroy();
+                reject(new PipeError(new Error('Input stream aborted'), 'input'));
+            }
+        });
+        input.on('error', err => {
+            if (!output.destroyed) output.destroy();
+            reject(new PipeError(err, 'input'));
+        });
+
+        output.on('close', () => {
+            if (!output.writableEnded) {
+                if (!input.destroyed) input.destroy();
+                reject(new PipeError(new Error('Output stream aborted'), 'output'));
+            }
+        });
+        output.on('error', err => {
+            if (!input.destroyed) input.destroy();
+            reject(new PipeError(err, 'output'));
+        });
+
+        output.on('finish', () => {
+            resolve();
+        });
+        input.pipe(output);
+    });
+}
+
+class ResourceTracker {
+    files: string[] = [];
+    streams: (Readable | Writable)[] = [];
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(private reject: (err: any) => void) {}
+
+    addStream(stream: Readable | Writable) {
+        stream.on('error', this.reject);
+        this.streams.push(stream);
+    }
+
+    addFile(file: string) {
+        this.files.push(file);
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function withResourceCleanup<T>(fn: (tracker: ResourceTracker) => Promise<T>, onError?: (err: any) => void) {
+    return new Promise<T>((resolve, reject) => {
+        const tracker = new ResourceTracker(reject);
+        fn(tracker)
+            .then(resolve, err => {
+                onError?.(err);
+                reject(err);
+            })
+            .finally(() => {
+                tracker.files.forEach(file => {
+                    unlink(file).catch(() => {});
+                });
+                tracker.streams.forEach(stream => {
+                    if (!stream.destroyed) stream.destroy();
+                });
+            });
+    });
+}

package/src/helpers/redis/broadcast.ts

@@ -0,0 +1,96 @@
+import { Logger, LoggerInterface } from '@deepkit/logger';
+import { ReceiveType } from '@deepkit/type';
+import { memoize } from 'lodash';
+import { hostname } from 'os';
+
+import { r } from '../../app/resolver';
+import { createRedis } from './redis';
+
+const getSharedBroadcastChannel = memoize(() => {
+    const logger = r(Logger).scoped('Broadcast');
+    const { prefix, client: publishClient } = createRedis('BROADCAST');
+    const { client: subscribeClient } = createRedis('BROADCAST');
+
+    const channel = `${prefix}:broadcast`;
+    const localInstanceKey = `${hostname()}/${process.pid}`;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const listeners = new Map<string, Set<(message: any) => void>>();
+
+    subscribeClient.subscribe(channel);
+    subscribeClient.on('message', (_, message) => {
+        try {
+            const { instanceKey, eventName, data } = JSON.parse(message);
+            if (instanceKey === localInstanceKey) return;
+            const listenersForEvent = listeners.get(eventName);
+            if (!listenersForEvent) return;
+            for (const listener of listenersForEvent) {
+                try {
+                    listener(data);
+                } catch (err) {
+                    logger.error(`Failed to handle broadcast message`, err, { eventName });
+                }
+            }
+        } catch (err) {
+            logger.error('Failed to parse broadcast message', err, message);
+        }
+    });
+
+    return {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        subscribe: (eventName: string, fn: (data: any) => void) => {
+            const listenersForEvent = listeners.get(eventName) ?? new Set();
+            listenersForEvent.add(fn);
+            listeners.set(eventName, listenersForEvent);
+        },
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        publish: (eventName: string, data: any) => {
+            publishClient.publish(channel, JSON.stringify({ instanceKey: localInstanceKey, eventName, data }));
+        }
+    };
+});
+
+export function createBroadcastChannel<T>(eventName: string, _type?: ReceiveType<T>) {
+    const channel = getSharedBroadcastChannel();
+
+    return {
+        subscribe: (fn: (data: T) => void) => {
+            channel.subscribe(eventName, data => {
+                // todo: figure out type validation
+                // assert<T>(data, undefined, type);
+                fn(data);
+            });
+        },
+
+        publish: (data: T) => {
+            channel.publish(eventName, data);
+        }
+    };
+}
+
+interface IDistributedMethodOptions {
+    name: string;
+    logger?: () => LoggerInterface;
+}
+export function createDistributedMethod<T>(options: IDistributedMethodOptions, fn: (data: T) => Promise<void>, type?: ReceiveType<T>) {
+    const getLogger = options.logger ?? (() => r(Logger).scoped(`Distributed:${options.name}`));
+    const channel = createBroadcastChannel(options.name, type);
+
+    const wrappedFn = async (data: T) => {
+        try {
+            await fn(data);
+        } catch (err) {
+            getLogger().error(`Error executing ${options.name} distributed method`, err);
+        }
+    };
+
+    // invoke locally when remotely requested
+    channel.subscribe(wrappedFn);
+
+    // publish & invoke locally when locally executed
+    return (data: T) => {
+        channel.publish(data);
+        return wrappedFn(data);
+    };
+}

package/src/helpers/redis/cache.ts

@@ -0,0 +1,28 @@
+import { memoize } from 'lodash';
+
+import { createRedis } from './redis';
+
+const getRedis = memoize(() => createRedis('CACHE'));
+
+export class Cache {
+    static async get(key: string): Promise<string | null> {
+        const { client, prefix } = getRedis();
+        return client.get(`${prefix}:cache:${key}`);
+    }
+
+    static async set(key: string, value: string, ttl = 60): Promise<void> {
+        const { client, prefix } = getRedis();
+        await client.set(`${prefix}:cache:${key}`, value, 'EX', ttl);
+    }
+
+    static async getObj<T>(key: string): Promise<T | null> {
+        const { client, prefix } = getRedis();
+        const value = await client.get(`${prefix}:cache:${key}`);
+        return value ? JSON.parse(value) : null;
+    }
+
+    static async setObj<T>(key: string, value: T, ttl = 60): Promise<void> {
+        const { client, prefix } = getRedis();
+        await client.set(`${prefix}:cache:${key}`, JSON.stringify(value), 'EX', ttl);
+    }
+}