NOTE

本页由仓库元数据、API reports 或示例目录生成；包名、export subpaths、TypeScript 声明和源码链接保留原文，便于与发布产物逐项核对。

声明内容来自仓库 API report，保留英文注释和 TypeScript 原文，便于与发布产物逐项核对。

@loggerjs/processors API

Generated from packages/processors/dist/**/*.d.ts. 源报告：api-reports/loggerjs-processors.api.md.

breadcrumb-buffer.d.ts

import { type LogEvent, type LoggerLevel, type Processor } from "@loggerjs/core";
export interface Breadcrumb {
    time: number;
    levelName: LogEvent["levelName"];
    logger: string;
    message: string;
    type?: string;
    tags?: LogEvent["tags"];
    source?: LogEvent["source"];
}
export interface BreadcrumbBufferState {
    readonly key: string;
    readonly buffered: number;
    readonly lastSeenMs: number;
}
export interface BreadcrumbBufferProcessor extends Processor {
    states(): readonly BreadcrumbBufferState[];
    reset(key?: string): void;
}
export interface BreadcrumbBufferOptions<TBreadcrumb = Breadcrumb> {
    triggerLevel?: LoggerLevel;
    shouldAttach?: (event: LogEvent) => boolean;
    shouldBuffer?: (event: LogEvent) => boolean;
    bufferSize?: number;
    maxBuckets?: number;
    key?: (event: LogEvent) => string;
    map?: (event: LogEvent) => TBreadcrumb;
    target?: "context" | "data";
    field?: string;
    includeTrigger?: boolean;
    clearOnTrigger?: boolean;
}
export declare function breadcrumbBufferProcessor<TBreadcrumb = Breadcrumb>(options?: BreadcrumbBufferOptions<TBreadcrumb>): BreadcrumbBufferProcessor;

coalesce.d.ts

import { type LogEvent, type Processor } from "@loggerjs/core";
export interface CoalesceOptions {
    windowMs?: number;
    maxEntries?: number;
    key?: (event: LogEvent) => string;
    field?: string;
    updateMessage?: boolean;
}
export declare function coalesceProcessor(options?: CoalesceOptions): Processor;

dedupe.d.ts

import type { LogEvent, Processor } from "@loggerjs/core";
export interface DedupeOptions {
    windowMs?: number;
    maxEntries?: number;
    key?: (event: LogEvent) => string;
}
export declare function dedupeProcessor(options?: DedupeOptions): Processor;

dynamic-sampler.d.ts

import { type EnabledLogLevelName, type LogEvent, type Processor, type ProcessorContext } from "@loggerjs/core";
export interface DynamicSamplerStats {
    readonly key: string;
    readonly seen: number;
    readonly kept: number;
    readonly dropped: number;
    readonly lastSeenMs: number;
}
export interface DynamicSamplerDecisionContext extends DynamicSamplerStats {
    readonly now: number;
}
export type DynamicSampleRate = number | ((event: LogEvent, state: DynamicSamplerDecisionContext) => number);
export interface DynamicSamplerRule {
    rate: DynamicSampleRate;
    when?: (event: LogEvent, context: ProcessorContext) => boolean;
    key?: (event: LogEvent) => string;
    stickyBy?: (event: LogEvent) => string | undefined;
}
export interface DynamicSamplerProcessor extends Processor {
    stats(): readonly DynamicSamplerStats[];
    reset(key?: string): void;
}
export interface DynamicSamplerOptions {
    defaultRate?: DynamicSampleRate;
    rules?: readonly DynamicSamplerRule[];
    key?: (event: LogEvent) => string;
    stickyBy?: (event: LogEvent) => string | undefined;
    random?: () => number;
    exemptLevels?: readonly EnabledLogLevelName[];
    maxKeys?: number;
    onDrop?: (event: LogEvent, key: string, rate: number) => void;
}
export declare function dynamicSamplerProcessor(options?: DynamicSamplerOptions): DynamicSamplerProcessor;

enrich.d.ts

import { type LogEvent, type LogRecord, type Middleware, type MiddlewareContext, type Processor, type ProcessorContext, type Tags, type TraceContext } from "@loggerjs/core";
export interface EnrichPatch {
    message?: string;
    type?: string;
    tags?: Tags;
    data?: unknown;
    context?: Record<string, unknown>;
    trace?: TraceContext;
    source?: LogEvent["source"];
}
export type EnrichInput = EnrichPatch | ((event: LogEvent, context: ProcessorContext) => EnrichPatch | false | void);
export interface EnrichRecordPatch {
    message?: string;
    type?: string;
    tags?: Tags;
    data?: unknown;
    context?: Record<string, unknown>;
    trace?: TraceContext;
    source?: string | LogEvent["source"];
}
export type EnrichMiddlewareInput = EnrichRecordPatch | ((record: LogRecord, context: MiddlewareContext) => EnrichRecordPatch | false | void);
export declare function enrichProcessor(input: EnrichInput): Processor;
export declare function enrichMiddleware(input: EnrichMiddlewareInput): Middleware;

