ts-packages 1.0.0 → 2.0.0

package/packages/server-utils/dist/cjs/types/index.d.ts

@@ -0,0 +1,87 @@
+import type express from 'express';
+export interface CorsOptions {
+    origin?: string | string[] | boolean | RegExp | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
+    methods?: string | string[];
+    allowedHeaders?: string | string[];
+    exposedHeaders?: string | string[];
+    credentials?: boolean;
+    maxAge?: number;
+    preflightContinue?: boolean;
+    optionsSuccessStatus?: number;
+}
+export interface ServerConfig {
+    port?: number;
+    cors?: boolean | CorsOptions;
+    helmet?: boolean;
+    json?: boolean;
+    cookieParser?: boolean;
+    customMiddleware?: express.RequestHandler[];
+    healthCheck?: boolean | string;
+    gracefulShutdown?: boolean;
+    socketIO?: SocketIOConfig;
+    periodicHealthCheck?: PeriodicHealthCheckConfig;
+    name?: string;
+    version?: string;
+    cache?: {
+        enabled?: boolean;
+        adapter?: 'redis' | 'memcache' | 'memory';
+        options?: unknown;
+        defaultTTL?: number;
+    };
+    session?: {
+        enabled?: boolean;
+        cookieName?: string;
+        ttl?: number;
+        cookieOptions?: {
+            path?: string;
+            httpOnly?: boolean;
+            secure?: boolean;
+            sameSite?: 'lax' | 'strict' | 'none';
+        };
+    };
+}
+export interface PeriodicHealthCheckConfig {
+    enabled?: boolean;
+    interval?: number;
+    services?: HealthCheckService[];
+}
+export interface HealthCheckService {
+    name: string;
+    url: string;
+    timeout?: number;
+}
+export interface SocketIOConfig {
+    enabled?: boolean;
+    cors?: boolean | {
+        origin?: string | string[] | boolean;
+        methods?: string[];
+        credentials?: boolean;
+    };
+    onConnection?: (socket: unknown) => void;
+    onDisconnection?: (socket: unknown, reason: string) => void;
+    path?: string;
+}
+export interface HealthCheckConfig {
+    path?: string;
+    customChecks?: HealthCheck[];
+}
+export interface HealthCheck {
+    name: string;
+    check: () => Promise<boolean>;
+}
+export interface GracefulShutdownConfig {
+    timeout?: number;
+    onShutdown?: () => Promise<void>;
+    serverName?: string;
+    serverVersion?: string;
+}
+export interface SocketInstance {
+    id: string;
+    emit: (event: string, data?: unknown) => void;
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+    broadcast: {
+        emit: (event: string, data?: unknown) => void;
+    };
+    disconnect: () => void;
+}
+export type ServerPlugin = (app: express.Application, config: ServerConfig) => void;

package/packages/server-utils/dist/cjs/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/packages/server-utils/dist/cjs/utils/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function getEnv(key: string, defaultValue?: string): string;
+export declare function getEnvNumber(key: string, defaultValue?: number): number;
+export declare function getEnvBoolean(key: string, defaultValue?: boolean): boolean;

