yinzerflow 0.3.1 → 0.4.1

package/README.md

@@ -41,7 +41,7 @@ await app.listen();
 - **[Getting Started](docs/start-here.md)** - Complete guide and examples
 - **[Routes](docs/routes.md)** - Routing system and handlers
 - **[Request/Response](docs/request.md)** - Request and response objects
-- **[Logging](docs/logging.md)** - Logging configuration and customization
+- **[Logging](docs/core/logging.md)** - Logging configuration and customization
 - **[Advanced Configuration](docs/advanced-configuration-options.md)** - Detailed configuration options
 
 ## 🛡️ Security

package/docs/configuration/advanced-configuration-options.md

@@ -210,7 +210,7 @@ await app.listen();
 
 ### Logging Configuration
 
-Control framework logging output with built-in Pittsburgh personality or custom logging libraries. See [Logging Documentation](./logging.md) for detailed setup, custom logger integration, and advanced use cases.
+Control framework logging output with built-in Pittsburgh personality or custom logging libraries. See [Logging Documentation](../core/logging.md) for detailed setup, custom logger integration, and advanced use cases.
 
 ```typescript
 const app = new YinzerFlow({

package/docs/configuration/configuration-patterns.md

@@ -443,7 +443,7 @@ For detailed configuration options, see:
 - **[Body Parsing Security](../security/body-parsing.md)** - Body parser configuration
 - **[CORS Security](../security/cors.md)** - CORS configuration
 - **[IP Security](../security/ip-security.md)** - IP security configuration
-- **[Logging Security](../security/logging.md)** - Logging configuration
+- **[Logging Security](../core/logging.md)** - Logging configuration
 
 ## Common Issues and Solutions
 

package/docs/core/logging.md

@@ -0,0 +1,130 @@
+# Logging
+
+YinzerFlow provides a flexible logging system with built-in Pittsburgh personality and performance tracking.
+
+## Configuration
+
+```typescript
+import { YinzerFlow, createLogger } from 'yinzerflow';
+
+const logger = createLogger({
+  prefix: 'MYAPP',
+  logLevel: 'info'
+});
+
+const server = new YinzerFlow({
+  port: 3000,
+  logger,
+  networkLogs: true
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logLevel` | `'off' \| 'error' \| 'warn' \| 'info'` | `'info'` | Minimum log level to output |
+| `prefix` | `string` | `'YINZER'` | Prefix for log messages |
+| `logger` | `Logger` | `undefined` | Custom logger implementation (Winston, Pino, etc.) |
+| `networkLogs` | `boolean` | `false` | Enable nginx-style network request logging |
+| `networkLogger` | `Logger` | `undefined` | Custom logger for network logs (can be same as `logger` or different) |
+
+## Examples
+
+### Basic Example
+
+```typescript
+import { log } from 'yinzerflow';
+
+// Use the shared logger (default YINZER prefix)
+log.info('Application started');
+log.warn('Deprecated feature used');
+log.error('Operation failed');
+```
+
+### Custom Logger
+
+```typescript
+import { createLogger } from 'yinzerflow';
+
+const dbLogger = createLogger({ 
+  prefix: 'DATABASE', 
+  logLevel: 'error' 
+});
+
+dbLogger.error('Connection failed');
+// Output: [DATABASE] ❌ [timestamp] [ERROR] Connection failed - aw jeez
+```
+
+### Unified Network and App Logging
+
+```typescript
+import { YinzerFlow, createLogger } from 'yinzerflow';
+
+const logger = createLogger({ prefix: 'APP', logLevel: 'info' });
+
+const server = new YinzerFlow({
+  port: 3000,
+  logger,
+  networkLogs: true,
+  networkLogger: logger  // Route network logs to same logger
+});
+
+// Both app and network logs go to the same custom logger
+```
+
+## Common Use Cases
+
+- **Debug Development Issues**: Use default logger with `networkLogs: true` for comprehensive debugging
+- **Track Application Errors**: Use `logLevel: 'error'` to capture only critical errors  
+- **Monitor Component Health**: Create isolated loggers per subsystem with custom prefixes
+- **Integrate External Logging**: Use custom logger implementation for Winston, Pino, etc.
+- **Silent Operation**: Set `logLevel: 'off'` for environments with external log management
+- **Script and Utility Logging**: Use shared `log` instance in standalone scripts and database seeds
+
+## Methods
+
+### `createLogger(options?): Logger`
+
+Creates a logger instance with isolated state.
+
+**Parameters:**
+- `logLevel?: 'off' | 'error' | 'warn' | 'info'` - Minimum log level (default: 'info')
+- `prefix?: string` - Log message prefix (default: 'YINZER')  
+- `logger?: Logger` - Custom logger implementation
+
+**Returns:** Logger with `info`, `warn`, `error`, and `levels` methods.
+
+### Logger Methods
+
+- `info(...args): void` - Log info-level messages
+- `warn(...args): void` - Log warning messages
+- `error(...args): void` - Log error messages
+- `levels` - Access to log level constants
+
+## Properties
+
+### Log Levels
+
+- `off` (0): No logging
+- `error` (1): Only errors
+- `warn` (2): Warnings and errors
+- `info` (3): All messages (most verbose)
+
+## Security Considerations
+
+YinzerFlow implements several security measures for safe logging:
+
+### 🛡️ Safe Data Handling
+- **Problem**: Logging sensitive data can expose secrets in log files
+- **YinzerFlow Solution**: Uses native `console.log` formatting to prevent accidental serialization of sensitive objects
+
+### 🛡️ Log Level Protection
+- **Problem**: Verbose logging in production can impact performance and expose internal details  
+- **YinzerFlow Solution**: Configurable log levels with early returns to minimize overhead when logging is disabled
+
+### 🛡️ Logger Isolation
+- **Problem**: Custom loggers could interfere with framework logging
+- **YinzerFlow Solution**: Clean interface boundaries and isolated logger instances prevent conflicts
+
+These security measures ensure YinzerFlow's logging implementation follows security best practices and prevents common attack vectors while maintaining spec compliance.

package/docs/security/security-overview.md

@@ -124,7 +124,7 @@ app.onError(({ response }, error) => {
 ### 🛡️ Logging Security
 **Protection**: Log injection, sensitive data exposure
 **Implementation**: Structured logging, sensitive data filtering
-**Documentation**: [Logging Security](./logging.md)
+**Documentation**: [Logging Security](../core/logging.md)
 
 ```typescript
 const secureApp = new YinzerFlow({
@@ -272,7 +272,7 @@ For detailed security documentation:
 - **[Body Parsing](./body-parsing.md)** - File upload and JSON parsing security
 - **[CORS](./cors.md)** - Cross-origin request security
 - **[IP Security](./ip-security.md)** - Client IP validation and protection
-- **[Logging](./logging.md)** - Secure logging practices
+- **[Logging](../core/logging.md)** - Secure logging practices
 - **[Error Handling](../core/error-handling.md)** - Secure error handling patterns
 
 For security issues or questions:

package/docs/start-here.md

@@ -120,7 +120,7 @@ For custom shutdown handling, see [Advanced Configuration](./advanced-configurat
 - **[Body Parsing](./security/body-parsing.md)** - Secure parsing of JSON, file uploads, and form data with DoS protection
 - **[CORS](./security/cors.md)** - Cross-Origin Resource Sharing with comprehensive security measures
 - **[IP Security](./security/ip-security.md)** - Client IP validation and spoofing protection for load balancers and CDNs
-- **[Logging](./security/logging.md)** - Flexible logging with custom logger support and Pittsburgh personality
+- **[Logging](./core/logging.md)** - Flexible logging with custom logger support and Pittsburgh personality
 - **[Configuration Patterns](./configuration/configuration-patterns.md)** - Common configuration patterns and best practices
 - **[Advanced Configuration](./configuration/advanced-configuration-options.md)** - Fine-tune security, performance, and functionality
 
@@ -164,7 +164,7 @@ For custom shutdown handling, see [Advanced Configuration](./advanced-configurat
 1. **Start with Routes**: Learn the routing system in [routes.md](./routes.md)
 2. **Understand Requests**: Explore request handling in [request.md](./request.md)
 3. **Configure Security**: Set up IP security and CORS in [ip-security.md](./ip-security.md) and [cors.md](./cors.md)
-4. **Customize Logging**: Implement custom loggers in [logging.md](./logging.md)
+4. **Customize Logging**: Implement custom loggers in [logging.md](./core/logging.md)
 5. **Advanced Configuration**: Fine-tune settings in [advanced-configuration-options.md](./advanced-configuration-options.md)
 
 ## Examples

package/index.d.ts

@@ -1559,12 +1559,31 @@ declare const logLevels: {
 	readonly warn: "warn";
 	readonly info: "info";
 };
+/**
+ * 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.
+ * - 'error': Only errors
+ * - 'warn': Warnings and errors (includes security warnings, slow requests)
+ * - 'info': Info, warnings, and errors (standard application logging)
+ *
+ * Network logging is controlled separately via boolean networkLogging 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;
-	trace?: (...args: Array<unknown>) => void;
+}
+export interface LoggerConfig {
+	logLevel?: LogLevel | undefined;
+	prefix?: string | undefined;
+	logger?: {
+		info: (...args: Array<unknown>) => void;
+		warn: (...args: Array<unknown>) => void;
+		error: (...args: Array<unknown>) => void;
+	} | undefined;
 }
 /**
  * Internal CORS Configuration Options
@@ -1870,19 +1889,16 @@ export interface InternalServerConfiguration {
 	 */
 	host: string;
 	/**
-	 * Application logging level for YinzerFlow server
-	 * - 'off': No application logging (silent mode)
-	 * - 'error': Only error messages
-	 * - 'warn': Warning and error messages
-	 * - 'info': All application logging with Pittsburgh personality
-	 * @default 'warn'
-	 */
-	logLevel: CreateEnum<typeof logLevels>;
-	/**
-	 * Custom logger implementation
-	 * If provided, this logger will be used instead of the built-in YinzerFlow logger
-	 * Must implement the Logger interface
-	 * @default undefined (uses built-in logger)
+	 * Custom logger instance
+	 *
+	 * 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;
 	/**
@@ -1923,10 +1939,16 @@ export interface InternalServerConfiguration {
 	autoGracefulShutdown: boolean;
 }
 export type HttpMethodHandlers = Record<Lowercase<keyof typeof httpMethod>, InternalSetupMethod>;
-export type RouteGroupMethod = (prefix: string, callback: (group: InternalGroupApp) => void, options?: InternalRouteRegistryOptions) => InternalGroupApp;
+export type RouteGroupMethod = (prefix: string, callback: (group: RouteGroup) => void, options?: InternalRouteRegistryOptions) => RouteGroup;
 export interface InternalGroupApp extends HttpMethodHandlers {
 	readonly group: RouteGroupMethod;
 }
+/**
+ * Route group instance that provides HTTP method handlers and nested group support.
+ *
+ * @see {@link InternalGroupApp} for internal implementation details
+ */
+export type RouteGroup = InternalGroupApp;
 /**
  * Main setup interface for configuring YinzerFlow routes, hooks, and middleware.
  *
@@ -2300,7 +2322,7 @@ declare class SetupImpl implements InternalSetupImpl {
 	patch(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
 	delete(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
 	options(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
-	group(prefix: string, callback: (group: InternalGroupApp) => void, options?: InternalRouteRegistryOptions): InternalGroupApp;
+	group(prefix: string, callback: (group: RouteGroup) => void, options?: InternalRouteRegistryOptions): RouteGroup;
 	beforeAll(handlers: Array<HandlerCallback<any>>, options?: InternalGlobalHookOptions): void;
 	afterAll(handlers: Array<HandlerCallback<any>>, options?: InternalGlobalHookOptions): void;
 	onError(handler: HandlerCallback<any>): void;
@@ -2322,19 +2344,23 @@ 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;
+	levels: typeof LOG_LEVELS;
+};
 export declare const log: {
-	setLogLevel: (level: "error" | "info" | "off" | "warn") => void;
-	setCustomLogger: (logger: Logger) => void;
 	info: (...args: Array<unknown>) => void;
 	warn: (...args: Array<unknown>) => void;
 	error: (...args: Array<unknown>) => void;
-	perf: (message: string, timeMs: number, data?: unknown) => void;
-	levels: {
-		readonly off: 0;
-		readonly error: 1;
-		readonly warn: 2;
-		readonly info: 3;
-	};
+	levels: typeof LOG_LEVELS;
 };
 
 export {};