error-fields.d.ts

declare const NATIVE_ERROR_FIELDS: readonly ["cause", "errors"];
type NativeErrorField = (typeof NATIVE_ERROR_FIELDS)[number];
export declare function hiddenErrorFields(value: Error): NativeErrorField[];
export declare function defineHidden(target: Record<string, unknown>, field: string, value: unknown): void;
export declare function dotPath(path: string, field: string): string;
export {};

filter-route.d.ts

import { type EnabledLogLevelName, type LogEvent, type LogEventRoute, type LoggerLevel, type Processor, type ProcessorContext, type Tags } from "@loggerjs/core";
export type EventStringMatcher = string | RegExp | ((value: string | undefined, event: LogEvent) => boolean);
export interface EventMatch {
    when?: (event: LogEvent, context: ProcessorContext) => boolean;
    logger?: EventStringMatcher | readonly EventStringMatcher[];
    type?: EventStringMatcher | readonly EventStringMatcher[];
    integration?: EventStringMatcher | readonly EventStringMatcher[];
    runtime?: EventStringMatcher | readonly EventStringMatcher[];
    levelName?: EnabledLogLevelName | readonly EnabledLogLevelName[];
    tags?: Tags;
    minLevel?: LoggerLevel;
    maxLevel?: LoggerLevel;
}
export type FilterAction = "keep" | "drop";
export type FilterPredicate = (event: LogEvent, context: ProcessorContext) => boolean;
export interface FilterRule extends EventMatch {
    action?: FilterAction;
    reason?: string;
}
export interface FilterOptions {
    rules: readonly FilterRule[];
    defaultAction?: FilterAction;
    onDrop?: (event: LogEvent, reason: string) => void;
}
export type FilterInput = FilterPredicate | readonly FilterRule[] | FilterOptions;
export interface RouteRule extends EventMatch, LogEventRoute {
}
export interface RouteOptions {
    rules: readonly RouteRule[];
    defaultRoute?: LogEventRoute;
}
export type RouteInput = LogEventRoute | readonly RouteRule[] | RouteOptions;
export declare function filterProcessor(input: FilterInput): Processor;
export declare function routeProcessor(input: RouteInput): Processor;

fingerprint.d.ts

import type { LogEvent, Processor, ProcessorContext } from "@loggerjs/core";
export type FingerprintPart = "logger" | "level" | "type" | "message" | "error.name" | "error.message" | "source.integration" | "source.runtime" | "stack.top" | ((event: LogEvent, context: ProcessorContext) => unknown);
export interface FingerprintOptions {
    parts?: readonly FingerprintPart[];
    hash?: (input: string) => string;
    target?: "tags" | "context";
    key?: string;
    separator?: string;
    prefix?: string;
}
export declare function fingerprintProcessor(options?: FingerprintOptions): Processor;

fingers-crossed.d.ts

import { type LogEvent, type LoggerLevel, type Processor, type ProcessorContext, type Transport } from "@loggerjs/core";
export type FingersCrossedDropReason = "buffer-full" | "bucket-pruned";
export type FingersCrossedFlush = (events: readonly LogEvent[], context: ProcessorContext) => void | Promise<void>;
export interface FingersCrossedState {
    readonly key: string;
    readonly buffered: number;
    readonly activeUntilMs: number;
    readonly lastSeenMs: number;
}
export interface FingersCrossedProcessor extends Processor {
    states(): readonly FingersCrossedState[];
    reset(key?: string): void;
}
export interface FingersCrossedOptions {
    triggerLevel?: LoggerLevel;
    shouldTrigger?: (event: LogEvent) => boolean;
    bufferSize?: number;
    activationMs?: number;
    flushTo?: Transport | FingersCrossedFlush;
    includeTrigger?: boolean;
    passthroughTrigger?: boolean;
    passthroughAfterTrigger?: boolean;
    key?: (event: LogEvent) => string;
    maxBuckets?: number;
    onTrigger?: (event: LogEvent, buffered: readonly LogEvent[], key: string) => void;
    onDrop?: (event: LogEvent, reason: FingersCrossedDropReason, key: string) => void;
}
export declare function fingersCrossedProcessor(options?: FingersCrossedOptions): FingersCrossedProcessor;

index.d.ts

