@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/HealthManager-DUyMIzsZ.d.ts

@@ -0,0 +1,141 @@
+import { M as Middleware } from './index-9_Jzj5jo.js';
+
+/**
+ * Health check status.
+ */
+type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+/**
+ * Result of a single health check.
+ */
+interface CheckResult {
+    name: string;
+    status: HealthStatus;
+    message?: string;
+    meta?: Record<string, unknown>;
+    duration: number;
+}
+/**
+ * Complete health report.
+ */
+interface HealthReport {
+    status: HealthStatus;
+    timestamp: Date;
+    checks: CheckResult[];
+    meta?: Record<string, unknown>;
+}
+/**
+ * Options for registering a health check.
+ */
+interface HealthCheckOptions {
+    /**
+     * Timeout in milliseconds for the check.
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * If true, failure of this check will set overall status to unhealthy.
+     * @default false
+     */
+    critical?: boolean;
+}
+/**
+ * Options for health middleware.
+ */
+interface HealthMiddlewareOptions {
+    /**
+     * Only run these specific checks.
+     */
+    checks?: string[];
+    /**
+     * Include detailed check results.
+     * @default true
+     */
+    detailed?: boolean;
+}
+
+/**
+ * Abstract base class for health checks.
+ */
+declare abstract class HealthCheck {
+    /**
+     * The name of this health check.
+     */
+    abstract readonly name: string;
+    /**
+     * Perform the health check.
+     */
+    abstract check(): Promise<CheckResult>;
+    /**
+     * Create a healthy result.
+     */
+    protected healthy(message?: string, meta?: Record<string, unknown>): CheckResult;
+    /**
+     * Create a degraded result.
+     */
+    protected degraded(message?: string, meta?: Record<string, unknown>): CheckResult;
+    /**
+     * Create an unhealthy result.
+     */
+    protected unhealthy(message?: string, meta?: Record<string, unknown>): CheckResult;
+    /**
+     * Create an unhealthy result from a caught error.
+     */
+    protected handleError(error: unknown, fallbackMessage: string): CheckResult;
+    /**
+     * Create a check result.
+     */
+    private result;
+}
+
+/**
+ * Health check manager.
+ */
+declare class HealthManager {
+    private checks;
+    /**
+     * Register a health check.
+     */
+    register(check: HealthCheck, options?: HealthCheckOptions): this;
+    /**
+     * Unregister a health check.
+     */
+    unregister(name: string): this;
+    /**
+     * Get all registered check names.
+     */
+    getCheckNames(): string[];
+    /**
+     * Run all health checks.
+     */
+    check(): Promise<HealthReport>;
+    /**
+     * Run specific health checks.
+     */
+    checkOnly(names: string[]): Promise<HealthReport>;
+    /**
+     * Get a specific check result.
+     */
+    getCheck(name: string): Promise<CheckResult | null>;
+    /**
+     * Create middleware for health endpoints.
+     */
+    middleware(options?: HealthMiddlewareOptions): Middleware;
+    /**
+     * Run the specified checks.
+     */
+    private runChecks;
+    /**
+     * Run a single check with timeout.
+     */
+    private runCheck;
+    /**
+     * Create a timeout promise.
+     */
+    private timeoutPromise;
+}
+/**
+ * Create a health manager.
+ */
+declare function createHealthManager(): HealthManager;
+
+export { type CheckResult as C, HealthManager as H, HealthCheck as a, type HealthCheckOptions as b, type HealthMiddlewareOptions as c, type HealthReport as d, type HealthStatus as e, createHealthManager as f };

