sentry-vir 4.0.3 → 4.2.0

package/LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 electrovir
+Copyright (c) 2026 electrovir
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/event-context/event-context.d.ts

@@ -1,6 +1,7 @@
 import { type JsonCompatibleObject, type PartialWithUndefined } from '@augment-vir/common';
-import { type ScopeContext, type setTags } from '@sentry/core';
+import { type Attachment, type ScopeContext, type setTags } from '@sentry/core';
 import { type EventSeverityEnum } from './event-severity.js';
+export type { Attachment } from '@sentry/core';
 /**
  * Used for all extra context types. While keys must be strings, values can be whatever but must be
  * JSON compatible.
@@ -9,12 +10,13 @@ export type EventExtraContext = JsonCompatibleObject;
 /** Allowed tag value types for Sentry event tags. */
 export type EventTags = Parameters<typeof setTags>[0];
 /**
- * Combined context and tags parameter used for event logging functions. Both properties are
- * optional.
+ * Combined context, tags, and attachments parameter used for event logging functions. All
+ * properties are optional.
  */
 export type EventContextAndTags = PartialWithUndefined<{
     context: EventExtraContext;
     tags: EventTags;
+    attachments: ReadonlyArray<Attachment>;
 }>;
 /** Function that generates extra event context. */
 export type EventExtraContextCreator = () => EventExtraContext;
@@ -22,6 +24,7 @@ export type EventExtraContextCreator = () => EventExtraContext;
 export type EventDetails = {
     extraContext?: EventExtraContext | undefined;
     tags?: EventTags | undefined;
+    attachments?: ReadonlyArray<Attachment> | undefined;
     severity: EventSeverityEnum;
 };
 /** Options for creating contexts. Used internally. */

package/dist/event-context/extra-context.error.d.ts

@@ -1,5 +1,6 @@
+import { type Attachment } from '@sentry/core';
 import { type EventContextAndTags, type EventExtraContext, type EventTags } from './event-context.js';
-import { extraEventContextSymbol, extraEventTagsSymbol } from './extra-event-context.js';
+import { extraEventAttachmentsSymbol, extraEventContextSymbol, extraEventTagsSymbol } from './extra-event-context.js';
 /**
  * Constructs an error with extra event context attached to it in the same way that
  * throwWithExtraContext attaches data.
@@ -14,6 +15,7 @@ import { extraEventContextSymbol, extraEventTagsSymbol } from './extra-event-con
 export declare class ExtraContextError extends Error {
     readonly [extraEventContextSymbol]: EventExtraContext | undefined;
     readonly [extraEventTagsSymbol]: EventTags | undefined;
+    readonly [extraEventAttachmentsSymbol]: ReadonlyArray<Attachment> | undefined;
     constructor(message: string, extraData: EventContextAndTags);
 }
 /**

package/dist/event-context/extra-context.error.js

@@ -1,5 +1,5 @@
 import { ensureError } from '@augment-vir/common';
-import { extraEventContextSymbol, extraEventTagsSymbol, } from './extra-event-context.js';
+import { extraEventAttachmentsSymbol, extraEventContextSymbol, extraEventTagsSymbol, } from './extra-event-context.js';
 /**
  * Constructs an error with extra event context attached to it in the same way that
  * throwWithExtraContext attaches data.
@@ -14,6 +14,7 @@ import { extraEventContextSymbol, extraEventTagsSymbol, } from './extra-event-co
 export class ExtraContextError extends Error {
     [extraEventContextSymbol];
     [extraEventTagsSymbol];
+    [extraEventAttachmentsSymbol];
     constructor(message, extraData) {
         super(message);
         if (extraData.context) {
@@ -22,6 +23,9 @@ export class ExtraContextError extends Error {
         if (extraData.tags) {
             this[extraEventTagsSymbol] = extraData.tags;
         }
+        if (extraData.attachments) {
+            this[extraEventAttachmentsSymbol] = extraData.attachments;
+        }
     }
 }
 /**
@@ -36,5 +40,8 @@ export function throwWithExtraContext(originalError, extraData) {
     if (extraData.tags) {
         error[extraEventTagsSymbol] = extraData.tags;
     }
+    if (extraData.attachments) {
+        error[extraEventAttachmentsSymbol] = extraData.attachments;
+    }
     throw error;
 }

package/dist/event-context/extra-event-context.d.ts

@@ -1,4 +1,4 @@
-import { type Event, type EventHint } from '@sentry/core';
+import { type Attachment, type Event, type EventHint } from '@sentry/core';
 import { type EventExtraContext, type EventTags } from './event-context.js';
 /**
  * Symbol used to attach extra event context to events. This is particularly useful for errors so
@@ -10,6 +10,11 @@ export declare const extraEventContextSymbol: unique symbol;
  * attaching tag data to thrown errors.
  */
 export declare const extraEventTagsSymbol: unique symbol;