export * from "./redact.js";
export * from "./sample.js";
export * from "./tags.js";
export * from "./coalesce.js";
export * from "./dedupe.js";
export * from "./trace.js";
export * from "./rate-limit.js";
export * from "./fingers-crossed.js";
export * from "./enrich.js";
export * from "./level-override.js";
export * from "./filter-route.js";
export * from "./fingerprint.js";
export * from "./normalize-error.js";
export * from "./stack-parser.js";
export * from "./symbolicate-stack.js";
export * from "./privacy-guard.js";
export * from "./schema-dev-check.js";
export * from "./dynamic-sampler.js";
export * from "./breadcrumb-buffer.js";
export { redactProcessor as redact } from "./redact.js";
export { sampleProcessor as sample } from "./sample.js";
export { coalesceProcessor as coalesce } from "./coalesce.js";
export { tagsMiddleware, typeMiddleware, contextMiddleware, tagsProcessor as tags, tagsMiddleware as tagsMw, typeProcessor as logType, typeMiddleware as logTypeMw, contextProcessor as context, contextMiddleware as contextMw, } from "./tags.js";
export { dedupeProcessor as dedupe } from "./dedupe.js";
export { traceContextMiddleware, traceContextProcessor as traceContext, traceContextMiddleware as traceContextMw, } from "./trace.js";
export { rateLimitProcessor as rateLimit } from "./rate-limit.js";
export { fingersCrossedProcessor as fingersCrossed } from "./fingers-crossed.js";
export { enrichMiddleware, enrichProcessor as enrich, enrichMiddleware as enrichMw, } from "./enrich.js";
export { levelOverrideProcessor as levelOverride } from "./level-override.js";
export { filterProcessor as filter, routeProcessor as route } from "./filter-route.js";
export { fingerprintProcessor as fingerprint } from "./fingerprint.js";
export { normalizeErrorProcessor as normalizeError } from "./normalize-error.js";
export { stackParserProcessor as stackParser } from "./stack-parser.js";
export { symbolicateStackProcessor as symbolicateStack } from "./symbolicate-stack.js";
export { privacyGuardProcessor as privacyGuard } from "./privacy-guard.js";
export { schemaDevCheckProcessor as schemaDevCheck } from "./schema-dev-check.js";
export { dynamicSamplerProcessor as dynamicSampler } from "./dynamic-sampler.js";
export { breadcrumbBufferProcessor as breadcrumbBuffer } from "./breadcrumb-buffer.js";

level-override.d.ts

import { type LogEvent, type LoggerLevel, type Processor, type ProcessorContext, type Tags } from "@loggerjs/core";
export type LevelOverrideStringMatcher = string | RegExp | ((value: string | undefined, event: LogEvent) => boolean);
export type LevelOverrideValue = LoggerLevel | false | undefined | ((event: LogEvent, context: ProcessorContext) => LoggerLevel | false | void);
export interface LevelOverrideRule {
    level: LevelOverrideValue;
    when?: (event: LogEvent, context: ProcessorContext) => boolean;
    logger?: LevelOverrideStringMatcher | readonly LevelOverrideStringMatcher[];
    type?: LevelOverrideStringMatcher | readonly LevelOverrideStringMatcher[];
    integration?: LevelOverrideStringMatcher | readonly LevelOverrideStringMatcher[];
    runtime?: LevelOverrideStringMatcher | readonly LevelOverrideStringMatcher[];
    tags?: Tags;
    minLevel?: LoggerLevel;
    maxLevel?: LoggerLevel;
}
export interface LevelOverrideOptions {
    rules: readonly LevelOverrideRule[];
}
export type LevelOverrideInput = LevelOverrideValue | readonly LevelOverrideRule[] | LevelOverrideOptions;
export declare function levelOverrideProcessor(input: LevelOverrideInput): Processor;

normalize-error.d.ts

import type { Processor, SerializedError } from "@loggerjs/core";
export interface NormalizeErrorProcessorOptions {
    maxDepth?: number;
    maxStackLines?: number;
    includeEnumerableProperties?: boolean;
    includeAggregateErrors?: boolean;
    dataErrorKeys?: readonly string[];
}
export interface NormalizedError extends SerializedError {
    cause?: NormalizedError;
    errors?: NormalizedError[];
}
export declare function normalizeErrorProcessor(options?: NormalizeErrorProcessorOptions): Processor;

privacy-guard.d.ts

import type { Processor } from "@loggerjs/core";
export type PrivacyGuardMatcher = string | symbol | RegExp | ((key: string, path: string, value: unknown) => boolean);
export type PrivacyGuardTarget = "message" | "data" | "context" | "tags" | "error";
export interface PrivacyPattern {
    name: string;
    pattern: RegExp;
    replacement?: string;
    validate?: (match: string) => boolean;
}
export interface PrivacyGuardOptions {
    targets?: readonly PrivacyGuardTarget[];
    denyKeys?: readonly PrivacyGuardMatcher[];
    allowKeys?: readonly PrivacyGuardMatcher[];
    patterns?: readonly PrivacyPattern[];
    replacement?: string;
    maxDepth?: number;
    maxStringLength?: number;
    truncateSuffix?: string;
    onRedact?: (path: string, reason: string) => void;
}
export declare function privacyGuardProcessor(options?: PrivacyGuardOptions): Processor;

