@loglayer/mixin-wide-events 1.2.1 → 1.4.0

package/dist/index.cjs

@@ -94,7 +94,8 @@ function createWideEventMixin(options) {
 		rate: options.sampling.rate,
 		perLevel: snapshotPerLevel,
 		emitLevel: options.sampling.emitLevel,
-		shouldEmit: options.sampling.shouldEmit
+		shouldEmit: options.sampling.shouldEmit,
+		forceKeep: options.sampling.forceKeep
 	} : void 0;
 	function defaultErrorSerializer(err) {
 		if (err instanceof Error) return {
@@ -189,23 +190,59 @@ function createWideEventMixin(options) {
 		return self;
 	}
 	/**
+	* Logs a thrown sampling callback via console.error, gated on `consoleDebug`.
+	* Matches loglayer's emit-path error convention (see LogLayer.ts:1457).
+	*/
+	function logCallbackError(callbackName, err, self) {
+		if (self.getConfig?.()?.consoleDebug) console.error(`[LogLayer] wide-events ${callbackName} callback threw; falling back:`, err);
+	}
+	/**
+	* Single sampling decision for an emit. Only called when a `forceKeep` or
+	* `shouldEmit` callback is configured (the no-callback case is handled by the
+	* pre-build fast-path in emitWideEventImpl).
+	*
+	* - `forceKeep` runs first (OR logic): true → keep; throws → fail-safe (log +
+	*   fall through); false → fall through.
+	* - Standard logic: rate AND `shouldEmit` (shouldEmit throws → fail-open, log
+	*   + keep). Without `shouldEmit`, rate alone decides.
+	*
+	* Invokes `runRateSampling` at most once.
+	*/
+	function evaluateSampling(wideData, level, self) {
+		if (samplingConfig?.forceKeep) try {
+			if (samplingConfig.forceKeep({
+				wideData,
+				level
+			})) return true;
+		} catch (err) {
+			logCallbackError("forceKeep", err, self);
+		}
+		if (samplingConfig?.shouldEmit) try {
+			const callbackOk = samplingConfig.shouldEmit({
+				wideData,
+				level
+			});
+			return runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel) && callbackOk;
+		} catch (err) {
+			logCallbackError("shouldEmit", err, self);
+			return true;
+		}
+		return runRateSampling(level, samplingConfig?.strategy, samplingConfig?.rate, samplingConfig?.perLevel);
+	}
+	/**
 	* Implementation for emitWideEvent
 	*/
 	function emitWideEventImpl(config, self) {
 		const defaultLevel = samplingConfig?.emitLevel ?? "info";
 		const level = config.level ?? defaultLevel;
-		if (samplingConfig && !samplingConfig.shouldEmit && !runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel)) return;
+		if (samplingConfig && !samplingConfig.shouldEmit && !samplingConfig.forceKeep && !runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel)) return;
 		const store = asyncContext.getStore();
 		const wideEventData = {};
 		if (includeContext && store?._llContext) Object.assign(wideEventData, store._llContext);
 		if (store?._llWideEvents) Object.assign(wideEventData, store._llWideEvents);