+/**
+ * Symbol used to attach extra event attachments to events. Used alongside extraEventContextSymbol
+ * for attaching file data to thrown errors.
+ */
+export declare const extraEventAttachmentsSymbol: unique symbol;
 /** Simply describes an object that has extra event context. */
 export type HasExtraContext = {
     [extraEventContextSymbol]: EventExtraContext;
@@ -18,10 +23,16 @@ export type HasExtraContext = {
 export type HasExtraTags = {
     [extraEventTagsSymbol]: EventTags;
 };
+/** Simply describes an object that has extra event attachments. */
+export type HasExtraAttachments = {
+    [extraEventAttachmentsSymbol]: ReadonlyArray<Attachment>;
+};
 /** Type guard for whether any given input has extra event context. */
 export declare function hasExtraEventContext(input: unknown): input is HasExtraContext;
 /** Type guard for whether any given input has extra event tags. */
 export declare function hasExtraEventTags(input: unknown): input is HasExtraTags;
+/** Type guard for whether any given input has extra event attachments. */
+export declare function hasExtraEventAttachments(input: unknown): input is HasExtraAttachments;
 /**
  * Checks if extra event context has been injected into the input via extraEventContextSymbol and,
  * if so, extracts it.
@@ -32,6 +43,11 @@ export declare function extractExtraContentFromSymbol(input: unknown): EventExtr
  * extracts them.
  */
 export declare function extractExtraTagsFromSymbol(input: unknown): EventTags | undefined;
+/**
+ * Checks if extra event attachments have been injected into the input via
+ * extraEventAttachmentsSymbol and, if so, extracts them.
+ */
+export declare function extractExtraAttachmentsFromSymbol(input: unknown): ReadonlyArray<Attachment> | undefined;
 /**
  * Tries to extract extra event context via extraEventContextSymbol. Returns undefined if there is
  * no extra event context.
@@ -42,3 +58,8 @@ export declare function extractExtraEventContext(event: EventHint | Event): Even
  * extra event tags.
  */
 export declare function extractExtraEventTags(event: EventHint | Event): EventTags | undefined;
+/**
+ * Tries to extract extra event attachments via extraEventAttachmentsSymbol. Returns undefined if
+ * there are no extra event attachments.
+ */
+export declare function extractExtraEventAttachments(event: EventHint | Event): ReadonlyArray<Attachment> | undefined;

package/dist/event-context/extra-event-context.js

@@ -9,6 +9,11 @@ export const extraEventContextSymbol = Symbol('extra-event-context');
  * attaching tag data to thrown errors.
  */
 export const extraEventTagsSymbol = Symbol('extra-event-tags');
+/**
+ * Symbol used to attach extra event attachments to events. Used alongside extraEventContextSymbol
+ * for attaching file data to thrown errors.
+ */
+export const extraEventAttachmentsSymbol = Symbol('extra-event-attachments');
 /** Type guard for whether any given input has extra event context. */
 export function hasExtraEventContext(input) {
     return check.hasKey(input, extraEventContextSymbol) && !!input[extraEventContextSymbol];
@@ -17,6 +22,10 @@ export function hasExtraEventContext(input) {
 export function hasExtraEventTags(input) {
     return check.hasKey(input, extraEventTagsSymbol) && !!input[extraEventTagsSymbol];
 }
+/** Type guard for whether any given input has extra event attachments. */
+export function hasExtraEventAttachments(input) {
+    return check.hasKey(input, extraEventAttachmentsSymbol) && !!input[extraEventAttachmentsSymbol];
+}
 /**
  * Checks if extra event context has been injected into the input via extraEventContextSymbol and,
  * if so, extracts it.
@@ -39,6 +48,16 @@ export function extractExtraTagsFromSymbol(input) {
     }
     return undefined;
 }
+/**
+ * Checks if extra event attachments have been injected into the input via
+ * extraEventAttachmentsSymbol and, if so, extracts them.
+ */
+export function extractExtraAttachmentsFromSymbol(input) {
+    if (hasExtraEventAttachments(input)) {
+        return input[extraEventAttachmentsSymbol];
+    }
+    return undefined;
+}
 /**
  * Tries to extract extra event context via extraEventContextSymbol. Returns undefined if there is
  * no extra event context.
@@ -83,3 +102,23 @@ export function extractExtraEventTags(event) {
         return undefined;
     }
 }
+/**
+ * Tries to extract extra event attachments via extraEventAttachmentsSymbol. Returns undefined if
+ * there are no extra event attachments.
+ */
+export function extractExtraEventAttachments(event) {
+    const fromRootSymbol = extractExtraAttachmentsFromSymbol(event);
+    const fromSubSymbol = 'originalException' in event
+        ? extractExtraAttachmentsFromSymbol(event.originalException)
+        : undefined;
+    const combined = [
+        ...(fromRootSymbol || []),
+        ...(fromSubSymbol || []),
+    ];
+    if (combined.length) {
+        return combined;
+    }
+    else {
+        return undefined;
+    }
+}

package/dist/logging/handle-error.js

@@ -1,6 +1,7 @@
 import { extractErrorMessage } from '@augment-vir/common';
 import { convertEventDetailsToSentryContext, } from '../event-context/event-context.js';
 import { EventSeverityEnum } from '../event-context/event-severity.js';
+import { extractExtraAttachmentsFromSymbol } from '../event-context/extra-event-context.js';
 import { LoggingState, logToConsoleWithoutSentry } from '../processing/log-to-console.js';
 import { addPrematureEvent } from './premature-events.js';
 import { sentryClientForLogging } from './sentry-client-for-logging.js';
@@ -34,7 +35,19 @@ function internalHandleError(error, eventOptions, options) {
             tags: eventOptions?.tags,
             severity: EventSeverityEnum.Error,
         }, options);
-        const eventId = sentryClientForLogging.captureException(error, scopeContext);
+        const client = sentryClientForLogging;
+        const allAttachments = [
+            ...(eventOptions?.attachments || []),
+            ...(extractExtraAttachmentsFromSymbol(error) || []),
+        ];
+        const eventId = allAttachments.length
+            ? client.withScope((scope) => {
+                allAttachments.forEach((attachment) => {
+                    scope.addAttachment(attachment);
+                });
+                return client.captureException(error, scopeContext);
+            })
+            : client.captureException(error, scopeContext);
         return eventId;
     }
     catch (caught) {

package/dist/logging/send-log.js

@@ -20,6 +20,7 @@ function wrapLogWithSeverity(severity) {
         return sendLogToSentry(info, {
             extraContext: eventOptions?.context,
             tags: eventOptions?.tags,
+            attachments: eventOptions?.attachments,
             severity,
         }, {
             wasSentPrematurely: false,
@@ -54,12 +55,23 @@ function sendLogToSentry(logInfo, eventDetails, options) {
             return undefined;
         }
         const scopeContext = convertEventDetailsToSentryContext(eventDetails, options);
-        const eventId = check.isString(resolvedLogInfo)
-            ? sentryClientForLogging.captureMessage(resolvedLogInfo, scopeContext)
-            : sentryClientForLogging.captureEvent({
-                ...resolvedLogInfo,
-                ...scopeContext,
-            });
+        const client = sentryClientForLogging;
+        function captureWithClient() {
+            return check.isString(resolvedLogInfo)
+                ? client.captureMessage(resolvedLogInfo, scopeContext)
+                : client.captureEvent({
+                    ...resolvedLogInfo,
+                    ...scopeContext,
+                });
+        }
+        const eventId = eventDetails.attachments?.length
+            ? client.withScope((scope) => {
+                eventDetails.attachments?.forEach((attachment) => {
+                    scope.addAttachment(attachment);
+                });
+                return captureWithClient();
+            })
+            : captureWithClient();
         return eventId;
     }
     catch (caught) {

package/dist/logging/sentry-client-for-logging.d.ts

@@ -1,7 +1,7 @@
 import { type MaybePromise } from '@augment-vir/common';
 import { type SentryDep } from '../env/execution-env.js';
 /** The bare minimum Sentry client needed for logging events. */
-export type SentryClientForLogging = Pick<SentryDep, 'captureMessage' | 'captureException' | 'captureEvent' | 'setTags'>;
+export type SentryClientForLogging = Pick<SentryDep, 'captureMessage' | 'captureException' | 'captureEvent' | 'setTags' | 'withScope'>;
 /** Internal sentry client used for logging. */
 export declare let sentryClientForLogging: SentryClientForLogging | undefined;
 /**

package/dist/processing/throttling.d.ts

@@ -1,6 +1,7 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
 import { type ErrorEvent, type EventHint, type TransactionEvent } from '@sentry/core';
 import { type AnyDuration, type FullDate, type UtcTimezone } from 'date-vir';
+import { FuzzyIndex, type FuzzyIndexKey } from 'fuzzy-vir';
 /**
  * Type for entries in {@link throttleCache}.
  *
@@ -9,14 +10,21 @@ import { type AnyDuration, type FullDate, type UtcTimezone } from 'date-vir';
 export type ThrottleCacheEntry = {
     intervalCount: number;
     intervalStartAt: FullDate<UtcTimezone>;
-    throttleStartedAt: FullDate<UtcTimezone> | undefined;
 };
 /**
- * The current throttle cache.
+ * The current throttle cache, keyed by a fuzzy cluster key so near-duplicate error messages share a
+ * throttle bucket.
  *
  * @category Internal
  */
-export declare const throttleCache: Map<string, ThrottleCacheEntry>;
+export declare const throttleCache: Map<FuzzyIndexKey, ThrottleCacheEntry>;
+/**
+ * Fuzzy index used to group near-duplicate error messages together so they share a single throttle
+ * bucket. The `onEvict` hook keeps {@link throttleCache} in sync when a cluster is dropped.
+ *
+ * @category Internal
+ */
+export declare const fuzzyErrorIndex: FuzzyIndex;
 /**
  * Throttling options.
  *
@@ -24,19 +32,14 @@ export declare const throttleCache: Map<string, ThrottleCacheEntry>;
  */
 export type ThrottleOptions = {
     disableThrottling: boolean;
-    /**
-     * When throttling begins, this determines how much time must pass before the error will be
-     * logged again.
-     */
+    /** Duration over which up to `throttleThreshold` events of the same message are allowed. */
     thresholdInterval: AnyDuration;
+    /** Disable the sentry log that fires the first time an error is throttled in an interval. */
+    disableThrottleLog: boolean;
     /**
-     * In order for throttling to turn off, the throttle threshold must have not been hit for this
-     * entire duration.
+     * Within `thresholdInterval`, if an error message is logged more than this many times,
+     * additional events are dropped until the interval rolls over.
      */
-    throttleCooldown: AnyDuration;
-    /** Enable a sentry log that indicates that an error is being throttled. */
-    disableThrottleLog: boolean;
-    /** If an error is logged this many times within `logInterval`, it starts getting throttled. */
     throttleThreshold: number;
 };
 /**

package/dist/processing/throttling.js

@@ -1,13 +1,26 @@
 import { getOrSetFromMap, mergeDefinedProperties, } from '@augment-vir/common';
 import { calculateRelativeDate, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
+import { FuzzyIndex } from 'fuzzy-vir';
 import { sendLog } from '../logging/send-log.js';
 import { extractOriginalMessage } from './event-processor.js';
 /**
- * The current throttle cache.
+ * The current throttle cache, keyed by a fuzzy cluster key so near-duplicate error messages share a
+ * throttle bucket.
  *
  * @category Internal
  */
 export const throttleCache = new Map();
+/**
+ * Fuzzy index used to group near-duplicate error messages together so they share a single throttle
+ * bucket. The `onEvict` hook keeps {@link throttleCache} in sync when a cluster is dropped.
+ *
+ * @category Internal
+ */
+export const fuzzyErrorIndex = new FuzzyIndex({
+    onEvict(clusterKey) {
+        throttleCache.delete(clusterKey);
+    },
+});
 /**
  * Default values for {@link ThrottleOptions}.
  *
@@ -19,10 +32,7 @@ export const defaultThrottleOptions = {
         hours: 1,
     },
     disableThrottleLog: false,
-    throttleCooldown: {
-        days: 1,
-    },
-    throttleThreshold: 50,
+    throttleThreshold: 500,
 };
 /**
  * Determines if an event should be throttled based on previous event counts.
@@ -38,49 +48,47 @@ hint, userOptions = defaultThrottleOptions) {
     if (options.disableThrottling) {
         return false;
     }
-    const errorKey = extractOriginalMessage(event, hint);
+    const errorKey = fuzzyErrorIndex.insert(extractOriginalMessage(event, hint));
     const now = getNowInUtcTimezone();
     const errorThrottleData = getOrSetFromMap(throttleCache, errorKey, () => {
         return {
             intervalCount: 0,
             intervalStartAt: now,
-            throttleStartedAt: undefined,
         };
     });
-    errorThrottleData.intervalCount++;
-    const thresholdSurpassed = errorThrottleData.intervalCount > options.throttleThreshold;
-    if (thresholdSurpassed && !errorThrottleData.throttleStartedAt) {
-        errorThrottleData.throttleStartedAt = now;
-        if (options.disableThrottleLog) {
-            sendLog.warning(`Error throttled: ${errorKey}`);
-        }
-    }
     const intervalNeedsRestart = isDateAfter({
         fullDate: now,
         relativeTo: calculateRelativeDate(errorThrottleData.intervalStartAt, options.thresholdInterval),
     });
     if (intervalNeedsRestart) {
-        errorThrottleData.intervalStartAt = now;
-        if (thresholdSurpassed) {
-            /**
-             * If an interval surpassed the threshold, always bump the threshold started at up so
-             * the cooldown requires all intervals to be below the threshold.
-             */
-            errorThrottleData.throttleStartedAt = now;
-            if (options.disableThrottleLog) {
-                sendLog.warning(`Error throttled: ${errorKey}`);
-            }
+        const suppressedCount = errorThrottleData.intervalCount - options.throttleThreshold;
+        if (suppressedCount > 0 && !options.disableThrottleLog) {
+            sendLog.warning(`Throttling ended after suppressing ${suppressedCount} events: ${errorKey}`, {
+                context: {
+                    suppressedErrorKey: errorKey,
+                    suppressedCount,
+                },
+                tags: {
+                    suppressedErrorKey: errorKey,
+                },
+            });
         }
+        errorThrottleData.intervalStartAt = now;
         errorThrottleData.intervalCount = 0;
     }
-    if (errorThrottleData.throttleStartedAt) {
-        const shouldStopThrottle = isDateAfter({
-            fullDate: now,
-            relativeTo: calculateRelativeDate(errorThrottleData.throttleStartedAt, options.throttleCooldown),
+    errorThrottleData.intervalCount++;
+    const shouldThrottle = errorThrottleData.intervalCount > options.throttleThreshold;
+    if (shouldThrottle &&
+        errorThrottleData.intervalCount === options.throttleThreshold + 1 &&
+        !options.disableThrottleLog) {
+        sendLog.warning(`Throttling started: ${errorKey}`, {
+            context: {
+                suppressedErrorKey: errorKey,
+            },
+            tags: {
+                suppressedErrorKey: errorKey,
+            },
         });
-        if (shouldStopThrottle && !thresholdSurpassed) {
-            errorThrottleData.throttleStartedAt = undefined;
-        }
     }
-    return !!errorThrottleData.throttleStartedAt;
+    return shouldThrottle;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sentry-vir",
-    "version": "4.0.3",
+    "version": "4.2.0",
     "description": "Easily use Sentry.",
     "keywords": [
         "config",
@@ -44,55 +44,56 @@
         "test:update": "npm test update"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.68.1",
-        "@augment-vir/common": "^31.68.1",
-        "@sentry/browser": "^10.42.0",
-        "@sentry/core": "^10.42.0",
-        "@sentry/node": "^10.42.0",
-        "date-vir": "^8.2.0",
-        "type-fest": "^5.4.4"
+        "@augment-vir/assert": "^31.70.0",
+        "@augment-vir/common": "^31.70.0",
+        "@sentry/browser": "^10.53.1",
+        "@sentry/core": "^10.53.1",
+        "@sentry/node": "^10.53.1",
+        "date-vir": "^8.3.2",
+        "fuzzy-vir": "^0.0.2",
+        "type-fest": "^5.6.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.68.1",
-        "@eslint/eslintrc": "^3.3.4",
+        "@augment-vir/test": "^31.70.0",
+        "@eslint/eslintrc": "^3.3.5",
         "@eslint/js": "^9.39.2",
         "@stylistic/eslint-plugin": "^5.10.0",
         "@stylistic/eslint-plugin-ts": "^4.4.1",
-        "@typescript-eslint/eslint-plugin": "^8.56.1",
+        "@typescript-eslint/eslint-plugin": "^8.59.4",
         "@web/dev-server-esbuild": "^1.0.5",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.1",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "cspell": "^9.7.0",
-        "dependency-cruiser": "^17.3.8",
-        "esbuild": "^0.27.3",
+        "cspell": "^10.0.0",
+        "dependency-cruiser": "^17.4.0",
+        "esbuild": "^0.28.0",
         "eslint": "^9.39.2",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-jsdoc": "^62.7.1",
+        "eslint-plugin-jsdoc": "^63.0.0",
         "eslint-plugin-monorepo-cop": "^1.0.2",
-        "eslint-plugin-playwright": "^2.9.0",
+        "eslint-plugin-playwright": "^2.10.4",
         "eslint-plugin-prettier": "^5.5.5",
         "eslint-plugin-require-extensions": "^0.1.3",
-        "eslint-plugin-sonarjs": "^4.0.1",
-        "eslint-plugin-unicorn": "^63.0.0",
+        "eslint-plugin-sonarjs": "^4.0.3",
+        "eslint-plugin-unicorn": "^64.0.0",
         "istanbul-smart-text-reporter": "^1.1.5",
-        "markdown-code-example-inserter": "^3.0.3",
-        "npm-check-updates": "^19.6.3",
+        "markdown-code-example-inserter": "^3.0.5",
+        "npm-check-updates": "^22.2.0",
         "prettier": "~3.3.3",
         "prettier-plugin-interpolated-html-tags": "^2.0.1",
         "prettier-plugin-jsdoc": "^1.8.0",
-        "prettier-plugin-multiline-arrays": "^4.1.4",
+        "prettier-plugin-multiline-arrays": "^4.1.8",
         "prettier-plugin-organize-imports": "^4.3.0",
         "prettier-plugin-packagejson": "^3.0.2",
         "prettier-plugin-sort-json": "^4.2.0",
         "prettier-plugin-toml": "^2.0.6",
         "runstorm": "^1.0.0",
-        "typedoc": "^0.28.17",
+        "typedoc": "^0.28.19",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.56.1",
-        "virmator": "^14.8.3",
-        "vite": "^7.3.1"
+        "typescript-eslint": "^8.57.1",
+        "virmator": "^14.16.0",
+        "vite": "^8.0.13"
     },
     "engines": {
         "node": ">=22"