package/packages/server-utils/dist/cjs/utils/utils.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEnv = getEnv;
+exports.getEnvNumber = getEnvNumber;
+exports.getEnvBoolean = getEnvBoolean;
+function getEnv(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined) {
+        if (defaultValue === undefined) {
+            throw new Error(`Environment variable ${key} is required`);
+        }
+        return defaultValue;
+    }
+    return value; // empty string allowed
+}
+function getEnvNumber(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined) {
+        if (defaultValue === undefined) {
+            throw new Error(`Environment variable ${key} is required`);
+        }
+        return defaultValue;
+    }
+    const parsed = Number(value);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Environment variable ${key} must be a valid number`);
+    }
+    return parsed;
+}
+function getEnvBoolean(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined) {
+        if (defaultValue === undefined) {
+            throw new Error(`Environment variable ${key} is required`);
+        }
+        return defaultValue;
+    }
+    const normalized = value.toLowerCase();
+    if (normalized !== 'true' && normalized !== 'false') {
+        throw new Error(`Environment variable ${key} must be 'true' or 'false'`);
+    }
+    return normalized === 'true';
+}

package/packages/server-utils/dist/esm/core/health.d.ts

@@ -0,0 +1,5 @@
+import type { Application, RequestHandler } from 'express';
+import type { HealthCheckConfig, ServerPlugin } from '../types';
+export declare function createHealthCheck(config?: HealthCheckConfig): RequestHandler;
+export declare function withHealthCheck(path?: string, config?: HealthCheckConfig): ServerPlugin;
+export declare function addHealthCheck(app: Application, path?: string, config?: HealthCheckConfig): void;

package/packages/server-utils/dist/esm/core/health.js

@@ -0,0 +1,40 @@
+export function createHealthCheck(config = {}) {
+    const { customChecks = [] } = config;
+    return async (_req, res) => {
+        try {
+            const checks = {
+                server: true,
+                timestamp: Date.now(),
+            };
+            // Run custom health checks
+            for (const check of customChecks) {
+                try {
+                    checks[check.name] = await check.check();
+                }
+                catch (_error) {
+                    checks[check.name] = false;
+                }
+            }
+            const isHealthy = Object.values(checks).every((status) => status === true || typeof status === 'number');
+            res.status(isHealthy ? 200 : 503).json({
+                status: isHealthy ? 'healthy' : 'unhealthy',
+                checks,
+            });
+        }
+        catch (_error) {
+            res.status(503).json({
+                status: 'unhealthy',
+                error: 'Health check failed',
+            });
+        }
+    };
+}
+export function withHealthCheck(path = '/health', config = {}) {
+    return (app) => {
+        app.get(path, createHealthCheck(config));
+    };
+}
+// Convenience function for direct use
+export function addHealthCheck(app, path = '/health', config = {}) {
+    app.get(path, createHealthCheck(config));
+}

package/packages/server-utils/dist/esm/core/periodic-health.d.ts

@@ -0,0 +1,11 @@
+import type { PeriodicHealthCheckConfig } from '../types';
+export declare class PeriodicHealthMonitor {
+    private intervals;
+    private config;
+    private serviceName;
+    constructor(config: PeriodicHealthCheckConfig, serviceName: string);
+    start(): void;
+    stop(): void;
+    private checkServiceHealth;
+    getHealthStatus(): Promise<Record<string, boolean>>;
+}

package/packages/server-utils/dist/esm/core/periodic-health.js

@@ -0,0 +1,64 @@
+export class PeriodicHealthMonitor {
+    constructor(config, serviceName) {
+        this.intervals = [];
+        this.config = config;
+        this.serviceName = serviceName;
+    }
+    start() {
+        if (!this.config.enabled || !this.config.services?.length) {
+            return;
+        }
+        const interval = this.config.interval || 30000;
+        this.config.services.forEach((service) => {
+            const intervalId = setInterval(async () => {
+                await this.checkServiceHealth(service);
+            }, interval);
+            this.intervals.push(intervalId);
+        });
+        console.log(`📊 ${this.serviceName}: Periodic health monitoring enabled (${interval}ms interval) for ${this.config.services.length} service(s)`);
+    }
+    stop() {
+        this.intervals.forEach((interval) => clearInterval(interval));
+        this.intervals = [];
+        console.log(`🛑 ${this.serviceName}: Periodic health monitoring stopped`);
+    }
+    async checkServiceHealth(service) {
+        try {
+            const controller = new AbortController();
+            const timeout = service.timeout || 5000;
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const response = await fetch(service.url, {
+                method: 'GET',
+                signal: controller.signal,
+                headers: {
+                    'User-Agent': `${this.serviceName}-health-monitor`,
+                },
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                console.log(`🟢 ${service.name} is healthy`);
+                return true;
+            }
+            else {
+                console.log(`🔴 ${service.name} returned ${response.status}`);
+                return false;
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            console.log(`🔴 ${service.name} health check failed: ${errorMessage}`);
+            return false;
+        }
+    }
+    // Get current health status of all services
+    async getHealthStatus() {
+        if (!this.config.services?.length) {
+            return {};
+        }
+        const results = {};
+        await Promise.all(this.config.services.map(async (service) => {
+            results[service.name] = await this.checkServiceHealth(service);
+        }));
+        return results;
+    }
+}

package/packages/server-utils/dist/esm/core/server.d.ts

@@ -0,0 +1,73 @@
+import { type ICache, SessionStore } from '@naman_deep_singh/cache';
+import type { Server } from 'http';
+import type { Application } from 'express';
+import type { ServerConfig, SocketIOConfig } from '../types';
+export interface GrpcService {
+    service: Record<string, unknown>;
+    implementation: Record<string, (...args: unknown[]) => unknown>;
+}
+export interface RpcMethod {
+    [key: string]: (params: unknown[], callback: (error: Error | null, result?: unknown) => void) => void;
+}
+export interface WebhookConfig {
+    path: string;
+    secret?: string;
+    handler: (payload: Record<string, unknown>, headers: Record<string, string | string[]>) => void | Promise<void>;
+}
+export interface GrpcServerInstance {
+    start(): void;
+    forceShutdown(): void;
+    addService(service: unknown, implementation: unknown): void;
+    bindAsync(address: string, credentials: unknown, callback: () => void): void;
+}
+export interface ServerInstanceConfig extends Required<Omit<ServerConfig, 'socketIO' | 'name' | 'version'>> {
+    name: string;
+    version: string;
+    startTime: Date;
+    socketIO?: SocketIOConfig;
+}
+export interface ServerInstance {
+    app: Application;
+    server?: Server;
+    config: ServerInstanceConfig;
+    start(): Promise<ServerInstance>;
+    stop(): Promise<void>;
+    getInfo(): ServerInfo;
+    addGrpcService(service: Record<string, unknown>, implementation: Record<string, (...args: unknown[]) => unknown>, port?: number): void;
+    addRpcMethods(methods: RpcMethod, path?: string): void;
+    addWebhook(config: WebhookConfig): void;
+    addSocketIO(config?: SocketIOConfig): unknown;
+}
+export interface ServerInfo {
+    name: string;
+    version: string;
+    port: number;
+    uptime: number;
+    status: 'starting' | 'running' | 'stopping' | 'stopped';
+    startTime: Date;
+}
+export declare class ExpressServer implements ServerInstance {
+    app: Application;
+    server?: Server;
+    config: ServerInstanceConfig;
+    cache?: ICache<unknown>;
+    sessionStore?: SessionStore | undefined;
+    private status;
+    private grpcServices;
+    private grpcServer?;
+    private rpcMethods;
+    private socketIO?;
+    private healthMonitor?;
+    constructor(name?: string, version?: string, config?: ServerConfig);
+    private setupMiddleware;
+    private setupCacheAndSession;
+    private setupPeriodicHealthMonitoring;
+    start(): Promise<ServerInstance>;
+    stop(): Promise<void>;
+    getInfo(): ServerInfo;
+    addGrpcService(service: Record<string, unknown>, implementation: Record<string, (...args: unknown[]) => unknown>, port?: number): void;
+    addRpcMethods(methods: RpcMethod, path?: string): void;
+    addWebhook(config: WebhookConfig): void;
+    addSocketIO(config?: SocketIOConfig): unknown;
+}
+export declare function createServer(name?: string, version?: string, config?: ServerConfig): ServerInstance;