package/dist/I18nManager-Dtgzsf5n.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Translation messages type - nested object structure.
+ */
+type TranslationMessages = {
+    [key: string]: string | TranslationMessages;
+};
+/**
+ * Replacement values for interpolation.
+ */
+type ReplacementValues = Record<string, string | number>;
+/**
+ * Pluralization rule function.
+ */
+type PluralizationRule = (count: number) => number;
+/**
+ * Translation loader interface.
+ */
+interface TranslationLoader {
+    /**
+     * Load translations for a locale.
+     */
+    load(locale: string): Promise<TranslationMessages>;
+    /**
+     * Load translations for a specific namespace.
+     */
+    loadNamespace?(locale: string, namespace: string): Promise<TranslationMessages>;
+    /**
+     * Get available locales.
+     */
+    getAvailableLocales?(): Promise<string[]>;
+}
+/**
+ * Translator options.
+ */
+interface TranslatorOptions {
+    /**
+     * Default locale.
+     */
+    locale: string;
+    /**
+     * Fallback locale when translation is missing.
+     */
+    fallbackLocale?: string;
+    /**
+     * Translation loader.
+     */
+    loader?: TranslationLoader;
+    /**
+     * Preloaded messages.
+     */
+    messages?: Record<string, TranslationMessages>;
+    /**
+     * Custom pluralization rules per locale.
+     */
+    pluralizationRules?: Record<string, PluralizationRule>;
+    /**
+     * Missing key handler.
+     */
+    onMissingKey?: (key: string, locale: string) => string | undefined;
+}
+/**
+ * I18n manager configuration.
+ */
+interface I18nConfig {
+    /**
+     * Default locale.
+     */
+    locale: string;
+    /**
+     * Fallback locale.
+     */
+    fallbackLocale?: string;
+    /**
+     * Path to translation files.
+     */
+    path?: string;
+    /**
+     * Preloaded messages.
+     */
+    messages?: Record<string, TranslationMessages>;
+}
+/**
+ * Translation loader factory.
+ */
+type TranslationLoaderFactory = () => TranslationLoader;
+
+/**
+ * Translator class for handling translations.
+ */
+declare class Translator {
+    private locale;
+    private fallbackLocale;
+    private messages;
+    private pluralizationRules;
+    private onMissingKey?;
+    constructor(options: TranslatorOptions);
+    /**
+     * Translate a key.
+     */
+    t(key: string, replacements?: ReplacementValues): string;
+    /**
+     * Translate a key with count for pluralization.
+     */
+    tc(key: string, count: number, replacements?: ReplacementValues): string;
+    /**
+     * Check if a translation exists.
+     */
+    has(key: string, locale?: string): boolean;
+    /**
+     * Get the current locale.
+     */
+    getLocale(): string;
+    /**
+     * Set the current locale.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the fallback locale.
+     */
+    getFallbackLocale(): string | undefined;
+    /**
+     * Set the fallback locale.
+     */
+    setFallbackLocale(locale: string | undefined): void;
+    /**
+     * Add messages for a locale.
+     */
+    addMessages(locale: string, messages: TranslationMessages): void;
+    /**
+     * Set messages for a locale (replaces existing).
+     */
+    setMessages(locale: string, messages: TranslationMessages): void;
+    /**
+     * Get all messages for a locale.
+     */
+    getMessages(locale?: string): TranslationMessages;
+    /**
+     * Get available locales.
+     */
+    getAvailableLocales(): string[];
+    /**
+     * Set a custom pluralization rule.
+     */
+    setPluralizationRule(locale: string, rule: PluralizationRule): void;
+    /**
+     * Internal translate method.
+     */
+    private translate;
+    /**
+     * Get raw translation without replacements.
+     */
+    private getRawTranslation;
+    /**
+     * Apply replacements to a translation string.
+     */
+    private applyReplacements;
+    /**
+     * Handle missing translation key.
+     */
+    private handleMissingKey;
+    /**
+     * Deep merge messages.
+     */
+    private mergeMessages;
+}
+
+/**
+ * I18n manager for handling multiple locales and translators.
+ */
+declare class I18nManager {
+    private config;
+    private translator;
+    private loader;
+    private loadedLocales;
+    constructor(config: I18nConfig);
+    /**
+     * Translate a key.
+     */
+    t(key: string, replacements?: ReplacementValues): string;
+    /**
+     * Translate a key with count for pluralization.
+     */
+    tc(key: string, count: number, replacements?: ReplacementValues): string;
+    /**
+     * Check if a translation exists.
+     */
+    has(key: string, locale?: string): boolean;
+    /**
+     * Get the current locale.
+     */
+    getLocale(): string;
+    /**
+     * Set the current locale.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the fallback locale.
+     */
+    getFallbackLocale(): string | undefined;
+    /**
+     * Set the fallback locale.
+     */
+    setFallbackLocale(locale: string | undefined): void;
+    /**
+     * Load translations for a locale.
+     */
+    loadLocale(locale: string): Promise<void>;
+    /**
+     * Load translations for multiple locales.
+     */
+    loadLocales(locales: string[]): Promise<void>;
+    /**
+     * Load a specific namespace for a locale.
+     */
+    loadNamespace(locale: string, namespace: string): Promise<void>;
+    /**
+     * Add messages for a locale.
+     */
+    addMessages(locale: string, messages: TranslationMessages): void;
+    /**
+     * Get all messages for a locale.
+     */
+    getMessages(locale?: string): TranslationMessages;
+    /**
+     * Get available locales.
+     */
+    getAvailableLocales(): string[];
+    /**
+     * Get available locales from loader.
+     */
+    getLoaderLocales(): Promise<string[]>;
+    /**
+     * Check if a locale is loaded.
+     */
+    isLocaleLoaded(locale: string): boolean;
+    /**
+     * Get the underlying translator.
+     */
+    getTranslator(): Translator;
+    /**
+     * Set a custom loader.
+     */
+    setLoader(loader: TranslationLoader): void;
+    /**
+     * Create a scoped translator for a specific locale.
+     */
+    forLocale(locale: string): Translator;
+}
+/**
+ * Create a new I18n manager.
+ */
+declare function createI18n(config: I18nConfig): I18nManager;
+/**
+ * Set the global I18n manager.
+ */
+declare function setI18n(i18n: I18nManager): void;
+/**
+ * Get the global I18n manager.
+ */
+declare function getI18n(): I18nManager;
+/**
+ * Translate a key using the global I18n manager.
+ */
+declare function t(key: string, replacements?: ReplacementValues): string;
+/**
+ * Translate a key with count using the global I18n manager.
+ */
+declare function tc(key: string, count: number, replacements?: ReplacementValues): string;
+
+export { I18nManager as I, type PluralizationRule as P, type ReplacementValues as R, type TranslationLoader as T, type I18nConfig as a, type TranslationLoaderFactory as b, type TranslationMessages as c, Translator as d, type TranslatorOptions as e, createI18n as f, getI18n as g, tc as h, setI18n as s, t };

