@bernierllc/logging-utils 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,7 @@
1
+ /*
2
+ Copyright (c) 2025 Bernier LLC
3
+
4
+ This file is licensed to the client under a limited-use license.
5
+ The client may use and modify this code *only within the scope of the project it was delivered for*.
6
+ Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
+ */
package/README.md ADDED
@@ -0,0 +1,261 @@
1
+ # @bernierllc/logging-utils
2
+
3
+ Utility functions for log analysis, performance monitoring, and format conversion. This package provides advanced utilities for working with logs beyond basic logging functionality.
4
+
5
+ ## Features
6
+
7
+ - **Performance Monitoring**: Timer tracking, metrics collection, and memory usage monitoring
8
+ - **Log Analysis**: Error frequency analysis, performance statistics, and user activity tracking
9
+ - **Log Aggregation**: Batching, deduplication, and rate limiting utilities
10
+ - **Format Conversion**: Convert between JSON, text, CSV, syslog, and logfmt formats
11
+ - **Type Safety**: Full TypeScript support with comprehensive type definitions
12
+ - **Zero Dependencies**: Only depends on @bernierllc/logging-core
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ npm install @bernierllc/logging-utils @bernierllc/logging-core
18
+ ```
19
+
20
+ ## Usage
21
+
22
+ ### Performance Monitoring
23
+
24
+ ```typescript
25
+ import { PerformanceLogger, MemoryTracker } from '@bernierllc/logging-utils';
26
+
27
+ // Performance tracking
28
+ const perfLogger = new PerformanceLogger();
29
+
30
+ perfLogger.startTimer('database-query');
31
+ // ... perform database query
32
+ const duration = perfLogger.endTimer('database-query');
33
+
34
+ // Increment counters
35
+ perfLogger.incrementCounter('api-requests');
36
+ perfLogger.incrementCounter('errors', 1);
37
+
38
+ // Get metrics
39
+ const metrics = perfLogger.getMetrics('database-query');
40
+ console.log(`Average duration: ${metrics?.duration}ms`);
41
+
42
+ // Memory tracking
43
+ const memoryTracker = new MemoryTracker();
44
+ memoryTracker.takeSnapshot('before-operation');
45
+ // ... perform operation
46
+ memoryTracker.takeSnapshot('after-operation');
47
+
48
+ const diff = memoryTracker.compareSnapshots('before-operation', 'after-operation');
49
+ console.log(`Memory increase: ${diff.heapUsedDiff} bytes`);
50
+ ```
51
+
52
+ ### Log Analysis
53
+
54
+ ```typescript
55
+ import { LogAnalyzer, AuditLogAnalyzer } from '@bernierllc/logging-utils';
56
+ import { LogEntry, AuditLogEntry } from '@bernierllc/logging-core';
57
+
58
+ // System log analysis
59
+ const analyzer = new LogAnalyzer();
60
+
61
+ // Add logs
62
+ analyzer.addLogs(logEntries);
63
+
64
+ // Get error analysis
65
+ const errorAnalysis = analyzer.getErrorAnalysis();
66
+ console.log('Most common errors:', errorAnalysis);
67
+
68
+ // Get performance stats
69
+ const stats = analyzer.getPerformanceStats();
70
+ console.log(`Total logs: ${stats.totalLogs}, Errors: ${stats.errors}`);
71
+
72
+ // Get logs by time range
73
+ const recentLogs = analyzer.getLogsByTimeRange(
74
+ '2025-01-01T00:00:00Z',
75
+ '2025-01-01T23:59:59Z'
76
+ );
77
+
78
+ // Audit log analysis
79
+ const auditAnalyzer = new AuditLogAnalyzer();
80
+ auditAnalyzer.addAuditLogs(auditLogEntries);
81
+
82
+ // Get suspicious activity
83
+ const suspicious = auditAnalyzer.getSuspiciousActivity(10);
84
+ console.log('Suspicious activity:', suspicious);
85
+
86
+ // Get user activity summary
87
+ const userActivity = auditAnalyzer.getUserActivitySummary();
88
+ console.log('User activity:', userActivity);
89
+ ```
90
+
91
+ ### Log Aggregation
92
+
93
+ ```typescript
94
+ import { LogAggregator, LogDeduplicator, LogRateLimiter } from '@bernierllc/logging-utils';
95
+
96
+ // Batch processing
97
+ const aggregator = new LogAggregator(100, 5000); // 100 logs, 5 second flush
98
+
99
+ aggregator.setFlushCallback((logs) => {
100
+ // Process batch of logs
101
+ console.log(`Processing ${logs.length} logs`);
102
+ });
103
+
104
+ aggregator.addLog(logEntry);
105
+
106
+ // Deduplication
107
+ const deduplicator = new LogDeduplicator(60000); // 1 minute window
108
+
109
+ if (!deduplicator.isDuplicate(logEntry)) {
110
+ // Process unique log
111
+ console.log('Processing unique log');
112
+ }
113
+
114
+ // Rate limiting
115
+ const rateLimiter = new LogRateLimiter(1000); // 1000 logs per minute
116
+
117
+ if (rateLimiter.shouldAllowLog('error')) {
118
+ // Log allowed
119
+ console.log('Logging error');
120
+ } else {
121
+ console.log('Rate limit exceeded');
122
+ }
123
+ ```
124
+
125
+ ### Format Conversion
126
+
127
+ ```typescript
128
+ import { LogFormatter, LogParser } from '@bernierllc/logging-utils';
129
+ import { LogEntry } from '@bernierllc/logging-core';
130
+
131
+ // Convert to different formats
132
+ const logEntry: LogEntry = {
133
+ level: 'info',
134
+ message: 'Application started',
135
+ timestamp: new Date().toISOString(),
136
+ metadata: { userId: 'user123' }
137
+ };
138
+
139
+ // Convert to different formats
140
+ const json = LogFormatter.toJSON(logEntry);
141
+ const text = LogFormatter.toText(logEntry);
142
+ const csv = LogFormatter.toCSV(logEntry);
143
+ const syslog = LogFormatter.toSyslog(logEntry);
144
+ const logfmt = LogFormatter.toLogfmt(logEntry);
145
+
146
+ // Parse from different formats
147
+ const parsedFromJson = LogParser.fromJSON(json);
148
+ const parsedFromText = LogParser.fromText(text);
149
+ const parsedFromCsv = LogParser.fromCSV(csv);
150
+
151
+ // Convert multiple logs
152
+ const logs: LogEntry[] = [logEntry1, logEntry2, logEntry3];
153
+ const jsonArray = LogFormatter.formatMultiple(logs, 'json');
154
+ const csvTable = LogFormatter.formatMultiple(logs, 'csv');
155
+ ```
156
+
157
+ ## API Reference
158
+
159
+ ### Performance Monitoring
160
+
161
+ #### `PerformanceLogger`
162
+ - `startTimer(name: string): void`
163
+ - `endTimer(name: string, metadata?: Record<string, unknown>): number`
164
+ - `incrementCounter(name: string, value?: number): void`
165
+ - `getMetrics(name: string): PerformanceMetrics | undefined`
166
+ - `getAllMetrics(): Map<string, PerformanceMetrics>`
167
+ - `reset(): void`
168
+
169
+ #### `MemoryTracker`
170
+ - `takeSnapshot(name: string): NodeJS.MemoryUsage`
171
+ - `getSnapshot(name: string): NodeJS.MemoryUsage | undefined`
172
+ - `compareSnapshots(name1: string, name2: string): Record<string, number>`
173
+ - `getMemoryUsagePercentage(): number`
174
+
175
+ ### Log Analysis
176
+
177
+ #### `LogAnalyzer`
178
+ - `addLog(log: LogEntry): void`
179
+ - `addLogs(logs: LogEntry[]): void`
180
+ - `getLogsByLevel(level: LogLevel): LogEntry[]`
181
+ - `getLogsByTimeRange(startTime: string, endTime: string): LogEntry[]`
182
+ - `getLogsByText(searchText: string): LogEntry[]`
183
+ - `getErrorAnalysis(): Record<string, number>`
184
+ - `getPerformanceStats(): PerformanceStats`
185
+ - `getUniqueUsers(): string[]`
186
+ - `getUniqueRequestIds(): string[]`
187
+
188
+ #### `AuditLogAnalyzer`
189
+ - `addAuditLog(log: AuditLogEntry): void`
190
+ - `getAuditLogsByActor(actorId: string): AuditLogEntry[]`
191
+ - `getAuditLogsByAction(action: string): AuditLogEntry[]`
192
+ - `getAuditLogsByTarget(target: string): AuditLogEntry[]`
193
+ - `getSuspiciousActivity(threshold?: number): Record<string, number>`
194
+ - `getUserActivitySummary(): Record<string, UserActivity>`
195
+
196
+ ### Log Aggregation
197
+
198
+ #### `LogAggregator`
199
+ - `addLog(log: LogEntry): void`
200
+ - `addLogs(logs: LogEntry[]): void`
201
+ - `flush(): LogEntry[]`
202
+ - `setFlushCallback(callback: (logs: LogEntry[]) => void): void`
203
+ - `stop(): void`
204
+ - `getBatchSize(): number`
205
+
206
+ #### `LogDeduplicator`
207
+ - `isDuplicate(log: LogEntry): boolean`
208
+ - `clear(): void`
209
+
210
+ #### `LogRateLimiter`
211
+ - `shouldAllowLog(level: LogLevel): boolean`
212
+ - `getLogCounts(): Record<string, number>`
213
+
214
+ ### Format Conversion
215
+
216
+ #### `LogFormatter`
217
+ - `toJSON(log: LogEntry): string`
218
+ - `toText(log: LogEntry): string`
219
+ - `toCSV(log: LogEntry): string`
220
+ - `toSyslog(log: LogEntry): string`
221
+ - `toLogfmt(log: LogEntry): string`
222
+ - `formatMultiple(logs: LogEntry[], format: Format): string`
223
+
224
+ #### `LogParser`
225
+ - `fromJSON(json: string): LogEntry`
226
+ - `fromText(text: string): LogEntry`
227
+ - `fromCSV(csv: string): LogEntry`
228
+ - `parseMultiple(content: string, format: Format): LogEntry[]`
229
+
230
+ ## Architecture
231
+
232
+ This package extends the logging ecosystem:
233
+
234
+ ```
235
+ @bernierllc/logging-core (core package)
236
+ ├── Types and interfaces
237
+ └── Environment detection
238
+
239
+ @bernierllc/logging (service package)
240
+ ├── Winston integration
241
+ └── File logging with rotation
242
+
243
+ @bernierllc/logging-utils (this package)
244
+ ├── Performance monitoring
245
+ ├── Log analysis tools
246
+ ├── Aggregation utilities
247
+ └── Format converters
248
+ ```
249
+
250
+ ## Contributing
251
+
252
+ 1. Fork the repository
253
+ 2. Create a feature branch
254
+ 3. Make your changes
255
+ 4. Add tests for new functionality
256
+ 5. Ensure all tests pass
257
+ 6. Submit a pull request
258
+
259
+ ## License
260
+
261
+ MIT License - see LICENSE file for details.
@@ -0,0 +1,85 @@
1
+ import { LogEntry, LogLevel } from './types';
2
+ /**
3
+ * Log aggregation utilities for batching and processing logs
4
+ */
5
+ export declare class LogAggregator {
6
+ private batch;
7
+ private batchSize;
8
+ private flushInterval;
9
+ private flushTimer?;
10
+ private onFlush?;
11
+ constructor(batchSize?: number, flushInterval?: number);
12
+ /**
13
+ * Add a log entry to the batch
14
+ */
15
+ addLog(log: LogEntry): void;
16
+ /**
17
+ * Add multiple log entries
18
+ */
19
+ addLogs(logs: LogEntry[]): void;
20
+ /**
21
+ * Flush the current batch
22
+ */
23
+ flush(): LogEntry[];
24
+ /**
25
+ * Set the flush callback
26
+ */
27
+ setFlushCallback(callback: (logs: LogEntry[]) => void): void;
28
+ /**
29
+ * Start the flush timer
30
+ */
31
+ private startFlushTimer;
32
+ /**
33
+ * Stop the aggregator
34
+ */
35
+ stop(): void;
36
+ /**
37
+ * Get current batch size
38
+ */
39
+ getBatchSize(): number;
40
+ }
41
+ /**
42
+ * Log deduplication utility
43
+ */
44
+ export declare class LogDeduplicator {
45
+ private seenLogs;
46
+ private windowMs;
47
+ constructor(windowMs?: number);
48
+ /**
49
+ * Check if a log is a duplicate
50
+ */
51
+ isDuplicate(log: LogEntry): boolean;
52
+ /**
53
+ * Create a key for deduplication
54
+ */
55
+ private createKey;
56
+ /**
57
+ * Clean old entries
58
+ */
59
+ private cleanOldEntries;
60
+ /**
61
+ * Clear all seen logs
62
+ */
63
+ clear(): void;
64
+ }
65
+ /**
66
+ * Log rate limiter
67
+ */
68
+ export declare class LogRateLimiter {
69
+ private logCounts;
70
+ private lastReset;
71
+ private maxLogsPerMinute;
72
+ constructor(maxLogsPerMinute?: number);
73
+ /**
74
+ * Check if logging should be allowed
75
+ */
76
+ shouldAllowLog(level: LogLevel): boolean;
77
+ /**
78
+ * Reset counters if a minute has passed
79
+ */
80
+ private resetIfNeeded;
81
+ /**
82
+ * Get current log counts
83
+ */
84
+ getLogCounts(): Record<string, number>;
85
+ }
@@ -0,0 +1,172 @@
1
+ "use strict";
2
+ /*
3
+ Copyright (c) 2025 Bernier LLC
4
+
5
+ This file is licensed to the client under a limited-use license.
6
+ The client may use and modify this code *only within the scope of the project it was delivered for*.
7
+ Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
10
+ exports.LogRateLimiter = exports.LogDeduplicator = exports.LogAggregator = void 0;
11
+ /**
12
+ * Log aggregation utilities for batching and processing logs
13
+ */
14
+ class LogAggregator {
15
+ constructor(batchSize = 100, flushInterval = 5000) {
16
+ this.batch = [];
17
+ this.batchSize = batchSize;
18
+ this.flushInterval = flushInterval;
19
+ this.startFlushTimer();
20
+ }
21
+ /**
22
+ * Add a log entry to the batch
23
+ */
24
+ addLog(log) {
25
+ this.batch.push(log);
26
+ if (this.batch.length >= this.batchSize) {
27
+ this.flush();
28
+ }
29
+ }
30
+ /**
31
+ * Add multiple log entries
32
+ */
33
+ addLogs(logs) {
34
+ this.batch.push(...logs);
35
+ if (this.batch.length >= this.batchSize) {
36
+ this.flush();
37
+ }
38
+ }
39
+ /**
40
+ * Flush the current batch
41
+ */
42
+ flush() {
43
+ const logs = [...this.batch];
44
+ this.batch = [];
45
+ if (this.onFlush && logs.length > 0) {
46
+ this.onFlush(logs);
47
+ }
48
+ return logs;
49
+ }
50
+ /**
51
+ * Set the flush callback
52
+ */
53
+ setFlushCallback(callback) {
54
+ this.onFlush = callback;
55
+ }
56
+ /**
57
+ * Start the flush timer
58
+ */
59
+ startFlushTimer() {
60
+ this.flushTimer = setInterval(() => {
61
+ if (this.batch.length > 0) {
62
+ this.flush();
63
+ }
64
+ }, this.flushInterval);
65
+ }
66
+ /**
67
+ * Stop the aggregator
68
+ */
69
+ stop() {
70
+ if (this.flushTimer) {
71
+ clearInterval(this.flushTimer);
72
+ }
73
+ this.flush();
74
+ }
75
+ /**
76
+ * Get current batch size
77
+ */
78
+ getBatchSize() {
79
+ return this.batch.length;
80
+ }
81
+ }
82
+ exports.LogAggregator = LogAggregator;
83
+ /**
84
+ * Log deduplication utility
85
+ */
86
+ class LogDeduplicator {
87
+ constructor(windowMs = 60000) {
88
+ this.seenLogs = new Set();
89
+ this.windowMs = windowMs;
90
+ }
91
+ /**
92
+ * Check if a log is a duplicate
93
+ */
94
+ isDuplicate(log) {
95
+ const key = this.createKey(log);
96
+ const now = Date.now();
97
+ // Clean old entries
98
+ this.cleanOldEntries(now);
99
+ if (this.seenLogs.has(key)) {
100
+ return true;
101
+ }
102
+ this.seenLogs.add(key);
103
+ return false;
104
+ }
105
+ /**
106
+ * Create a key for deduplication
107
+ */
108
+ createKey(log) {
109
+ return `${log.level}:${log.message}:${log.userId || 'anonymous'}:${Math.floor(Date.now() / this.windowMs)}`;
110
+ }
111
+ /**
112
+ * Clean old entries
113
+ */
114
+ cleanOldEntries(now) {
115
+ // This is a simplified implementation
116
+ // In a real implementation, you'd want to store timestamps with the keys
117
+ if (this.seenLogs.size > 1000) { // Prevent memory leaks
118
+ this.seenLogs.clear();
119
+ }
120
+ }
121
+ /**
122
+ * Clear all seen logs
123
+ */
124
+ clear() {
125
+ this.seenLogs.clear();
126
+ }
127
+ }
128
+ exports.LogDeduplicator = LogDeduplicator;
129
+ /**
130
+ * Log rate limiter
131
+ */
132
+ class LogRateLimiter {
133
+ constructor(maxLogsPerMinute = 1000) {
134
+ this.logCounts = new Map();
135
+ this.lastReset = Date.now();
136
+ this.maxLogsPerMinute = maxLogsPerMinute;
137
+ }
138
+ /**
139
+ * Check if logging should be allowed
140
+ */
141
+ shouldAllowLog(level) {
142
+ this.resetIfNeeded();
143
+ const key = level;
144
+ const currentCount = this.logCounts.get(key) || 0;
145
+ if (currentCount >= this.maxLogsPerMinute) {
146
+ return false;
147
+ }
148
+ this.logCounts.set(key, currentCount + 1);
149
+ return true;
150
+ }
151
+ /**
152
+ * Reset counters if a minute has passed
153
+ */
154
+ resetIfNeeded() {
155
+ const now = Date.now();
156
+ if (now - this.lastReset >= 60000) { // 1 minute
157
+ this.logCounts.clear();
158
+ this.lastReset = now;
159
+ }
160
+ }
161
+ /**
162
+ * Get current log counts
163
+ */
164
+ getLogCounts() {
165
+ const result = {};
166
+ this.logCounts.forEach((count, level) => {
167
+ result[level] = count;
168
+ });
169
+ return result;
170
+ }
171
+ }
172
+ exports.LogRateLimiter = LogRateLimiter;
@@ -0,0 +1,87 @@
1
+ import { LogEntry, LogLevel, AuditLogEntry } from './types';
2
+ /**
3
+ * Log analysis utilities for parsing and analyzing log data
4
+ */
5
+ export declare class LogAnalyzer {
6
+ private logs;
7
+ /**
8
+ * Add a log entry to the analyzer
9
+ */
10
+ addLog(log: LogEntry): void;
11
+ /**
12
+ * Add multiple log entries
13
+ */
14
+ addLogs(logs: LogEntry[]): void;
15
+ /**
16
+ * Clear all logs
17
+ */
18
+ clear(): void;
19
+ /**
20
+ * Get logs by level
21
+ */
22
+ getLogsByLevel(level: LogLevel): LogEntry[];
23
+ /**
24
+ * Get logs by time range
25
+ */
26
+ getLogsByTimeRange(startTime: string, endTime: string): LogEntry[];
27
+ /**
28
+ * Get logs containing specific text
29
+ */
30
+ getLogsByText(searchText: string): LogEntry[];
31
+ /**
32
+ * Get error frequency analysis
33
+ */
34
+ getErrorAnalysis(): Record<string, number>;
35
+ /**
36
+ * Get performance statistics
37
+ */
38
+ getPerformanceStats(): {
39
+ totalLogs: number;
40
+ errors: number;
41
+ warnings: number;
42
+ info: number;
43
+ debug: number;
44
+ averageLogsPerHour: number;
45
+ };
46
+ /**
47
+ * Get unique users from logs
48
+ */
49
+ getUniqueUsers(): string[];
50
+ /**
51
+ * Get unique request IDs from logs
52
+ */
53
+ getUniqueRequestIds(): string[];
54
+ }
55
+ /**
56
+ * Audit log analyzer for security and compliance analysis
57
+ */
58
+ export declare class AuditLogAnalyzer {
59
+ private auditLogs;
60
+ /**
61
+ * Add an audit log entry
62
+ */
63
+ addAuditLog(log: AuditLogEntry): void;
64
+ /**
65
+ * Get audit logs by actor
66
+ */
67
+ getAuditLogsByActor(actorId: string): AuditLogEntry[];
68
+ /**
69
+ * Get audit logs by action
70
+ */
71
+ getAuditLogsByAction(action: string): AuditLogEntry[];
72
+ /**
73
+ * Get audit logs by target
74
+ */
75
+ getAuditLogsByTarget(target: string): AuditLogEntry[];
76
+ /**
77
+ * Get suspicious activity (high frequency actions)
78
+ */
79
+ getSuspiciousActivity(threshold?: number): Record<string, number>;
80
+ /**
81
+ * Get user activity summary
82
+ */
83
+ getUserActivitySummary(): Record<string, {
84
+ actions: string[];
85
+ count: number;
86
+ }>;
87
+ }