Types Reference
Complete TypeScript type definitions for cenglu logger
Types Reference
Complete TypeScript type definitions for cenglu. All types are exported from the main package and can be imported directly.
import type {
Logger,
LogLevel,
LogRecord,
LoggerOptions,
Transport,
LoggerPlugin,
// ... any other types
} from "cenglu";Core Types
LogLevel
Log severity levels in order of priority:
type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";Priority order:
trace(10) - Most verbose, development debuggingdebug(20) - Detailed debugging informationinfo(30) - General informational messages (default)warn(40) - Warning messageserror(50) - Error messagesfatal(60) - Critical errors that may cause shutdown
Bindings
Context object with arbitrary key-value pairs:
type Bindings = {
[key: string]: unknown;
};Used for:
- Log context:
logger.info("message", { userId: 123 }) - Child logger bindings:
logger.child({ service: "auth" }) - Temporary bindings:
logger.with({ requestId: "abc" })
LogRecord
Complete log record structure passed through the logging pipeline:
type LogRecord = {
time: number; // Timestamp in milliseconds since epoch
level: LogLevel; // Log level
msg: string; // Log message
context?: Bindings; // Additional context
err?: ErrorInfo | null; // Error details (if present)
service?: string; // Service name
env?: string; // Environment (dev, prod, etc.)
version?: string; // Application version
traceId?: string; // Distributed tracing ID
spanId?: string; // Distributed tracing span ID
};Example:
{
time: 1700000000000,
level: "info",
msg: "User created",
context: { userId: 123, email: "user@example.com" },
service: "user-service",
env: "production",
version: "1.2.3",
traceId: "abc-123",
}ErrorInfo
Structured error information extracted from Error objects:
type ErrorInfo = {
name?: string; // Error name (e.g., "ValidationError")
message?: string; // Error message
stack?: string; // Stack trace
code?: string | number; // Error code
cause?: ErrorInfo; // Error cause chain
[key: string]: unknown; // Additional error properties
};Supports error cause chains for nested errors:
{
name: "ApiError",
message: "Failed to fetch user",
code: "API_ERROR",
cause: {
name: "NetworkError",
message: "Connection timeout",
code: "ETIMEDOUT"
}
}TraceContext
Distributed tracing context for correlation across services:
type TraceContext = {
traceId?: string; // Unique trace identifier
spanId?: string; // Unique span identifier
};Configuration Types
LoggerOptions
Main configuration object for createLogger():
type LoggerOptions = {
// Basic configuration
level?: LogLevel; // Minimum log level (default: "info")
service?: string; // Service name
env?: string; // Environment name
version?: string; // Application version
bindings?: Bindings; // Default bindings for all logs
// Output configuration
console?: ConsoleOptions; // Console output settings
file?: FileOptions; // File output settings
pretty?: PrettyOptions; // Pretty formatting for development
structured?: StructuredFormat; // Structured format (JSON, ECS, etc.)
// Extensions
adapters?: ProviderAdapter[]; // Legacy provider adapters
transports?: Transport[]; // Custom transports
plugins?: LoggerPlugin[]; // Logger plugins
// Advanced features
sampling?: SamplingOptions; // Log sampling configuration
redaction?: RedactionOptions; // Sensitive data redaction
// Context & correlation
correlationId?: string | (() => string | undefined); // Correlation ID generator
traceProvider?: () => TraceContext | undefined; // Trace context provider
useAsyncContext?: boolean; // Enable AsyncLocalStorage (default: true)
// Testing/mocking
now?: () => number; // Custom time function
random?: () => number; // Custom random function
};ConsoleOptions
Console transport configuration:
type ConsoleOptions = {
enabled?: boolean; // Enable console output (default: true)
stream?: NodeJS.WritableStream; // Output stream for non-error logs
errorStream?: NodeJS.WritableStream; // Output stream for error logs
};Example:
{
enabled: true,
stream: process.stdout,
errorStream: process.stderr,
}FileOptions
File transport configuration with rotation support:
type FileOptions = {
enabled?: boolean; // Enable file logging (default: false)
dir?: string; // Log directory (default: "./logs")
filename?: (info: { // Custom filename generator
date: Date;
level: LogLevel;
sequence: number;
}) => string;
separateErrors?: boolean; // Write errors to separate file
rotation?: FileRotationPolicy; // File rotation settings
};FileRotationPolicy
File rotation and retention policy:
type FileRotationPolicy = {
intervalDays?: number; // Rotate every N days (default: 1)
maxBytes?: number; // Max file size before rotation
maxFiles?: number; // Max number of rotated files to keep
compress?: "gzip" | false; // Compression format (default: false)
retentionDays?: number; // Delete files older than N days
};Example:
{
intervalDays: 1,
maxBytes: 10 * 1024 * 1024, // 10MB
maxFiles: 7,
compress: "gzip",
retentionDays: 30,
}PrettyOptions
Human-readable formatting for development:
type PrettyOptions = {
enabled?: boolean; // Enable pretty formatting
theme?: Partial<Theme>; // Color theme
formatter?: (record: LogRecord) => string; // Custom formatter
};Theme
Color theme for pretty formatting:
type Theme = {
dim: (s: string) => string; // Dim text
gray: (s: string) => string; // Gray text
red: (s: string) => string; // Red text (errors)
yellow: (s: string) => string; // Yellow text (warnings)
green: (s: string) => string; // Green text (success)
cyan: (s: string) => string; // Cyan text (info)
magenta: (s: string) => string; // Magenta text
bold: (s: string) => string; // Bold text
};StructuredFormat
Structured output format configuration:
type StructuredFormat = {
type?: "json" | "ecs" | "datadog" | "splunk" | "logfmt"; // Format type
transform?: (record: LogRecord) => unknown; // Custom transformer
};Format types:
json- Standard JSON formatecs- Elasticsearch Common Schemadatadog- Datadog log formatsplunk- Splunk-compatible formatlogfmt- Logfmt key=value format
SamplingOptions
Log sampling configuration:
type SamplingOptions = {
rates?: Partial<Record<LogLevel, number>>; // Per-level sampling rates
defaultRate?: number; // Default rate (0.0 to 1.0)
};Example:
{
defaultRate: 0.1, // Sample 10% by default
rates: {
error: 1.0, // Always log errors
warn: 0.5, // Sample 50% of warnings
debug: 0.01, // Sample 1% of debug logs
}
}RedactionOptions
Sensitive data redaction configuration:
type RedactionOptions = {
enabled?: boolean; // Enable redaction
patterns?: RedactionPattern[]; // Custom patterns
paths?: string[]; // Object paths to redact
useDefaults?: boolean; // Use built-in patterns
customRedactor?: (value: unknown, key?: string) => unknown; // Custom redactor
};RedactionPattern
Custom redaction pattern:
type RedactionPattern = {
pattern: RegExp; // Regex pattern to match
replacement?: string; // Replacement text (default: "[REDACTED]")
name?: string; // Pattern name for debugging
};Example:
{
pattern: /api[_-]?key[:\s]+[\w-]+/gi,
replacement: "[API_KEY_REDACTED]",
name: "api-key",
}Transport Types
Transport
Synchronous transport interface:
type Transport = {
/**
* Write a log record
* @param record - The log record
* @param formatted - Pre-formatted string (JSON, etc.)
* @param isError - Whether this is an error-level log
*/
write(record: LogRecord, formatted: string, isError: boolean): void;
/**
* Flush any buffered logs (optional)
*/
flush?(): Promise<void>;
/**
* Close transport and cleanup resources (optional)
*/
close?(): Promise<void>;
};AsyncTransport
Asynchronous transport interface:
type AsyncTransport = {
/**
* Write a log record asynchronously
*/
write(record: LogRecord, formatted: string, isError: boolean): Promise<void>;
/**
* Flush any buffered logs (optional)
*/
flush?(): Promise<void>;
/**
* Close transport and cleanup resources (optional)
*/
close?(): Promise<void>;
/**
* Error handler for async operations (optional)
*/
onError?: (error: Error, record: LogRecord) => void;
};Plugin Types
LoggerPlugin
Plugin interface for extending logger functionality:
type LoggerPlugin = {
readonly name: string; // Unique plugin name
readonly order?: number; // Execution order (default: 100)
/**
* Called once during logger initialization
*/
onInit?(logger: unknown): void;
/**
* Transform or filter log records
* Return null to drop the log
*/
onRecord?(record: LogRecord): LogRecord | null;
/**
* Modify formatted output
*/
onFormat?(record: LogRecord, formatted: string): string;
/**
* Post-write hook (after transport write)
*/
onWrite?(record: LogRecord, formatted: string): void;
/**
* Called on logger.flush()
*/
onFlush?(): Promise<void> | void;
/**
* Called on logger.close()
*/
onClose?(): Promise<void> | void;
};Execution order:
onInit- During logger creationonRecord- Before formatting (can filter/transform)onFormat- After formatting- Transport write
onWrite- After transport writeonFlush- On flushonClose- On close
ProviderAdapter
Legacy adapter interface for provider compatibility:
type ProviderAdapter = {
readonly name: string; // Adapter name
level?: LogLevel; // Adapter-specific level
handle(record: LogRecord): void | Promise<void>; // Handle log record
};State Types
LoggerState
Current logger state (read-only):
type LoggerState = {
readonly level: LogLevel; // Current log level
readonly service?: string; // Service name
readonly env?: string; // Environment
readonly version?: string; // Version
readonly bindings: Readonly<Bindings>; // Current bindings
};Access via logger.state:
const { level, service, bindings } = logger.state;LoggerConfig
Current logger configuration (read-only):
type LoggerConfig = {
readonly pretty: Readonly<{
enabled: boolean;
theme: Partial<Theme>;
formatter?: (record: LogRecord) => string;
}>;
readonly structured: Readonly<{
type: "json" | "ecs" | "datadog" | "splunk" | "logfmt";
transform?: (record: LogRecord) => unknown;
}>;
readonly sampling?: Readonly<SamplingOptions>;
readonly correlationId?: string | (() => string | undefined);
readonly traceProvider?: () => TraceContext | undefined;
readonly now: () => number;
readonly random: () => number;
readonly useAsyncContext: boolean;
};Access via logger.config:
const { structured, sampling } = logger.config;Utility Types
TimerResult
Return type from logger.time():
type TimerResult = {
(): void; // End timer and log
end(): void; // End timer and log
elapsed(): number; // Get elapsed time without logging
endWithContext(context: Bindings): void; // End with additional context
};Usage:
const done = logger.time("operation", { taskId: 123 });
// ... do work ...
done(); // Logs with duration
// Or
const timer = logger.time("query");
const ms = timer.elapsed(); // Get elapsed time
timer.endWithContext({ rows: 10 }); // End with contextTreeOptions
Options for object tree formatting:
type TreeOptions = {
maxDepth?: number; // Maximum nesting depth
maxArrayLength?: number; // Maximum array elements to show
maxStringLength?: number; // Maximum string length
};FormatterType
Available formatter types:
type FormatterType = "json" | "pretty" | "ecs" | "datadog" | "splunk" | "logfmt";Type Guards
Cenglu doesn't export type guards, but you can create your own:
function isLogRecord(obj: unknown): obj is LogRecord {
return (
typeof obj === "object" &&
obj !== null &&
"level" in obj &&
"msg" in obj &&
"time" in obj
);
}
function isErrorInfo(obj: unknown): obj is ErrorInfo {
return (
typeof obj === "object" &&
obj !== null &&
("message" in obj || "name" in obj || "stack" in obj)
);
}Import Examples
// Core types
import type {
Logger,
LogLevel,
LogRecord,
Bindings,
ErrorInfo,
} from "cenglu";
// Configuration types
import type {
LoggerOptions,
ConsoleOptions,
FileOptions,
PrettyOptions,
StructuredFormat,
SamplingOptions,
RedactionOptions,
} from "cenglu";
// Extension types
import type {
Transport,
AsyncTransport,
LoggerPlugin,
ProviderAdapter,
} from "cenglu";
// State types
import type {
LoggerState,
LoggerConfig,
TimerResult,
} from "cenglu";
// Utility types
import type {
TraceContext,
Theme,
TreeOptions,
FormatterType,
} from "cenglu";