\n\nA tiny, powerful isomorphic logger for both Node.js and browser environments. built for **Agent Tars**.\n\n| Browser | Node.js |\n| --------------------------------------- | --------------------------------- |\n|  |  |\n\n## Features\n\n- **Isomorphic**: Works seamlessly in both Node.js and browser environments\n- **Colorful Output**: Automatic color support for different platforms\n- **Hierarchical Logging**: Create nested loggers with prefixes\n- **Data Handling**: Log structured data with optional transformation\n- **Zero Dependencies**: Lightweight with no external runtime dependencies\n- **TypeScript Support**: Full type definitions included\n- **Log Levels**: Fine-grained control over logging verbosity\n\n## Installation\n\n```bash\nnpm install @agent-infra/logger\n# or\nyarn add @agent-infra/logger\n# or\npnpm add @agent-infra/logger\n```\n\n## Quick Start\n\n```typescript\nimport { ConsoleLogger } from '@agent-infra/logger';\n\n// Create a logger with a prefix\nconst logger = new ConsoleLogger('[App]');\n\n// Basic logging\nlogger.info('Server started');\nlogger.warn('Resource usage high');\nlogger.error('Database connection failed');\nlogger.success('Task completed successfully');\n\n// Log with structured data\nlogger.infoWithData(\n 'User data:',\n { id: 1, name: 'John', email: 'john@example.com' },\n // Optional transformer to mask sensitive data\n (user) => ({ ...user, email: '***@example.com' }),\n);\n\n// Create a child logger for a specific component\nconst dbLogger = logger.spawn('Database');\ndbLogger.info('Connected to database'); // Outputs: [App:Database] Connected to database\n```\n\n## API Reference\n\n### Logger\n\nMain logger type.\n\n| Method | Description |\n| ----------------------------------------------------------------------------- | --------------------------------------------------------- |\n| `log(...args: any[])` | Basic logging, similar to console.log |\n| `info(message: string)` | Log informational message (blue prefix) |\n| `warn(message: string)` | Log warning message (yellow prefix) |\n| `error(message: string)` | Log error message (red prefix) |\n| `success(message: string)` | Log success message (green prefix) |\n| `infoWithData(message: string, data?: T, transformer?: (value: T) => any)` | Log message with associated data and optional transformer |\n| `spawn(prefix: string)` | Create a new logger instance with additional prefix |\n| `setLevel(level: LogLevel)` | Set the current log level |\n| `getLevel()` | Get the current log level |\n\n### LogLevel\n\nControls the verbosity of logging output.\n\n```typescript\nenum LogLevel {\n DEBUG = 0, // Most verbose, includes all logs\n INFO = 1, // Standard information messages\n SUCCESS = 2, // Success messages and operations\n WARN = 3, // Warning messages\n ERROR = 4, // Error messages\n SILENT = 5 // No logs will be displayed\n}\n```\n\n### defaultLogger\n\nThe empty logger that implements the Logger interface but does nothing.\n\n### ConsoleLogger\n\nThe main logger implementation with colored console output.\n\n## Usage\n\n### Log Levels\n\nControl verbosity with log levels:\n\n```ts\nimport { ConsoleLogger, LogLevel } from '@agent-infra/logger';\n\nconst logger = new ConsoleLogger('[App]');\n\n// Set log level\nlogger.setLevel(LogLevel.WARN); // Only WARN and ERROR will be shown\n\n// These won't be displayed\nlogger.debug('Debug message');\nlogger.info('Info message');\nlogger.success('Success message');\n\n// These will be displayed\nlogger.warn('Warning message');\nlogger.error('Error message');\n\n// Get current log level\nconst currentLevel = logger.getLevel(); // Returns LogLevel.WARN\n```\n\n### Data Logging with Transformation\n\nThe `infoWithData` method allows logging structured data with optional transformation:\n\n```typescript\n// Log data with optional transformation\nlogger.infoWithData(\n 'User profile:',\n { id: 123, name: 'Alice', email: 'alice@example.com', password: 'secret123' },\n // Optional transformer to mask sensitive data\n (data) => ({ ...data, password: '********' }),\n);\n```\n\n### Hierarchical Loggers\n\nCreate nested loggers with the `spawn` method for better organization:\n\n```ts\n// Create parent logger\nconst appLogger = new ConsoleLogger('[App]');\n\n// Create child loggers for different components\nconst authLogger = appLogger.spawn('Auth');\nconst dbLogger = appLogger.spawn('Database');\nconst apiLogger = appLogger.spawn('API');\n\n// Usage\nauthLogger.info('User authenticated'); // Outputs: [App:Auth] User authenticated\ndbLogger.error('Connection failed'); // Outputs: [App:Database] Connection failed\napiLogger.warn('Rate limit reached'); // Outputs: [App:API] Rate limit reached\n```\n\n### Advanced Usage\n\n#### Environment-Specific Configuration\n\nConfigure different log levels based on environment:\n\n```typescript\nimport { ConsoleLogger, LogLevel } from '@agent-infra/logger';\n\n// Create base logger\nconst logger = new ConsoleLogger('[App]');\n\n// Configure based on environment\nif (process.env.NODE_ENV === 'production') {\n logger.setLevel(LogLevel.WARN); // Only show warnings and errors in production\n} else if (process.env.NODE_ENV === 'test') {\n logger.setLevel(LogLevel.ERROR); // Only show errors in test\n} else {\n logger.setLevel(LogLevel.DEBUG); // Show all logs in development\n}\n```\n\n#### Integration with Error Tracking\n\nCombine with error tracking services:\n\n```typescript\nimport { ConsoleLogger } from '@agent-infra/logger';\nimport * as Sentry from '@sentry/browser'; // Example error tracking\n\nconst logger = new ConsoleLogger('[App]');\n\n// Override error method to also report to Sentry\nconst originalError = logger.error;\nlogger.error = function(...args) {\n // Call original implementation\n originalError.apply(this, args);\n \n // Report to error tracking\n if (args[0] && typeof args[0] === 'string') {\n Sentry.captureMessage(args[0], Sentry.Severity.Error);\n }\n};\n```\n\n#### Custom Color Themes\n\nYou can modify the CSS_COLOR_VALUES in your application to customize colors:\n\n```typescript\nimport { ConsoleLogger, CSS_COLOR_VALUES } from '@agent-infra/logger';\n\n// Override default colors with your theme\nObject.assign(CSS_COLOR_VALUES, {\n blue: '#3498db',\n green: '#2ecc71',\n red: '#e74c3c',\n yellow: '#f39c12'\n});\n\nconst logger = new ConsoleLogger('[MyApp]');\n```\n\n## Best Practices\n\n### Organizing Loggers\n\nFor larger applications, organize loggers by feature or module:\n\n```typescript\n// logger.ts\nimport { ConsoleLogger, LogLevel } from '@agent-infra/logger';\n\n// Create root logger\nconst rootLogger = new ConsoleLogger('[MyApp]');\n\n// Set level based on environment\nrootLogger.setLevel(\n process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.INFO\n);\n\n// Create and export feature-specific loggers\nexport const authLogger = rootLogger.spawn('Auth');\nexport const apiLogger = rootLogger.spawn('API');\nexport const dbLogger = rootLogger.spawn('DB');\nexport const uiLogger = rootLogger.spawn('UI');\n```\n\n### Consistent Log Formats\n\nFor machine-parseable logs, use consistent formats:\n\n```typescript\nimport { ConsoleLogger } from '@agent-infra/logger';\n\nconst logger = new ConsoleLogger('[API]');\n\n// Log structured events consistently\nfunction logApiEvent(eventType, data) {\n const event = {\n timestamp: new Date().toISOString(),\n type: eventType,\n ...data\n };\n \n logger.infoWithData(`API ${eventType}`, event);\n}\n\n// Usage\nlogApiEvent('request', { \n method: 'GET', \n path: '/users', \n duration: 120 \n});\n```\n\n## License\n\nCopyright (c) 2025 ByteDance, Inc. and its affiliates.\n\nLicensed under the Apache License, Version 2.0.","users":{}}
![\"npm](\"https://img.shields.io/npm/v/@agent-infra/logger?style=flat-square&colorA=564341&colorB=EDED91\")
\n ![\"downloads\"](\"https://img.shields.io/npm/dm/@agent-infra/logger.svg?style=flat-square&colorA=564341&colorB=EDED91\")
\n ![\"node](\"https://img.shields.io/node/v/@agent-infra/logger.svg?style=flat-square&colorA=564341&colorB=EDED91\")
\n ![\"license\"](\"https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square&colorA=564341&colorB=EDED91\"){kind=icon}
\n