@sprqvntrs/logger 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 SPRQVNTRS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# @sprqvntrs/logger
+
+TypeScript logging package built on [Pino](https://github.com/pinojs/pino) with structured logging, request tracing, and testing utilities.
+
+## Installation
+
+```bash
+pnpm add @sprqvntrs/logger
+```
+
+## Quick Start
+
+```typescript
+import { createLogger } from '@sprqvntrs/logger';
+
+const logger = createLogger({
+  serviceName: 'my-service',
+  level: 'debug', // optional, defaults to LOG_LEVEL env or 'info'
+});
+
+logger.info('Server started', { port: 3000 });
+logger.error('Operation failed', { error: new Error('Something went wrong') });
+
+// Child loggers for scoped context
+const requestLogger = logger.child({ requestId: '123', userId: 'user-456' });
+requestLogger.info('Processing request'); // includes requestId and userId
+```
+
+## Features
+
+- Factory function (`createLogger`) and static class (`StaticLogger`) APIs
+- Type-safe structured logging with `LogContext` interface
+- Child logger support for scoped logging
+- AsyncLocalStorage-based request ID propagation
+- HTTP middleware with path/extension exclusions
+- Server lifecycle presets (start, shutdown, errors)
+- Worker/job logging presets
+- Mock logger and spy utilities for testing
+- Automatic redaction of sensitive fields (passwords, tokens, etc.)
+- Opt-in pretty printing via `pino-pretty` (consumer-installed)
+
+## Entry Points
+
+| Import | Description |
+|--------|-------------|
+| `@sprqvntrs/logger` | Main exports (createLogger, StaticLogger, types, context utils) |
+| `@sprqvntrs/logger/http` | HTTP middleware (createHttpLogger) |
+| `@sprqvntrs/logger/server` | Server/worker lifecycle logging |
+| `@sprqvntrs/logger/testing` | Mock logger for tests |
+
+## API Reference
+
+### `createLogger(options)`
+
+Creates a new logger instance.
+
+```typescript
+interface CreateLoggerOptions {
+  serviceName: string;           // Required: included in all logs
+  level?: LogLevel;              // 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+  version?: string;              // Service version (defaults to npm_package_version)
+  pretty?: boolean;              // Pretty print (default: false, requires pino-pretty installed)
+  redactPaths?: string[];        // Additional paths to redact
+  base?: Record<string, unknown>; // Additional base fields
+  timestamp?: boolean;           // Include timestamp (default: true)
+}
+```
+
+### Logger Methods
+
+```typescript
+interface Logger {
+  trace(message: string, context?: LogContext): void;
+  debug(message: string, context?: LogContext): void;
+  info(message: string, context?: LogContext): void;
+  warn(message: string, context?: LogContext): void;
+  error(message: string, context?: LogContext): void;
+  fatal(message: string, context?: LogContext): void;
+
+  child(bindings: Record<string, unknown>): Logger;
+  readonly pino: PinoLogger; // Access underlying Pino instance
+}
+```
+
+### Static Logger (Backward Compatible)
+
+```typescript
+import Logger from '@sprqvntrs/logger';
+
+// Configure once at startup
+Logger.configure({ serviceName: 'my-service' });
+
+// Use anywhere
+Logger.info('message', { key: 'value' });
+Logger.error('failed', { error: new Error('oops') });
+
+// Create child loggers
+const child = Logger.child({ component: 'auth' });
+```
+
+## HTTP Middleware
+
+```typescript
+import { createHttpLogger } from '@sprqvntrs/logger/http';
+import { createLogger } from '@sprqvntrs/logger';
+
+const logger = createLogger({ serviceName: 'api' });
+
+const httpLogger = createHttpLogger({
+  logger,                                    // Use existing logger
+  excludePaths: ['/health', '/metrics'],     // Don't log these paths
+  excludeExtensions: ['.js', '.css', '.png'], // Don't log static files
+  customProps: (req, res) => ({              // Add custom fields
+    userAgent: req.headers['user-agent'],
+  }),
+});
+
+// Express
+app.use(httpLogger);
+
+// Fastify
+fastify.addHook('onRequest', (req, reply, done) => {
+  httpLogger(req.raw, reply.raw, done);
+});
+```
+
+## Request Context Propagation
+
+Automatically include request IDs in all logs using AsyncLocalStorage:
+
+```typescript
+import {
+  withRequestContext,
+  generateRequestId,
+  createRequestContextMiddleware,
+} from '@sprqvntrs/logger';
+
+// Express middleware
+app.use(createRequestContextMiddleware());
+
+// Or manual context
+app.use((req, res, next) => {
+  const requestId = req.headers['x-request-id'] || generateRequestId();
+  withRequestContext({ requestId }, () => next());
+});
+
+// All subsequent logs automatically include requestId
+logger.info('Processing'); // { requestId: '...', msg: 'Processing' }
+```
+
+## Server Lifecycle Logging
+
+```typescript
+import { createServerLogger } from '@sprqvntrs/logger/server';
+
+const { logger, logServerStart, logShutdown, logServerClosed } =
+  createServerLogger({
+    serviceName: 'api',
+    registerGlobalHandlers: true, // Handle uncaughtException/unhandledRejection
+  });
+
+const server = app.listen(3000, () => {
+  logServerStart(3000, { url: 'http://localhost:3000' });
+});
+
+process.on('SIGTERM', () => {
+  logShutdown('SIGTERM');
+  server.close(() => logServerClosed());
+});
+```
+
+## Worker/Job Logging
+
+```typescript
+import { createWorkerLogger } from '@sprqvntrs/logger/server';
+
+const { logger, logJobStart, logJobComplete, logJobFailed } =
+  createWorkerLogger({ serviceName: 'background-worker' });
+
+async function processJob(job: Job) {
+  const startTime = Date.now();
+  logJobStart(job.id, job.type);
+
+  try {
+    await executeJob(job);
+    logJobComplete(job.id, job.type, Date.now() - startTime);
+  } catch (error) {
+    logJobFailed(job.id, job.type, error);
+    throw error;
+  }
+}
+```
+
+## Testing
+
+```typescript
+import { createMockLogger } from '@sprqvntrs/logger/testing';
+
+describe('MyService', () => {
+  let logger: MockLogger;
+
+  beforeEach(() => {
+    logger = createMockLogger();
+  });
+
+  it('logs user creation', () => {
+    const service = new MyService(logger);
+    service.createUser({ name: 'Test' });
+
+    expect(logger.hasLog((log) =>
+      log.level === 'info' &&
+      log.message.includes('User created')
+    )).toBe(true);
+  });
+
+  it('captures error context', () => {
+    const service = new MyService(logger);
+    service.failingOperation();
+
+    const errorLogs = logger.getLogsByLevel('error');
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0]?.context?.error).toBeDefined();
+  });
+
+  afterEach(() => {
+    logger.clear();
+  });
+});
+```
+
+### Spy Logger
+
+Wrap a real logger to capture calls while still logging:
+
+```typescript
+import { createSpyLogger, createLogger } from '@sprqvntrs/logger/testing';
+
+const realLogger = createLogger({ serviceName: 'test' });
+const { logger, getCalls } = createSpyLogger(realLogger);
+
+logger.info('test message', { key: 'value' });
+
+expect(getCalls('info')).toContainEqual({
+  message: 'test message',
+  context: { key: 'value' },
+});
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LOG_LEVEL` | Log level | `info` |
+| `NODE_ENV` | Included as `env` in log base fields | - |
+
+## Pretty Printing (Development)
+
+Pretty output is **opt-in**. To enable it, install `pino-pretty` as a dev dependency in your application and pass `pretty: true`:
+
+```bash
+pnpm add -D pino-pretty
+```
+
+```typescript
+const logger = createLogger({
+  serviceName: 'my-service',
+  pretty: process.env.NODE_ENV !== 'production', // your choice when to enable
+});
+```
+
+Without `pretty: true`, the logger emits structured JSON regardless of `NODE_ENV` — which is what production log aggregators (Datadog, CloudWatch, Loki) expect. If you pass `pretty: true` without `pino-pretty` installed, Pino will throw at instantiation.
+
+## Automatic Redaction
+
+The following paths are automatically redacted from logs:
+
+- `password`, `token`, `authorization`, `apiKey`, `api_key`, `secret`, `credential`
+- Nested paths: `*.password`, `*.token`, etc.
+- Headers: `headers.authorization`, `headers.cookie`
+
+Add custom redaction paths:
+
+```typescript
+const logger = createLogger({
+  serviceName: 'api',
+  redactPaths: ['*.ssn', 'creditCard'],
+});
+```
+
+## TypeScript
+
+This package exports TypeScript source files directly. Configure your bundler to transpile `node_modules/@sprqvntrs/*`:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true
+  }
+}
+```
+
+## Raw TypeScript
+
+This package ships raw TypeScript (`main` and `types` point at `index.ts`), so a Vite
+consumer (Vite, React Router, Remix) must add the scope to `ssr.noExternal`:
+`ssr: { noExternal: [/^@sprqvntrs\//] }`.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,53 @@
+// Main factory function
+export { createLogger, StaticLogger } from './src/core/logger';
+
+// Backward-compatible default export (static logger)
+export { StaticLogger as default } from './src/core/logger';
+
+// Buffered logger
+export { createBufferedLogger } from './src/core/buffered-logger';
+
+// Flush destinations
+export { jsonDestination } from './src/core/destinations';
+export type { JsonDestinationOptions } from './src/core/destinations';
+
+// Types
+export type {
+  Logger,
+  LogLevel,
+  LogContext,
+  LogEntry,
+  MockLogger,
+  CreateLoggerOptions,
+  LoggerConfigureOptions,
+  HttpLoggerOptions,
+  RequestContext,
+  ServerLogger,
+  BufferedLogger,
+  BufferedLoggerOptions,
+  FlushDestination,
+  SerializedLogEntry,
+} from './src/types';
+
+// Context utilities for request tracing
+export {
+  withRequestContext,
+  withRequestContextAsync,
+  getRequestContext,
+  getRequestId,
+  getContextValue,
+  updateRequestContext,
+  generateRequestId,
+  createRequestContextMiddleware,
+} from './src/context/async-context';
+
+// Serializers (for advanced customization)
+export {
+  errorSerializer,
+  requestSerializer,
+  responseSerializer,
+  getSerializers,
+} from './src/core/serializers';
+
+// Pino config (for advanced customization)
+export { createPinoConfig, createPinoInstance } from './src/core/pino-config';

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@sprqvntrs/logger",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./http": "./src/middleware/http.ts",
+    "./server": "./src/presets/server.ts",
+    "./testing": "./src/testing/mock-logger.ts"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SPRQVNTRS/platform.git",
+    "directory": "packages/logger"
+  },
+  "files": [
+    "src/**/*",
+    "index.ts",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "pino": "^9.6.0",
+    "pino-http": "^10.4.0"
+  },
+  "peerDependencies": {
+    "pino-pretty": "^13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pino-pretty": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "pino-pretty": "^13.0.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/SPRQVNTRS/platform/tree/main/packages/logger#readme",
+  "bugs": {
+    "url": "https://github.com/SPRQVNTRS/platform/issues"
+  }
+}

package/src/context/async-context.ts

@@ -0,0 +1,126 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { RequestContext } from '../types';
+
+/**
+ * AsyncLocalStorage instance for maintaining request context
+ * across async operations
+ */
+const asyncLocalStorage = new AsyncLocalStorage<RequestContext>();
+
+/**
+ * Generates a unique request ID
+ * Uses crypto.randomUUID if available, falls back to timestamp-based ID
+ */
+export function generateRequestId(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  // Fallback for older Node.js versions
+  return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 11)}`;
+}
+
+/**
+ * Run a function with request context
+ * The context will be available to all async operations within the callback
+ *
+ * @example
+ * ```typescript
+ * // In middleware
+ * app.use((req, res, next) => {
+ *   withRequestContext({ requestId: generateRequestId() }, () => {
+ *     next();
+ *   });
+ * });
+ *
+ * // Later in any handler or service
+ * logger.info('Processing'); // requestId automatically included
+ * ```
+ */
+export function withRequestContext<T>(context: RequestContext, fn: () => T): T {
+  return asyncLocalStorage.run(context, fn);
+}
+
+/**
+ * Run an async function with request context
+ * Convenience wrapper for async functions
+ *
+ * @example
+ * ```typescript
+ * await withRequestContextAsync({ requestId: '123' }, async () => {
+ *   await someAsyncOperation();
+ *   logger.info('Done'); // requestId automatically included
+ * });
+ * ```
+ */
+export async function withRequestContextAsync<T>(
+  context: RequestContext,
+  fn: () => Promise<T>
+): Promise<T> {
+  return asyncLocalStorage.run(context, fn);
+}
+
+/**
+ * Get the current request context
+ * Returns undefined if not running within a request context
+ */
+export function getRequestContext(): RequestContext | undefined {
+  return asyncLocalStorage.getStore();
+}
+
+/**
+ * Get a specific value from the current request context
+ */
+export function getContextValue<K extends keyof RequestContext>(
+  key: K
+): RequestContext[K] | undefined {
+  const store = asyncLocalStorage.getStore();
+  return store?.[key];
+}
+
+/**
+ * Get the current request ID from context
+ * Convenience method for the most common use case
+ */
+export function getRequestId(): string | undefined {
+  return getContextValue('requestId');
+}
+
+/**
+ * Update the current request context
+ * Merges new values with existing context
+ * Only works within an active context - no-op otherwise
+ */
+export function updateRequestContext(updates: Partial<RequestContext>): void {
+  const store = asyncLocalStorage.getStore();
+  if (store) {
+    Object.assign(store, updates);
+  }
+}
+
+/**
+ * Create a middleware-style function for Express/Koa/etc
+ * that sets up request context for each request
+ *
+ * @example
+ * ```typescript
+ * // Express
+ * app.use(createRequestContextMiddleware());
+ *
+ * // With custom ID extraction
+ * app.use(createRequestContextMiddleware((req) => ({
+ *   requestId: req.headers['x-request-id'] || generateRequestId(),
+ *   userId: req.user?.id,
+ * })));
+ * ```
+ */
+export function createRequestContextMiddleware(
+  contextExtractor?: (req: unknown) => RequestContext
+): (req: unknown, res: unknown, next: () => void) => void {
+  return (req, _res, next) => {
+    const context = contextExtractor
+      ? contextExtractor(req)
+      : { requestId: generateRequestId() };
+
+    withRequestContext(context, next);
+  };
+}