yinzerflow 0.6.12 → 0.7.0

package/index.d.ts

@@ -984,24 +984,26 @@ interface Response$1 {
 }
 /**
  Time duration string format
- 
- Format: number followed by unit (s, m, h, d)
- 
+
+ Format: number followed by unit (ms, s, m, h, d)
+
  Units:
+ - ms: milliseconds
  - s: seconds
  - m: minutes
  - h: hours
  - d: days
- 
+
  @example
  ```typescript
- '30s'  // 30 seconds
- '15m'  // 15 minutes
- '2h'   // 2 hours
- '1d'   // 1 day
+ '500ms' // 500 milliseconds
+ '30s'   // 30 seconds
+ '15m'   // 15 minutes
+ '2h'    // 2 hours
+ '1d'    // 1 day
  ```
  */
-export type TimeString = `${number}${"d" | "h" | "m" | "s"}`;
+export type TimeString = `${number}${"d" | "h" | "m" | "ms" | "s"}`;
 export interface InternalCookieOptions {
 	/**
 	 * Expiration date/time for the cookie
@@ -1479,6 +1481,11 @@ export interface InternalHookRegistryImpl {
 	_addAfterHooks: (handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions) => void;
 	_addOnError: (handler: HandlerCallback) => void;
 	_addOnNotFound: (handler: HandlerCallback) => void;
+	setLogger: (logger: {
+		info: (...args: Array<unknown>) => void;
+		warn: (...args: Array<unknown>) => void;
+		error: (...args: Array<unknown>) => void;
+	}) => void;
 }
 /**
  * Internal route registry implementation for managing route storage and lookup.
@@ -1887,33 +1894,52 @@ export declare const logLevels: {
 	readonly error: "error";
 	readonly warn: "warn";
 	readonly info: "info";
+	readonly debug: "debug";
 };
 /**
  * YinzerFlow Logging Levels
  *
  * String-based logging levels for intuitive configuration:
- * - 'off': No logging at all. Mainly used for network logging internally, but feel free to use it for other purposes.
+ * - 'off': No logging at all
  * - 'error': Only errors
- * - 'warn': Warnings and errors (includes security warnings, slow requests)
+ * - 'warn': Warnings and errors (includes security warnings)
  * - 'info': Info, warnings, and errors (standard application logging)
+ * - 'debug': All messages including verbose connection details
  *
- * Network logging is controlled separately via boolean networkLogging config.
+ * Access logging is controlled separately via `logging.requests` config.
  */
 export type LogLevel = CreateEnum<typeof logLevels>;
 export interface Logger {
 	info: (...args: Array<unknown>) => void;
 	warn: (...args: Array<unknown>) => void;
 	error: (...args: Array<unknown>) => void;
+	debug?: ((...args: Array<unknown>) => void) | undefined;
 }
 export interface LoggerConfig {
-	logLevel?: LogLevel | undefined;
+	level?: LogLevel | undefined;
 	prefix?: string | undefined;
-	logger?: {
-		info: (...args: Array<unknown>) => void;
-		warn: (...args: Array<unknown>) => void;
-		error: (...args: Array<unknown>) => void;
-	} | undefined;
+	logLevel?: LogLevel | undefined;
 }
+/**
+ * Byte size string format
+ *
+ * Format: number followed by unit (b, kb, mb, gb)
+ *
+ * Units:
+ * - b: bytes
+ * - kb: kilobytes (1024 bytes)
+ * - mb: megabytes (1048576 bytes)
+ * - gb: gigabytes (1073741824 bytes)
+ *
+ * @example
+ * ```typescript
+ * '512b'   // 512 bytes
+ * '256kb'  // 256 kilobytes
+ * '1mb'    // 1 megabyte
+ * '2gb'    // 2 gigabytes
+ * ```
+ */
+export type ByteString = `${number}${"b" | "gb" | "kb" | "mb"}`;
 export declare const rateLimitAlgorithm: {
 	readonly slidingWindowCounter: "sliding-window-counter";
 };
@@ -2380,32 +2406,14 @@ export interface InternalServerOptions {
 	 */
 	host: string;
 	/**
-	 * Custom logger instance
+	 * Logging configuration — controls app logger, access logs, and diagnostics.
 	 *
-	 * Use createLogger() to create logger instances with custom configuration
-	 * @default undefined (uses built-in logger with default settings)
-	 *
-	 * @example
-	 * ```typescript
-	 * const logger = createLogger({ prefix: 'APP', logLevel: 'info' });
-	 * new YinzerFlow({ logger });
-	 * ```
-	 */
-	logger?: Logger;
-	/**
-	 * Network request/response logging (nginx-style logs)
-	 * Completely separate from application logs - simple on/off toggle
-	 * @default false
-	 */
-	networkLogs: boolean;
-	/**
-	 * Custom logger for network logs (optional)
-	 * If provided, network logs will be routed to this logger instead of built-in formatting
-	 * Can be the same as the application logger or a different one
-	 * Useful for unified monitoring (e.g., Winston with Datadog transport for both app and network logs)
-	 * @default undefined (uses built-in network logging)
+	 * Three independent channels:
+	 * - **App logger**: Developer logs + framework errors/warnings (gated by `level`)
+	 * - **Access log**: nginx-style request/response lines (gated by `requests` on/off)
+	 * - **Diagnostics**: Framework health monitoring (gated by individual thresholds)
 	 */
-	networkLogger?: Logger;
+	logging: InternalLoggingOptions;
 	/**
 	 * Cross-Origin Resource Sharing configuration
 	 */
@@ -2442,6 +2450,92 @@ export interface InternalServerOptions {
 	 */
 	gracefulShutdownTimeout: TimeString | number;
 }
+/**
+ * Internal Logging Configuration
+ * Controls three independent channels: app logger, access logs, and diagnostics.
+ */
+export interface InternalLoggingOptions {
+	/**
+	 * Log level threshold — messages at this severity and above are output.
+	 * From least to most severe: debug → info → warn → error.
+	 * @default 'warn'
+	 */
+	level: LogLevel;
+	/**
+	 * Log line prefix shown in brackets, e.g. [YINZER]
+	 * @default 'YINZER'
+	 */
+	prefix: string;
+	/**
+	 * Enable Pittsburgh personality phrases in log output
+	 * @default true
+	 */
+	personality: boolean;
+	/**
+	 * Enable nginx-style access logs (one line per request/response)
+	 * @default false
+	 */
+	requests: boolean;
+	/**
+	 * Custom logger for application logs (optional)
+	 * If provided, app logs route to this logger instead of built-in formatting
+	 * @default undefined
+	 */
+	logger?: Logger;
+	/**
+	 * Custom logger for access logs (optional)
+	 * If provided, access logs route to this logger instead of built-in formatting
+	 * @default undefined
+	 */
+	accessLogger?: Logger;
+	/**
+	 * Framework diagnostics — health monitoring independent of app log level.
+	 * All thresholds default to false (disabled). Set a threshold to enable.
+	 */
+	diagnostics: InternalDiagnosticsOptions;
+}
+/**
+ * Internal Diagnostics Configuration
+ * Framework health monitoring that fires independently of the app log level.
+ * Even with `level: 'off'`, diagnostics still fire when thresholds are exceeded.
+ */
+export interface InternalDiagnosticsOptions {
+	/**
+	 * Log requests slower than this threshold
+	 * @default false (disabled)
+	 * @example '500ms' or 500 (milliseconds)
+	 */
+	slowRequests: TimeString | number | false;
+	/**
+	 * Log responses larger than this threshold
+	 * @default false (disabled)
+	 * @example '1mb' or 1048576 (bytes)
+	 */
+	largeResponses: ByteString | number | false;
+	/**
+	 * Log requests with bodies larger than this threshold
+	 * @default false (disabled)
+	 * @example '1mb' or 1048576 (bytes)
+	 */
+	largeRequests: ByteString | number | false;
+	/**
+	 * Log periodic memory/heap usage at this interval
+	 * @default false (disabled)
+	 * @example '30s' or 30000 (milliseconds)
+	 */
+	memory: TimeString | number | false;
+	/**
+	 * Log event loop lag exceeding this threshold
+	 * @default false (disabled)
+	 * @example '100ms' or 100 (milliseconds)
+	 */
+	eventLoop: TimeString | number | false;
+	/**
+	 * Log rate limit hits
+	 * @default false (disabled)
+	 */
+	rateLimits: boolean;
+}
 export type HttpMethodHandlers = Record<Lowercase<keyof typeof httpMethod>, InternalSetupMethod>;
 export type RouteGroupMethod = (prefix: string, callback: (group: RouteGroup) => void, options?: InternalRouteRegistryOptions) => RouteGroup;
 export interface InternalGroupApp extends HttpMethodHandlers {
@@ -2778,6 +2872,14 @@ export interface InternalSetupImpl extends Setup {
 	readonly _configuration: InternalServerOptions;
 	readonly _routeRegistry: InternalRouteRegistryImpl;
 	readonly _hooks: InternalHookRegistryImpl;
+	/** Per-instance logger. Set by `_configureLogging()` in YinzerFlow. */
+	_log: {
+		info: (...args: Array<unknown>) => void;
+		warn: (...args: Array<unknown>) => void;
+		error: (...args: Array<unknown>) => void;
+		debug: (...args: Array<unknown>) => void;
+		table: (data: unknown, ...additionalArgs: Array<unknown>) => void;
+	};
 }
 declare class HookRegistryImpl implements InternalHookRegistryImpl {
 	readonly _beforeRouting: Set<{
@@ -2794,6 +2896,12 @@ declare class HookRegistryImpl implements InternalHookRegistryImpl {
 	}>;
 	_onError: HandlerCallback;
 	_onNotFound: HandlerCallback;
+	private _logger;
+	setLogger(logger: {
+		info: (...args: Array<unknown>) => void;
+		warn: (...args: Array<unknown>) => void;
+		error: (...args: Array<unknown>) => void;
+	}): void;
 	constructor();
 	_addBeforeRoutingHooks(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
 	_addBeforeHooks(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
@@ -2827,29 +2935,30 @@ declare class HookRegistryImpl implements InternalHookRegistryImpl {
  * // Basic configuration with logging
  * const app = new YinzerFlow({
  *   port: 8080,
- *   logLevel: 'info',
- *   networkLogs: true
+ *   logging: { level: 'info', requests: true }
  * });
  *
  * // Full configuration example
  * const app = new YinzerFlow({
  *   port: 3000,
  *   host: '0.0.0.0',
- *   logLevel: 'debug',
- *   networkLogs: true,
- *   autoGracefulShutdown: true,
+ *   logging: {
+ *     level: 'debug',
+ *     personality: true,
+ *     requests: true,
+ *     logger: {
+ *       info: (message, ...args) => console.log(`[APP] ${message}`, ...args),
+ *       warn: (message, ...args) => console.warn(`[APP] ${message}`, ...args),
+ *       error: (message, ...args) => console.error(`[APP] ${message}`, ...args),
+ *       debug: (message, ...args) => console.debug(`[APP] ${message}`, ...args)
+ *     }
+ *   },
  *   cors: {
  *     enabled: true,
  *     origin: ['https://example.com', 'https://app.example.com'],
  *     methods: ['GET', 'POST', 'PUT', 'DELETE'],
  *     headers: ['Content-Type', 'Authorization'],
  *     credentials: true
- *   },
- *   logger: {
- *     info: (message, ...args) => console.log(`[APP] ${message}`, ...args),
- *     warn: (message, ...args) => console.warn(`[APP] ${message}`, ...args),
- *     error: (message, ...args) => console.error(`[APP] ${message}`, ...args),
- *     debug: (message, ...args) => console.debug(`[APP] ${message}`, ...args)
  *   }
  * });
  * ```
@@ -2949,10 +3058,48 @@ declare class RouteRegistryImpl implements InternalRouteRegistryImpl {
 	private _storeParameterizedRoute;
 	private _findParameterizedRoute;
 }
+declare const loggerBrand: unique symbol;
+declare const LOG_LEVELS: {
+	readonly off: 0;
+	readonly error: 1;
+	readonly warn: 2;
+	readonly info: 3;
+	readonly debug: 4;
+};
+export declare const createLogger: (initialConfig?: LoggerConfig & {
+	personality?: boolean;
+	logger?: Logger | null | undefined;
+}) => {
+	info: (...args: Array<unknown>) => void;
+	warn: (...args: Array<unknown>) => void;
+	error: (...args: Array<unknown>) => void;
+	debug: (...args: Array<unknown>) => void;
+	table: (data: unknown, ...additionalArgs: Array<unknown>) => void;
+	levels: typeof LOG_LEVELS;
+	[loggerBrand]: {
+		level: string;
+		prefix: string;
+		personality: boolean;
+	};
+};
+declare const log: {
+	info: (...args: Array<unknown>) => void;
+	warn: (...args: Array<unknown>) => void;
+	error: (...args: Array<unknown>) => void;
+	debug: (...args: Array<unknown>) => void;
+	table: (data: unknown, ...additionalArgs: Array<unknown>) => void;
+	levels: typeof LOG_LEVELS;
+	[loggerBrand]: {
+		level: string;
+		prefix: string;
+		personality: boolean;
+	};
+};
 declare class SetupImpl implements InternalSetupImpl {
 	readonly _configuration: InternalServerOptions;
 	readonly _routeRegistry: RouteRegistryImpl;
 	readonly _hooks: HookRegistryImpl;
+	_log: typeof log;
 	constructor(customConfiguration?: ServerOptions);
 	get(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
 	head(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
@@ -2972,8 +3119,13 @@ export declare class YinzerFlow extends SetupImpl {
 	private _isListening;
 	private _server?;
 	private _globalRateLimiter?;
+	private _diagnostics?;
 	private readonly _maxBufferSize;
+	private _accessLog?;
+	private _accessLogEnabled;
 	constructor(configuration?: ServerOptions);
+	get log(): typeof YinzerFlow._log;
+	private _configureLogging;
 	private _setupServer;
 	private _processRequest;
 	private _handleRequestError;
@@ -2991,26 +3143,6 @@ export declare class YinzerFlow extends SetupImpl {
 	};
 	private _setupGracefulShutdown;
 }
-declare const LOG_LEVELS: {
-	readonly off: 0;
-	readonly error: 1;
-	readonly warn: 2;
-	readonly info: 3;
-};
-export declare const createLogger: (initialConfig?: LoggerConfig) => {
-	info: (...args: Array<unknown>) => void;
-	warn: (...args: Array<unknown>) => void;
-	error: (...args: Array<unknown>) => void;
-	table: (data: unknown, ...additionalArgs: Array<unknown>) => void;
-	levels: typeof LOG_LEVELS;
-};
-export declare const log: {
-	info: (...args: Array<unknown>) => void;
-	warn: (...args: Array<unknown>) => void;
-	error: (...args: Array<unknown>) => void;
-	table: (data: unknown, ...additionalArgs: Array<unknown>) => void;
-	levels: typeof LOG_LEVELS;
-};
 export declare const corsHook: (config: InternalCorsEnabledOptions) => HandlerCallback;
 export declare const rateLimitHook: <T extends HandlerCallbackGenerics>(rateLimitOptions: RateLimitOptions) => HandlerCallback<T>;
 export declare const colors: {