package/dist/LogManager-7mxnkaPM.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Log level types (RFC 5424 severity levels).
+ */
+type LogLevel = 'emergency' | 'alert' | 'critical' | 'error' | 'warning' | 'notice' | 'info' | 'debug';
+/**
+ * Log level priority (lower = more severe).
+ */
+declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+/**
+ * Log context (additional data attached to log entries).
+ */
+type LogContext = Record<string, unknown>;
+/**
+ * Log entry structure.
+ */
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    context: LogContext;
+    timestamp: Date;
+}
+/**
+ * Log channel interface.
+ */
+interface LogChannel {
+    /**
+     * Write a log entry.
+     */
+    log(entry: LogEntry): void | Promise<void>;
+    /**
+     * Close the channel (cleanup resources).
+     */
+    close?(): void | Promise<void>;
+}
+/**
+ * Log channel factory.
+ */
+type LogChannelFactory = (config: LogChannelConfig) => LogChannel;
+/**
+ * Base channel configuration.
+ */
+interface LogChannelConfig {
+    driver: string;
+    level?: LogLevel;
+    [key: string]: unknown;
+}
+/**
+ * Console channel configuration.
+ */
+interface ConsoleChannelConfig extends LogChannelConfig {
+    driver: 'console';
+    colors?: boolean;
+    timestamps?: boolean;
+    format?: 'text' | 'json';
+}
+/**
+ * File channel configuration.
+ */
+interface FileChannelConfig extends LogChannelConfig {
+    driver: 'file';
+    path: string;
+    format?: 'text' | 'json';
+}
+/**
+ * Daily file channel configuration.
+ */
+interface DailyFileChannelConfig extends LogChannelConfig {
+    driver: 'daily';
+    path: string;
+    days?: number;
+    format?: 'text' | 'json';
+}
+/**
+ * Stack channel configuration.
+ */
+interface StackChannelConfig extends LogChannelConfig {
+    driver: 'stack';
+    channels: string[];
+}
+/**
+ * Log manager configuration.
+ */
+interface LogConfig {
+    default: string;
+    channels: Record<string, LogChannelConfig>;
+    /** Keys whose values are replaced with '[FILTERED]' in log context. */
+    filterKeys?: string[];
+    /** Replacement string for filtered values. Default: '[FILTERED]' */
+    filterReplacement?: string;
+}
+/**
+ * Log formatter.
+ */
+interface LogFormatter {
+    format(entry: LogEntry): string;
+}
+
+interface LoggerOptions {
+    /**
+     * Keys whose values should be replaced with the replacement string.
+     * Matching is case-insensitive and recursive.
+     */
+    filterKeys?: string[];
+    /** Replacement string for filtered values. Default: '[FILTERED]' */
+    replacement?: string;
+}
+/**
+ * Recursively replace values of sensitive keys in a log context object.
+ */
+declare function filterSensitiveData(data: Record<string, unknown>, filterKeys: string[], replacement?: string): Record<string, unknown>;
+/**
+ * Logger instance for writing log entries.
+ */
+declare class Logger {
+    private readonly channels;
+    private readonly baseContext;
+    private readonly filterKeys;
+    private readonly replacement;
+    constructor(channels: LogChannel[], context?: LogContext, options?: LoggerOptions);
+    /**
+     * Log at emergency level (system is unusable).
+     */
+    emergency(message: string, context?: LogContext): void;
+    /**
+     * Log at alert level (action must be taken immediately).
+     */
+    alert(message: string, context?: LogContext): void;
+    /**
+     * Log at critical level (critical conditions).
+     */
+    critical(message: string, context?: LogContext): void;
+    /**
+     * Log at error level (error conditions).
+     */
+    error(message: string, context?: LogContext): void;
+    /**
+     * Log at warning level (warning conditions).
+     */
+    warning(message: string, context?: LogContext): void;
+    /**
+     * Alias for warning().
+     */
+    warn(message: string, context?: LogContext): void;
+    /**
+     * Log at notice level (normal but significant conditions).
+     */
+    notice(message: string, context?: LogContext): void;
+    /**
+     * Log at info level (informational messages).
+     */
+    info(message: string, context?: LogContext): void;
+    /**
+     * Log at debug level (debug-level messages).
+     */
+    debug(message: string, context?: LogContext): void;
+    /**
+     * Log a message at the specified level.
+     */
+    log(level: LogLevel, message: string, context?: LogContext): void;
+    /**
+     * Create a new logger with additional context.
+     */
+    withContext(context: LogContext): Logger;
+    /**
+     * Create a child logger with additional context (alias for withContext).
+     */
+    child(context: LogContext): Logger;
+    /**
+     * Close all channels.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Log manager for managing multiple logging channels.
+ *
+ * @example
+ * ```ts
+ * const log = new LogManager({
+ *   default: 'stack',
+ *   channels: {
+ *     console: { driver: 'console', level: 'debug' },
+ *     file: { driver: 'daily', path: './storage/logs/app.log', days: 14 },
+ *     stack: { driver: 'stack', channels: ['console', 'file'] },
+ *   }
+ * })
+ *
+ * log.info('User logged in', { userId: user.id })
+ * log.error('Payment failed', { orderId, error: error.message })
+ *
+ * const requestLog = log.withContext({ requestId: ctx.requestId })
+ * requestLog.info('Processing request')
+ * ```
+ */
+declare class LogManager {
+    private readonly config;
+    private readonly channelFactories;
+    private readonly channelInstances;
+    private readonly loggers;
+    private readonly loggerOptions;
+    constructor(config: LogConfig);
+    private registerDefaultDrivers;
+    private createStackChannel;
+    /**
+     * Register a custom channel driver.
+     */
+    registerDriver(name: string, factory: LogChannelFactory): void;
+    /**
+     * Get a logger for a specific channel.
+     */
+    channel(name?: string): Logger;
+    /**
+     * Get a logger that writes to multiple channels.
+     */
+    stack(channelNames: string[]): Logger;
+    private resolveChannel;
+    /**
+     * Create a logger with additional context using the default channel.
+     */
+    withContext(context: Record<string, unknown>): Logger;
+    emergency(message: string, context?: Record<string, unknown>): void;
+    alert(message: string, context?: Record<string, unknown>): void;
+    critical(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    warning(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    notice(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Close all channel instances.
+     */
+    close(): Promise<void>;
+    /**
+     * Get the default channel name.
+     */
+    getDefaultChannel(): string;
+    /**
+     * Get available channel names.
+     */
+    getChannelNames(): string[];
+}
+/**
+ * Create a log manager instance.
+ */
+declare function createLogManager(config: LogConfig): LogManager;
+/**
+ * Set the global log manager instance.
+ */
+declare function setLogManager(manager: LogManager): void;
+/**
+ * Get the global log manager instance.
+ */
+declare function getLogManager(): LogManager;
+
+export { type ConsoleChannelConfig as C, type DailyFileChannelConfig as D, type FileChannelConfig as F, LogManager as L, type StackChannelConfig as S, LOG_LEVEL_PRIORITY as a, type LogChannel as b, type LogChannelConfig as c, type LogChannelFactory as d, type LogConfig as e, type LogContext as f, type LogEntry as g, type LogFormatter as h, type LogLevel as i, Logger as j, type LoggerOptions as k, createLogManager as l, filterSensitiveData as m, getLogManager as n, setLogManager as s };