@loggerjs/processors 0.0.2 → 0.1.0

package/README.md

@@ -1,31 +1,44 @@
 # @loggerjs/processors
 
-Compatibility processor package for common synchronous middleware behavior.
+> The composable middleware and processor toolbox for LoggerJS — redact, sample, dedupe, rate-limit, fingerprint, enrich, route, and buffer.
+
+[![npm](https://img.shields.io/npm/v/@loggerjs/processors.svg)](https://www.npmjs.com/package/@loggerjs/processors)
+[![license](https://img.shields.io/npm/l/@loggerjs/processors)](../../LICENSE)
+
+Synchronous, error-isolated steps that run inside the [LoggerJS](../../README.md) pipeline before delivery. **Middleware** run on the raw `LogRecord` (before id/message/error work); **processors** run on the projected `LogEvent`. Both are sandboxed — a throwing step is reported to logger meta and never corrupts other records or blocks delivery.
+
+## Install
+
+```bash
+npm install @loggerjs/processors
+```
+
+## Usage
+
+```ts
+import { createLogger } from "@loggerjs/node";
+import { redactProcessor, sampleProcessor, tagsMiddleware } from "@loggerjs/processors";
+
+const logger = createLogger({
+  category: ["api"],
+  middleware: [tagsMiddleware({ service: "checkout" })],
+  processors: [
+    redactProcessor({ keys: ["password", "token", /secret/i] }),
+    sampleProcessor({ rates: { debug: 0.1, info: 1, warn: 1, error: 1, fatal: 1 } }),
+  ],
+});
+```
+
+<details>
+<summary>Full example — middleware and processors side by side</summary>
 
 ```ts
 import {
-  contextMiddleware,
-  enrichMiddleware,
-  tagsMiddleware,
-  traceContextMiddleware,
-  typeMiddleware,
-  breadcrumbBufferProcessor,
-  dedupeProcessor,
-  dynamicSamplerProcessor,
-  enrichProcessor,
-  filterProcessor,
-  fingerprintProcessor,
-  fingersCrossedProcessor,
-  levelOverrideProcessor,
-  normalizeErrorProcessor,
-  privacyGuardProcessor,
-  rateLimitProcessor,
-  redactProcessor,
-  routeProcessor,
-  sampleProcessor,
-  schemaDevCheckProcessor,
-  stackParserProcessor,
-  tagsProcessor,
+  contextMiddleware, enrichMiddleware, tagsMiddleware, traceContextMiddleware, typeMiddleware,
+  breadcrumbBufferProcessor, dedupeProcessor, dynamicSamplerProcessor, enrichProcessor,
+  filterProcessor, fingerprintProcessor, fingersCrossedProcessor, levelOverrideProcessor,
+  normalizeErrorProcessor, privacyGuardProcessor, rateLimitProcessor, redactProcessor,
+  routeProcessor, sampleProcessor, schemaDevCheckProcessor, stackParserProcessor, tagsProcessor,
 } from "@loggerjs/processors";
 
 const middleware = [
@@ -59,9 +72,33 @@ const processors = [
 ];
 ```
 
-Prefer record middleware for metadata and enrichment that can run before event projection. Legacy
-processors remain available for compatibility and for event-only behavior such as routing, schema
-checks, sampling, buffering, and filtering. Expensive I/O and serialization belong in transports.
-`fingersCrossedProcessor` can receive a `flushTo` transport or sink when buffered pre-trigger events
-must be replayed. `routeProcessor` targets transport names, so configure named transports when using
-per-event routing.
+</details>
+
+## The toolbox
+
+| Group | Steps |
+| --- | --- |
+| **Redaction & privacy** | `redactProcessor`, `privacyGuardProcessor` |
+| **Sampling & volume** | `sampleProcessor`, `dynamicSamplerProcessor`, `rateLimitProcessor`, `dedupeProcessor`, `coalesceProcessor` |
+| **Enrichment & tagging** | `enrichProcessor` / `enrichMiddleware`, `tagsProcessor` / `tagsMiddleware`, `typeProcessor` / `typeMiddleware`, `contextProcessor` / `contextMiddleware`, `traceContextProcessor` / `traceContextMiddleware` |
+| **Errors** | `normalizeErrorProcessor`, `fingerprintProcessor`, `stackParserProcessor`, `symbolicateStackProcessor` |
+| **Routing & control** | `routeProcessor`, `filterProcessor`, `levelOverrideProcessor` |
+| **Buffering** | `fingersCrossedProcessor`, `breadcrumbBufferProcessor` |
+| **Development** | `schemaDevCheckProcessor` |
+
+## Ordering & cost
+
+- **Prefer middleware** for metadata and enrichment that can run before event projection — it's the cheapest place to drop or annotate a record.
+- **Use processors** for event-only behavior: routing, schema checks, sampling, buffering, and filtering on the resolved event shape.
+- **Configuring any processor disables the record fast path** for that logger, because every log must then be projected to an event. That is the correct trade when you need event-level behavior — see [PROCESSORS.md](../../docs/PROCESSORS.md) and [PERFORMANCE.md](../../docs/PERFORMANCE.md).
+- `fingersCrossedProcessor` accepts a `flushTo` transport or sink to replay buffered pre-trigger events. `routeProcessor` targets **named** transports, so name the transports you route to. Expensive I/O and serialization belong in transports, not processors.
+
+## Documentation
+
+- [Processors](../../docs/PROCESSORS.md) — the full reference and ordering guidance
+- [Operations](../../docs/OPERATIONS.md) — privacy defaults and what to redact
+- [Concepts](../../docs/CONCEPTS.md) · [LoggerJS root README](../../README.md)
+
+## License
+
+[MIT](../../LICENSE) © JS Kits

package/dist/coalesce.d.ts

@@ -0,0 +1,10 @@
+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;
+//# sourceMappingURL=coalesce.d.ts.map

package/dist/coalesce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce.d.ts","sourceRoot":"","sources":["../src/coalesce.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,MAAM,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAgCD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,eAAoB,GAAG,SAAS,CAqC1E"}

package/dist/index.cjs

@@ -127,6 +127,58 @@ function contextProcessor(context) {
 	});
 }
 //#endregion
+//#region src/coalesce.ts
+function attachCoalesced(event, field, key, state, updateMessage) {
+	if (state.count <= 1) return event;
+	const payload = {
+		key,
+		count: state.count,
+		firstSeen: state.firstSeen,
+		lastSeen: state.lastSeen
+	};
+	return {
+		...event,
+		message: updateMessage ? `${event.message} (x${state.count})` : event.message,
+		data: event.data && typeof event.data === "object" && !Array.isArray(event.data) ? {
+			...event.data,
+			[field]: payload
+		} : {
+			value: event.data,
+			[field]: payload
+		}
+	};
+}
+function coalesceProcessor(options = {}) {
+	const windowMs = options.windowMs ?? 1e3;
+	const maxEntries = options.maxEntries ?? 1e3;
+	const field = options.field ?? "coalesced";
+	const updateMessage = options.updateMessage ?? true;
+	const keyFor = options.key ?? ((event) => `${event.levelName}:${event.message}:${event.error?.message ?? ""}`);
+	const seen = /* @__PURE__ */ new Map();
+	return (event, context) => {
+		const now = context.now();
+		const key = keyFor(event);
+		const previous = seen.get(key);
+		if (previous && now - previous.lastSeen < windowMs) {
+			previous.count += 1;
+			previous.lastSeen = now;
+			(0, _loggerjs_core.incrementLoggerMetaCounter)("processor.coalesce.suppressed");
+			return false;
+		}
+		const next = {
+			firstSeen: now,
+			lastSeen: now,
+			count: 1
+		};
+		seen.set(key, next);
+		if (seen.size > maxEntries) {
+			const cutoff = now - windowMs;
+			for (const [entryKey, state] of seen) if (state.lastSeen < cutoff || seen.size > maxEntries) seen.delete(entryKey);
+		}
+		return previous ? attachCoalesced(event, field, key, previous, updateMessage) : event;
+	};
+}
+//#endregion
 //#region src/dedupe.ts
 function dedupeProcessor(options = {}) {
 	const windowMs = options.windowMs ?? 1e3;
@@ -825,7 +877,7 @@ function normalizeFrames(frames, options) {
 	}
 	return out;
 }
-function writeFrames(event, options, frames) {
+function writeFrames$1(event, options, frames) {
 	if (options.target === "context") return {
 		...event,
 		context: {
@@ -858,7 +910,60 @@ function stackParserProcessor(options = {}) {
 		const stack = event.error?.stack;
 		if (!stack || normalized.maxFrames === 0) return event;
 		const frames = normalizeFrames(normalized.parser(stack), normalized);
-		return frames.length > 0 ? writeFrames(event, normalized, frames) : event;
+		return frames.length > 0 ? writeFrames$1(event, normalized, frames) : event;
+	};
+}
+//#endregion
+//#region src/symbolicate-stack.ts
+function frameListFromEvent(event, sourceKey) {
+	const existing = event.error?.[sourceKey];
+	if (Array.isArray(existing)) return existing;
+	const stack = event.error?.stack;
+	return stack ? parseStack(stack) : [];
+}
+function applySymbolication(frame, event, options) {
+	const original = options.symbolicate(frame, event);
+	if (!original) return frame;
+	if (options.mode === "replace") return {
+		...original,
+		raw: frame.raw
+	};
+	return {
+		...frame,
+		original
+	};
+}
+function writeFrames(event, target, key, frames) {
+	if (target === "context") return {
+		...event,
+		context: {
+			...event.context,
+			[key]: frames
+		}
+	};
+	return {
+		...event,
+		error: {
+			message: event.error?.message ?? event.message,
+			...event.error,
+			[key]: frames
+		}
+	};
+}
+function symbolicateStackProcessor(options) {
+	const maxFrames = Math.max(0, Math.floor(options.maxFrames ?? 20));
+	const sourceKey = options.sourceKey ?? "frames";
+	const target = options.target ?? "error";
+	const key = options.key ?? "symbolicatedFrames";
+	const mode = options.mode ?? "annotate";
+	return (event) => {
+		if (maxFrames === 0) return event;
+		const frames = frameListFromEvent(event, sourceKey).slice(0, maxFrames);
+		if (frames.length === 0) return event;
+		return writeFrames(event, target, key, frames.map((frame) => applySymbolication(frame, event, {
+			mode,
+			symbolicate: options.symbolicate
+		})));
 	};
 }
 //#endregion
@@ -1326,6 +1431,8 @@ function breadcrumbBufferProcessor(options = {}) {
 //#endregion
 exports.breadcrumbBuffer = breadcrumbBufferProcessor;
 exports.breadcrumbBufferProcessor = breadcrumbBufferProcessor;
+exports.coalesce = coalesceProcessor;
+exports.coalesceProcessor = coalesceProcessor;
 exports.context = contextProcessor;
 exports.contextMiddleware = contextMiddleware;
 exports.contextMw = contextMiddleware;
@@ -1365,6 +1472,8 @@ exports.schemaDevCheck = schemaDevCheckProcessor;
 exports.schemaDevCheckProcessor = schemaDevCheckProcessor;
 exports.stackParser = stackParserProcessor;
 exports.stackParserProcessor = stackParserProcessor;
+exports.symbolicateStack = symbolicateStackProcessor;
+exports.symbolicateStackProcessor = symbolicateStackProcessor;
 exports.tags = tagsProcessor;
 exports.tagsMiddleware = tagsMiddleware;
 exports.tagsMw = tagsMiddleware;