@loglayer/mixin-wide-events 1.0.0

package/README.md

@@ -0,0 +1,9 @@
+# @loglayer/mixin-wide-events
+
+[![npm version](https://img.shields.io/npm/v/@loglayer/mixin-wide-events.svg)](https://www.npmjs.com/package/@loglayer/mixin-wide-events)
+[![npm downloads](https://img.shields.io/npm/dm/@loglayer/mixin-wide-events.svg)](https://www.npmjs.com/package/@loglayer/mixin-wide-events)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+
+Adds wide event logging functionality to LogLayer for comprehensive, self-contained log entries.
+
+[Documentation](https://loglayer.dev/mixins/wide-events) | [API Reference](https://loglayer.dev/mixins/wide-events)

package/dist/index.cjs

@@ -0,0 +1,213 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region ../../core/plugin/dist/index.js
+/**
+* List of plugin callbacks that can be called by the plugin manager.
+*
+* @see {@link https://loglayer.dev/plugins/creating-plugins.html#transformloglevel | transformLogLevel Docs}
+* @see {@link https://loglayer.dev/plugins/creating-plugins.html#onbeforedataout | onBeforeDataOut Docs}
+* @see {@link https://loglayer.dev/plugins/creating-plugins.html#shouldsendtologger | shouldSendToLogger Docs}
+* @see {@link https://loglayer.dev/plugins/creating-plugins.html#onmetadatacalled | onMetadataCalled Docs}
+* @see {@link https://loglayer.dev/plugins/creating-plugins.html#onbeforemessageout | onBeforeMessageOut Docs}
+* @see {@link https://loglayer.dev/plugins/creating-plugins.html#oncontextcalled | onContextCalled Docs}
+*/
+let PluginCallbackType = /* @__PURE__ */ function(PluginCallbackType) {
+	PluginCallbackType["transformLogLevel"] = "transformLogLevel";
+	PluginCallbackType["onBeforeDataOut"] = "onBeforeDataOut";
+	PluginCallbackType["shouldSendToLogger"] = "shouldSendToLogger";
+	PluginCallbackType["onMetadataCalled"] = "onMetadataCalled";
+	PluginCallbackType["onBeforeMessageOut"] = "onBeforeMessageOut";
+	PluginCallbackType["onContextCalled"] = "onContextCalled";
+	return PluginCallbackType;
+}({});
+
+//#endregion
+//#region ../../core/loglayer/dist/index.js
+const CALLBACK_LIST = [
+	PluginCallbackType.onBeforeDataOut,
+	PluginCallbackType.onMetadataCalled,
+	PluginCallbackType.onBeforeMessageOut,
+	PluginCallbackType.transformLogLevel,
+	PluginCallbackType.shouldSendToLogger,
+	PluginCallbackType.onContextCalled
+];
+/**
+* The class that the mixin extends
+*/
+let LogLayerMixinAugmentType = /* @__PURE__ */ function(LogLayerMixinAugmentType) {
+	/**
+	* Mixin extends the LogBuilder prototype
+	*/
+	LogLayerMixinAugmentType["LogBuilder"] = "LogBuilder";
+	/**
+	* Mixin extends the LogLayer prototype
+	*/
+	LogLayerMixinAugmentType["LogLayer"] = "LogLayer";
+	return LogLayerMixinAugmentType;
+}({});
+
+//#endregion
+//#region src/mixin.ts
+/**
+* Creates a LogLayer mixin that adds wide event logging functionality.
+*
+* Wide events are comprehensive, self-contained log entries that capture an entire
+* operation's context and data in a single emission. This pattern helps with
+* observability by ensuring all relevant data is available in one log entry.
+*
+* @param options - Configuration options
+* @param options.asyncContext - An async context implementation for propagating
+*   wide event data across async boundaries. For Node.js, use `new AsyncLocalStorage()`
+*   from `async_hooks`. For browser environments, provide your own compatible implementation.
+* @param options.includeContext - Whether to include withContext() data in emitted wide events (default: true)
+
+*
+* @returns A LogLayer mixin registration object
+*
+* @example
+* ```typescript
+* import { AsyncLocalStorage } from "async_hooks";
+* import { LogLayer, StructuredTransport } from "loglayer";
+* import { createWideEventMixin } from "@loglayer/mixin-wide-events";
+*
+* const wideEventMixin = createWideEventMixin({
+*   asyncContext: new AsyncLocalStorage(),
+* });
+*
+* const log = new LogLayer({
+*   transport: new StructuredTransport({ logger: console }),
+*   mixins: [wideEventMixin],
+* });
+*
+* // Create a child logger for the request
+* const logger = log.child().withContext({ requestId: "123" });
+*
+* // Accumulate data throughout the request
+* logger.withWideEvents({ userId: "456" });
+* await doSomething();
+* logger.withWideEvents({ orderId: "789" });
+*
+* // Emit the wide event
+* logger.emitWideEvent({ message: "Request completed" });
+* ```
+*/
+function createWideEventMixin(options) {
+	const asyncContext = options.asyncContext;
+	const includeContext = options.includeContext ?? true;
+	const wideEventField = options.wideEventField;
+	/**
+	* Context tracker plugin - stores context in async storage
+	* for inclusion in wide events (only if includeContext is true)
+	*/
+	const contextTrackerPlugin = {
+		id: `@loglayer/wide-events-context-tracker-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+		onBeforeDataOut: (params) => {
+			if (!includeContext) return params;
+			const store = asyncContext.getStore();
+			if (store && params.context && Object.keys(params.context).length > 0) {
+				if (!store._llContext) store._llContext = {};
+				Object.assign(store._llContext, params.context);
+			}
+			return params;
+		}
+	};
+	/**
+	* Deep merge utility - merges source into target recursively for nested objects.
+	* Filters out dangerous keys to prevent prototype pollution attacks.
+	* Uses WeakRef to detect circular references.
+	*/
+	function deepMerge(target, source, visited = /* @__PURE__ */ new WeakSet()) {
+		const result = { ...target };
+		for (const key of Object.keys(source)) {
+			if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+			const sourceValue = source[key];
+			const targetValue = result[key];
+			if (sourceValue !== null && typeof sourceValue === "object" && !Array.isArray(sourceValue) && targetValue !== null && typeof targetValue === "object" && !Array.isArray(targetValue)) {
+				if (visited.has(sourceValue)) continue;
+				visited.add(sourceValue);
+				result[key] = deepMerge(targetValue, sourceValue, visited);
+			} else result[key] = sourceValue;
+		}
+		return result;
+	}
+	/**
+	* Implementation for withWideEvents
+	*/
+	function withWideEventsImpl(data, self) {
+		const store = asyncContext.getStore();
+		if (store) {
+			if (!store._llWideEvents) store._llWideEvents = {};
+			store._llWideEvents = deepMerge(store._llWideEvents, data);
+		}
+		return self;
+	}
+	/**
+	* Implementation for getWideEvents
+	*/
+	function getWideEventsImpl(key, _self) {
+		const data = asyncContext.getStore()?._llWideEvents;
+		if (!data) return key ? void 0 : {};
+		if (key !== void 0) return data[key];
+		return { ...data };
+	}
+	/**
+	* Implementation for clearWideEvents
+	*/
+	function clearWideEventsImpl(key, self) {
+		const store = asyncContext.getStore();
+		if (store?._llWideEvents) if (key !== void 0) delete store._llWideEvents[key];
+		else store._llWideEvents = {};
+		return self;
+	}
+	/**
+	* Implementation for emitWideEvent
+	*/
+	function emitWideEventImpl(config, self) {
+		const store = asyncContext.getStore();
+		const wideEventData = {};
+		if (includeContext && store?._llContext) Object.assign(wideEventData, store._llContext);
+		if (store?._llWideEvents) Object.assign(wideEventData, store._llWideEvents);
+		if (config.metadata) Object.assign(wideEventData, config.metadata);
+		const level = config.level ?? "info";
+		const metadataToEmit = wideEventField ? { [wideEventField]: wideEventData } : wideEventData;
+		self.withMetadata(metadataToEmit)[level](config.message);
+		return self;
+	}
+	return {
+		mixinsToAdd: [{
+			augmentationType: LogLayerMixinAugmentType.LogLayer,
+			augment: (prototype) => {
+				prototype.withWideEvents = function(data) {
+					return withWideEventsImpl(data, this);
+				};
+				prototype.getWideEvents = function(key) {
+					return getWideEventsImpl(key, this);
+				};
+				prototype.clearWideEvents = function(key) {
+					return clearWideEventsImpl(key, this);
+				};
+				prototype.emitWideEvent = function(config) {
+					return emitWideEventImpl(config, this);
+				};
+			},
+			augmentMock: (prototype) => {
+				prototype.withWideEvents = function(data) {
+					return withWideEventsImpl(data, this);
+				};
+				prototype.getWideEvents = function(key) {
+					return getWideEventsImpl(key, this);
+				};
+				prototype.clearWideEvents = function(key) {
+					return clearWideEventsImpl(key, this);
+				};
+				prototype.emitWideEvent = function(config) {
+					return emitWideEventImpl(config, this);
+				};
+			}
+		}],
+		pluginsToAdd: [contextTrackerPlugin]
+	};
+}
+
+//#endregion
+exports.createWideEventMixin = createWideEventMixin;