rate-limit.d.ts

import { type EnabledLogLevelName, type LogEvent, type Processor } from "@loggerjs/core";
export interface RateLimitBucket {
    readonly key: string;
    readonly tokens: number;
    readonly lastRefillMs: number;
}
export interface RateLimitProcessor extends Processor {
    buckets(): readonly RateLimitBucket[];
}
export interface RateLimitOptions {
    capacity?: number;
    refillPerSecond?: number;
    key?: (event: LogEvent) => string;
    exemptLevels?: readonly EnabledLogLevelName[];
    maxBuckets?: number;
    onDrop?: (event: LogEvent, key: string) => void;
}
export declare function rateLimitProcessor(options?: RateLimitOptions): RateLimitProcessor;

redact.d.ts

import type { Processor } from "@loggerjs/core";
export type RedactMatcher = string | symbol | RegExp | ((key: string, path: string, value: unknown) => boolean);
export interface RedactOptions {
    keys?: RedactMatcher[];
    paths?: string[];
    replacement?: string;
    censor?: string;
    remove?: boolean;
    maxDepth?: number;
}
export declare function redactProcessor(options?: RedactOptions): Processor;

sample.d.ts

import type { EnabledLogLevelName, Processor } from "@loggerjs/core";
export interface SampleOptions {
    defaultRate?: number;
    rates?: Partial<Record<EnabledLogLevelName, number>>;
    random?: () => number;
}
export declare function sampleProcessor(options?: SampleOptions): Processor;

schema-dev-check.d.ts

import type { LogEvent, Processor, ProcessorContext } from "@loggerjs/core";
export type SchemaCheckResult = true | false | string | readonly string[] | void;
export type SchemaValidator = (data: unknown, event: LogEvent, context: ProcessorContext) => SchemaCheckResult;
export type SchemaDevCheckAction = "report" | "tag" | "drop";
export interface SchemaDevCheckOptions {
    enabled?: boolean;
    action?: SchemaDevCheckAction;
    validators?: Readonly<Record<string, SchemaValidator>>;
    validate?: SchemaValidator;
    select?: (event: LogEvent, context: ProcessorContext) => SchemaValidator | undefined;
    tagKey?: string;
    contextKey?: string;
    onInvalid?: (event: LogEvent, errors: readonly string[]) => void;
}
export declare function schemaDevCheckProcessor(options?: SchemaDevCheckOptions): Processor;

stack-parser.d.ts

import type { Processor } from "@loggerjs/core";
export interface StackFrame {
    raw?: string;
    function?: string;
    file?: string;
    line?: number;
    column?: number;
}
export interface StackParserOptions {
    maxFrames?: number;
    dropInternal?: boolean;
    includeRaw?: boolean;
    target?: "error" | "context";
    key?: string;
    parser?: (stack: string) => readonly StackFrame[];
}
export declare function parseStack(stack: string): StackFrame[];
export declare function stackParserProcessor(options?: StackParserOptions): Processor;

symbolicate-stack.d.ts

import type { LogEvent, Processor } from "@loggerjs/core";
import { type StackFrame } from "./stack-parser.js";
export interface SymbolicatedStackFrame extends StackFrame {
    original?: StackFrame;
}
export interface SymbolicateStackOptions {
    maxFrames?: number;
    sourceKey?: string;
    target?: "error" | "context";
    key?: string;
    mode?: "annotate" | "replace";
    symbolicate: (frame: StackFrame, event: LogEvent) => StackFrame | undefined;
}
export declare function symbolicateStackProcessor(options: SymbolicateStackOptions): Processor;

tags.d.ts

import { type Middleware, type Processor, type Tags } from "@loggerjs/core";
export declare function tagsMiddleware(tags: Tags): Middleware;
export declare function typeMiddleware(type: string): Middleware;
export declare function contextMiddleware(context: Record<string, unknown>): Middleware;
export declare function tagsProcessor(tags: Tags): Processor;
export declare function typeProcessor(type: string): Processor;
export declare function contextProcessor(context: Record<string, unknown>): Processor;

trace.d.ts

import { type Middleware, type Processor, type TraceContext } from "@loggerjs/core";
export type TraceContextProvider = () => TraceContext | undefined;
export declare function traceContextMiddleware(provider: TraceContextProvider): Middleware;
export declare function traceContextProcessor(provider: TraceContextProvider): Processor;