-		if (samplingConfig?.shouldEmit) try {
-			const callbackOk = samplingConfig.shouldEmit({
-				wideData: wideEventData,
-				level
-			});
-			if (!runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel) || !callbackOk) return;
-		} catch {}
+		if (samplingConfig && (samplingConfig.forceKeep || samplingConfig.shouldEmit)) {
+			if (!evaluateSampling(wideEventData, level, self)) return;
+		}
 		const metadataToEmit = wideEventField ? { [wideEventField]: wideEventData } : wideEventData;
 		self.raw({
 			logLevel: level,

package/dist/index.d.cts

@@ -107,6 +107,37 @@ interface WideEventSamplingConfig {
    * ```
    */
   shouldEmit?: (params: WideEventSamplingParams) => boolean;
+  /**
+   * A keep-only override evaluated **before** the rate/`shouldEmit` checks.
+   * When it returns `true`, the event is emitted immediately, bypassing the
+   * rate check and `shouldEmit`. When it returns `false`, standard
+   * rate/`shouldEmit` logic applies. Receives the same params as `shouldEmit`,
+   * so any external signal (e.g. an HTTP header) must first be written into the
+   * wide event via `withWideEvents()`.
+   *
+   * `forceKeep` can only rescue events — it never drops an event that standard
+   * logic would keep (`error`/`fatal` stay exempt).
+   *
+   * Treat `wideData` as read-only: it is passed by reference and mutating it
+   * changes what gets emitted.
+   *
+   * If it throws, it fails **safe**: the throw is swallowed and evaluation
+   * falls through to the standard rate/`shouldEmit` logic (unlike `shouldEmit`,
+   * which fails open). A swallowed throw is logged via `console.error` when
+   * `consoleDebug` is enabled.
+   *
+   * @example
+   * ```ts
+   * {
+   *   strategy: "per_level",
+   *   perLevel: { info: 0.01 },
+   *   forceKeep: ({ wideData }) =>
+   *     wideData?.debug === true ||
+   *     (wideData?.deps?.someService?.failures ?? 0) > 0,
+   * }
+   * ```
+   */
+  forceKeep?: (params: WideEventSamplingParams) => boolean;
   /**
    * Override the default log level when no explicit `level` is passed to
    * `emitWideEvent()`. When set, the resolved level uses this value instead

package/dist/index.d.mts

@@ -107,6 +107,37 @@ interface WideEventSamplingConfig {
    * ```
    */
   shouldEmit?: (params: WideEventSamplingParams) => boolean;
+  /**
+   * A keep-only override evaluated **before** the rate/`shouldEmit` checks.
+   * When it returns `true`, the event is emitted immediately, bypassing the
+   * rate check and `shouldEmit`. When it returns `false`, standard
+   * rate/`shouldEmit` logic applies. Receives the same params as `shouldEmit`,
+   * so any external signal (e.g. an HTTP header) must first be written into the
+   * wide event via `withWideEvents()`.
+   *
+   * `forceKeep` can only rescue events — it never drops an event that standard
+   * logic would keep (`error`/`fatal` stay exempt).
+   *
+   * Treat `wideData` as read-only: it is passed by reference and mutating it
+   * changes what gets emitted.
+   *
+   * If it throws, it fails **safe**: the throw is swallowed and evaluation
+   * falls through to the standard rate/`shouldEmit` logic (unlike `shouldEmit`,
+   * which fails open). A swallowed throw is logged via `console.error` when
+   * `consoleDebug` is enabled.
+   *
+   * @example
+   * ```ts
+   * {
+   *   strategy: "per_level",
+   *   perLevel: { info: 0.01 },
+   *   forceKeep: ({ wideData }) =>
+   *     wideData?.debug === true ||
+   *     (wideData?.deps?.someService?.failures ?? 0) > 0,
+   * }
+   * ```
+   */
+  forceKeep?: (params: WideEventSamplingParams) => boolean;
   /**
    * Override the default log level when no explicit `level` is passed to
    * `emitWideEvent()`. When set, the resolved level uses this value instead

package/dist/index.mjs

@@ -93,7 +93,8 @@ function createWideEventMixin(options) {
 		rate: options.sampling.rate,
 		perLevel: snapshotPerLevel,
 		emitLevel: options.sampling.emitLevel,
-		shouldEmit: options.sampling.shouldEmit
+		shouldEmit: options.sampling.shouldEmit,
+		forceKeep: options.sampling.forceKeep
 	} : void 0;
 	function defaultErrorSerializer(err) {
 		if (err instanceof Error) return {
@@ -188,23 +189,59 @@ function createWideEventMixin(options) {
 		return self;
 	}
 	/**
+	* Logs a thrown sampling callback via console.error, gated on `consoleDebug`.
+	* Matches loglayer's emit-path error convention (see LogLayer.ts:1457).
+	*/
+	function logCallbackError(callbackName, err, self) {
+		if (self.getConfig?.()?.consoleDebug) console.error(`[LogLayer] wide-events ${callbackName} callback threw; falling back:`, err);
+	}
+	/**
+	* Single sampling decision for an emit. Only called when a `forceKeep` or
+	* `shouldEmit` callback is configured (the no-callback case is handled by the
+	* pre-build fast-path in emitWideEventImpl).
+	*
+	* - `forceKeep` runs first (OR logic): true → keep; throws → fail-safe (log +
+	*   fall through); false → fall through.
+	* - Standard logic: rate AND `shouldEmit` (shouldEmit throws → fail-open, log
+	*   + keep). Without `shouldEmit`, rate alone decides.
+	*
+	* Invokes `runRateSampling` at most once.
+	*/
+	function evaluateSampling(wideData, level, self) {
+		if (samplingConfig?.forceKeep) try {
+			if (samplingConfig.forceKeep({
+				wideData,
+				level
+			})) return true;
+		} catch (err) {
+			logCallbackError("forceKeep", err, self);
+		}
+		if (samplingConfig?.shouldEmit) try {
+			const callbackOk = samplingConfig.shouldEmit({
+				wideData,
+				level
+			});
+			return runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel) && callbackOk;
+		} catch (err) {
+			logCallbackError("shouldEmit", err, self);
+			return true;
+		}
+		return runRateSampling(level, samplingConfig?.strategy, samplingConfig?.rate, samplingConfig?.perLevel);
+	}
+	/**
 	* Implementation for emitWideEvent
 	*/
 	function emitWideEventImpl(config, self) {
 		const defaultLevel = samplingConfig?.emitLevel ?? "info";
 		const level = config.level ?? defaultLevel;
-		if (samplingConfig && !samplingConfig.shouldEmit && !runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel)) return;
+		if (samplingConfig && !samplingConfig.shouldEmit && !samplingConfig.forceKeep && !runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel)) return;
 		const store = asyncContext.getStore();
 		const wideEventData = {};
 		if (includeContext && store?._llContext) Object.assign(wideEventData, store._llContext);
 		if (store?._llWideEvents) Object.assign(wideEventData, store._llWideEvents);
-		if (samplingConfig?.shouldEmit) try {
-			const callbackOk = samplingConfig.shouldEmit({
-				wideData: wideEventData,
-				level
-			});
-			if (!runRateSampling(level, samplingConfig.strategy, samplingConfig.rate, samplingConfig.perLevel) || !callbackOk) return;
-		} catch {}
+		if (samplingConfig && (samplingConfig.forceKeep || samplingConfig.shouldEmit)) {
+			if (!evaluateSampling(wideEventData, level, self)) return;
+		}
 		const metadataToEmit = wideEventField ? { [wideEventField]: wideEventData } : wideEventData;
 		self.raw({
 			logLevel: level,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loglayer/mixin-wide-events",
   "description": "Adds wide event logging functionality to LogLayer for comprehensive, self-contained log entries.",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -38,8 +38,8 @@
     "typescript": "6.0.3",
     "vitest": "4.1.7",
     "@internal/tsconfig": "2.1.0",
-    "@loglayer/shared": "4.3.0",
-    "loglayer": "9.3.0"
+    "@loglayer/shared": "4.4.0",
+    "loglayer": "9.4.0"
   },
   "peerDependencies": {
     "loglayer": ">=9.0.0"