sentry-vir 3.1.0 → 3.2.0

package/dist/augments/replace-object.d.ts

@@ -0,0 +1,2 @@
+import { type AnyObject } from '@augment-vir/common';
+export declare function replaceObject<T extends AnyObject>(original: T, replacement: T): void;

package/dist/augments/replace-object.js

@@ -0,0 +1,6 @@
+export function replaceObject(original, replacement) {
+    Object.keys(original).forEach((key) => delete original[key]);
+    Object.entries(replacement).forEach(([key, value,]) => {
+        original[key] = value;
+    });
+}

package/dist/auto.d.ts

@@ -12,4 +12,4 @@ export declare const sentryDepByEnv: Record<SentryExecutionEnvEnum, SentryDepImp
  *
  * To override any default sentry-vir settings, include them in the userConfig input.
  */
-export declare function autoInitSentry({ executionEnv, dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, }: InitSentryInput): Promise<SentryDep>;
+export declare function autoInitSentry({ executionEnv, dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, silent, throttleOptions, }: InitSentryInput): Promise<SentryDep>;

package/dist/auto.js

@@ -19,7 +19,7 @@ async function getSentryByEnv(executionEnv) {
  *
  * To override any default sentry-vir settings, include them in the userConfig input.
  */
-export async function autoInitSentry({ executionEnv, dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, }) {
+export async function autoInitSentry({ executionEnv, dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, silent, throttleOptions, }) {
     const sentryDep = await getSentryByEnv(executionEnv);
     await baseInitSentry({
         dsn,
@@ -30,6 +30,8 @@ export async function autoInitSentry({ executionEnv, dsn, releaseEnv, releaseNam
         sentryDep,
         executionEnv,
         isDev,
+        silent,
+        throttleOptions,
     });
     return sentryDep;
 }

package/dist/browser.d.ts

@@ -7,4 +7,4 @@ export type Sentry = SentryBrowserDep;
  *
  * To override any default sentry-vir settings, include them in the userConfig input.
  */
-export declare function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, }: Omit<InitSentryInput, 'executionEnv'>): Promise<Sentry>;
+export declare function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, silent, throttleOptions, }: Omit<InitSentryInput, 'executionEnv'>): Promise<Sentry>;

package/dist/browser.js

@@ -6,7 +6,7 @@ import { baseInitSentry } from './init-sentry/base-sentry-init.js';
  *
  * To override any default sentry-vir settings, include them in the userConfig input.
  */
-export async function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, }) {
+export async function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, silent, throttleOptions, }) {
     const sentryDep = await import('@sentry/browser');
     await baseInitSentry({
         dsn,
@@ -17,6 +17,8 @@ export async function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOve
         sentryDep,
         executionEnv: SentryExecutionEnvEnum.Browser,
         isDev,
+        silent,
+        throttleOptions,
     });
     return sentryDep;
 }

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export * from './logging/send-log.js';
 export * from './logging/sentry-client-for-logging.js';
 export * from './processing/event-processor.js';
 export * from './processing/handle-sentry-send.js';
+export * from './processing/throttling.js';

package/dist/index.js

@@ -11,3 +11,4 @@ export * from './logging/send-log.js';
 export * from './logging/sentry-client-for-logging.js';
 export * from './processing/event-processor.js';
 export * from './processing/handle-sentry-send.js';
+export * from './processing/throttling.js';

package/dist/init-sentry/base-sentry-init.d.ts

@@ -1,6 +1,8 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
 import { type Options } from '@sentry/core';
 import { type SentryDep, type SentryExecutionEnvEnum } from '../env/execution-env.js';
 import { type EventExtraContextCreator } from '../event-context/event-context.js';
+import { type ThrottleOptions } from '../processing/throttling.js';
 import { type UserOverrides } from './sentry-config.js';
 /** Configuration for initializing Sentry. */
 export type InitSentryInput = {
@@ -33,6 +35,7 @@ export type InitSentryInput = {
     createUniversalContext?: EventExtraContextCreator | undefined;
     /** Optionally override any Sentry config properties that this package sets. */
     sentryConfigOverrides?: UserOverrides;
+    throttleOptions: Readonly<PartialWithUndefined<ThrottleOptions>> | undefined;
 };
 /**
  * Base Sentry init. Requires the Sentry module to already have been imported. Setup a sentry client
@@ -40,6 +43,6 @@ export type InitSentryInput = {
  *
  * To override any default sentry-vir settings, include them in the userConfig input.
  */
-export declare function baseInitSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, sentryDep, executionEnv, isDev, silent, }: InitSentryInput & {
+export declare function baseInitSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, sentryDep, executionEnv, isDev, silent, throttleOptions, }: InitSentryInput & {
     sentryDep: SentryDep;
 }): Promise<SentryDep>;

package/dist/init-sentry/base-sentry-init.js

@@ -7,14 +7,21 @@ import { createSentryConfig } from './sentry-config.js';
  *
  * To override any default sentry-vir settings, include them in the userConfig input.
  */
-export async function baseInitSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, sentryDep, executionEnv, isDev, silent, }) {
-    const finalSentryConfig = await createSentryConfig(executionEnv, sentryDep, {
-        dsn,
-        environment: releaseEnv,
-        release: releaseName,
-    }, sentryConfigOverrides, {
-        isDev,
-        isSilent: !!silent,
+export async function baseInitSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, sentryDep, executionEnv, isDev, silent, throttleOptions, }) {
+    const finalSentryConfig = await createSentryConfig({
+        executionEnv,
+        sentryDep,
+        requiredSentryOptions: {
+            dsn,
+            environment: releaseEnv,
+            release: releaseName,
+        },
+        userOverrides: sentryConfigOverrides,
+        flagParams: {
+            isDev,
+            isSilent: !!silent,
+            throttleOptions,
+        },
     });
     sentryDep.init(finalSentryConfig);
     sentryDep.addEventProcessor((event, hint) => processSentryEvent(event, hint, createUniversalContext));

package/dist/init-sentry/sentry-config.d.ts

@@ -1,13 +1,22 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
 import { type BrowserOptions } from '@sentry/browser';
 import { type Options } from '@sentry/core';
 import { type NodeOptions } from '@sentry/node';
 import { type SentryDepByEnv, SentryExecutionEnvEnum } from '../env/execution-env.js';
+import { type ThrottleOptions } from '../processing/throttling.js';
 /** Optional UserOverrides of Sentry config values. */
 export type UserOverrides = Omit<Partial<Options>, keyof RequiredSentryOptions> | undefined;
 /** Sentry config options that are required. */
 export type RequiredSentryOptions = Pick<Required<Options>, 'dsn' | 'environment' | 'release'>;
 /** Creates the sentry config used internally by sentry-vir. */
-export declare function createSentryConfig<const ExecutionEnv extends SentryExecutionEnvEnum>(executionEnv: ExecutionEnv, sentryDep: SentryDepByEnv<ExecutionEnv>, requiredSentryOptions: RequiredSentryOptions, userOverrides: UserOverrides, flagParams: {
-    isDev: boolean;
-    isSilent: boolean;
+export declare function createSentryConfig<const ExecutionEnv extends SentryExecutionEnvEnum>({ executionEnv, sentryDep, requiredSentryOptions, userOverrides, flagParams, }: {
+    executionEnv: ExecutionEnv;
+    sentryDep: SentryDepByEnv<ExecutionEnv>;
+    requiredSentryOptions: RequiredSentryOptions;
+    userOverrides: UserOverrides;
+    flagParams: {
+        isDev: boolean;
+        isSilent: boolean;
+        throttleOptions: Readonly<PartialWithUndefined<ThrottleOptions>> | undefined;
+    };
 }): Promise<BrowserOptions | NodeOptions>;

package/dist/init-sentry/sentry-config.js

@@ -2,7 +2,7 @@ import { mergeDeep } from '@augment-vir/common';
 import { SentryExecutionEnvEnum, } from '../env/execution-env.js';
 import { createSentryHandler } from '../processing/handle-sentry-send.js';
 /** Creates the sentry config used internally by sentry-vir. */
-export function createSentryConfig(executionEnv, sentryDep, requiredSentryOptions, userOverrides, flagParams) {
+export function createSentryConfig({ executionEnv, sentryDep, requiredSentryOptions, userOverrides, flagParams, }) {
     const sharedSentryConfig = {
         beforeSend: createSentryHandler(flagParams),
         beforeSendTransaction: createSentryHandler(flagParams),

package/dist/node.d.ts

@@ -7,4 +7,4 @@ export type Sentry = SentryNodeDep;
  *
  * To override any default sentry-vir settings, include them in the userConfig input.
  */
-export declare function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, }: Omit<InitSentryInput, 'executionEnv'>): Promise<SentryNodeDep>;
+export declare function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, silent, throttleOptions, }: Omit<InitSentryInput, 'executionEnv'>): Promise<SentryNodeDep>;

package/dist/node.js

@@ -6,7 +6,7 @@ import { baseInitSentry } from './init-sentry/base-sentry-init.js';
  *
  * To override any default sentry-vir settings, include them in the userConfig input.
  */
-export async function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, }) {
+export async function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOverrides, createUniversalContext, isDev, silent, throttleOptions, }) {
     const sentryDep = await import('@sentry/node');
     await baseInitSentry({
         dsn,
@@ -17,6 +17,8 @@ export async function initSentry({ dsn, releaseEnv, releaseName, sentryConfigOve
         sentryDep,
         executionEnv: SentryExecutionEnvEnum.Node,
         isDev,
+        silent,
+        throttleOptions,
     });
     return sentryDep;
 }

package/dist/processing/event-processor.d.ts

@@ -13,4 +13,4 @@ export declare function extractOriginalMessage(
 /** Event from Sentry. */
 event: Pick<TransactionEvent | ErrorEvent, 'message'>, 
 /** EventHint generated by Sentry. */
-hint: EventHint | undefined): string;
+hint: Readonly<Pick<EventHint, 'originalException'>> | undefined): string;

package/dist/processing/handle-sentry-send.d.ts

@@ -1,9 +1,12 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
 import { type EventHint } from '@sentry/browser';
 import { type ErrorEvent, type TransactionEvent } from '@sentry/core';
+import { type ThrottleOptions } from './throttling.js';
 /** Creates a handler for Sentry events based on the given env. */
-export declare function createSentryHandler<T extends TransactionEvent | ErrorEvent>({ isDev, isSilent, }: {
+export declare function createSentryHandler<T extends TransactionEvent | ErrorEvent>({ isDev, isSilent, throttleOptions, }: {
     /** If in dev, events won't be sent to Sentry. They will only be logged in the console. */
     isDev: boolean;
     /** If silent, events won't even get logged to the console. */
     isSilent: boolean;
+    throttleOptions: Readonly<PartialWithUndefined<ThrottleOptions>> | undefined;
 }): (event: T, hint: EventHint) => T | null;

package/dist/processing/handle-sentry-send.js

@@ -1,12 +1,16 @@
 import { LoggingState, logToConsoleFromSentry } from './log-to-console.js';
+import { shouldThrottleEvent } from './throttling.js';
 /** Creates a handler for Sentry events based on the given env. */
-export function createSentryHandler({ isDev, isSilent, }) {
+export function createSentryHandler({ isDev, isSilent, throttleOptions, }) {
     /** The actual function that gets called when handling Sentry events. */
     function handleSentrySend(
     /** The event from Sentry. */
     event, 
     /** The EventHint generated by Sentry. */
     hint) {
+        if (shouldThrottleEvent(event, hint, throttleOptions)) {
+            return null;
+        }
         if (!event.extra?.wasSentPrematurely) {
             logToConsoleFromSentry(event, hint, isDev ? LoggingState.Dev : LoggingState.Prod, isSilent);
         }

package/dist/processing/throttling.d.ts

@@ -0,0 +1,57 @@
+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';
+/**
+ * Type for entries in {@link throttleCache}.
+ *
+ * @category Internal
+ */
+export type ThrottleCacheEntry = {
+    intervalCount: number;
+    intervalStartAt: FullDate<UtcTimezone>;
+    throttleStartedAt: FullDate<UtcTimezone> | undefined;
+};
+/**
+ * The current throttle cache.
+ *
+ * @category Internal
+ */
+export declare const throttleCache: Record<string, ThrottleCacheEntry>;
+/**
+ * Throttling options.
+ *
+ * @category Internal
+ */
+export type ThrottleOptions = {
+    disableThrottling: boolean;
+    /**
+     * When throttling begins, this determines how much time must pass before the error will be
+     * logged again.
+     */
+    thresholdInterval: AnyDuration;
+    /**
+     * In order for throttling to turn off, the throttle threshold must have not been hit for this
+     * entire duration.
+     */
+    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;
+};
+/**
+ * Default values for {@link ThrottleOptions}.
+ *
+ * @category Internal
+ */
+export declare const defaultThrottleOptions: ThrottleOptions;
+/**
+ * Determines if an event should be throttled based on previous event counts.
+ *
+ * @category Internal
+ */
+export declare function shouldThrottleEvent(
+/** Event from Sentry. */
+event: Pick<TransactionEvent | ErrorEvent, 'message'>, 
+/** EventHint generated by Sentry. */
+hint?: Readonly<Pick<EventHint, 'originalException'>> | undefined, userOptions?: Readonly<PartialWithUndefined<ThrottleOptions>>): boolean;

package/dist/processing/throttling.js

@@ -0,0 +1,82 @@
+import { getOrSet, mergeDefinedProperties } from '@augment-vir/common';
+import { calculateRelativeDate, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
+import { sendLog } from '../logging/send-log.js';
+import { extractOriginalMessage } from './event-processor.js';
+/**
+ * The current throttle cache.
+ *
+ * @category Internal
+ */
+export const throttleCache = {};
+/**
+ * Default values for {@link ThrottleOptions}.
+ *
+ * @category Internal
+ */
+export const defaultThrottleOptions = {
+    disableThrottling: false,
+    thresholdInterval: { hours: 1 },
+    disableThrottleLog: false,
+    throttleCooldown: { days: 1 },
+    throttleThreshold: 50,
+};
+/**
+ * Determines if an event should be throttled based on previous event counts.
+ *
+ * @category Internal
+ */
+export function shouldThrottleEvent(
+/** Event from Sentry. */
+event, 
+/** EventHint generated by Sentry. */
+hint = undefined, userOptions = defaultThrottleOptions) {
+    const options = mergeDefinedProperties(defaultThrottleOptions, userOptions);
+    if (options.disableThrottling) {
+        return false;
+    }
+    const errorKey = extractOriginalMessage(event, hint);
+    const now = getNowInUtcTimezone();
+    const errorThrottleData = getOrSet(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}`);
+            }
+        }
+        errorThrottleData.intervalCount = 0;
+    }
+    if (errorThrottleData.throttleStartedAt) {
+        const shouldStopThrottle = isDateAfter({
+            fullDate: now,
+            relativeTo: calculateRelativeDate(errorThrottleData.throttleStartedAt, options.throttleCooldown),
+        });
+        if (shouldStopThrottle && !thresholdSurpassed) {
+            errorThrottleData.throttleStartedAt = undefined;
+        }
+    }
+    return !!errorThrottleData.throttleStartedAt;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sentry-vir",
-    "version": "3.1.0",
+    "version": "3.2.0",
     "description": "Easily use Sentry.",
     "keywords": [
         "config",
@@ -35,7 +35,7 @@
         "publish": "virmator publish npm run test:all",
         "start": "virmator frontend",
         "test": "virmator test web",
-        "test:all": "npm run compile && concurrently --colors --kill-others-on-fail -c auto --names tests,spelling,format,docs,deps,lint \"npm run test\" \"npm run test:spelling\" \"npm run test:format\" \"npm run test:docs\" \"npm run test:deps\" \"npm run test:lint\"",
+        "test:all": "npm run compile && runstorm --names tests,spelling,format,docs,deps,lint \"npm run test\" \"npm run test:spelling\" \"npm run test:format\" \"npm run test:docs\" \"npm run test:deps\" \"npm run test:lint\"",
         "test:deps": "virmator deps check",
         "test:docs": "virmator docs check",
         "test:format": "virmator format check",
@@ -44,53 +44,55 @@
         "test:update": "npm test update"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.32.2",
-        "@augment-vir/common": "^31.32.2",
-        "@sentry/browser": "^10.5.0",
-        "@sentry/core": "^10.5.0",
-        "@sentry/node": "^10.5.0",
-        "type-fest": "^4.41.0"
+        "@augment-vir/assert": "^31.38.0",
+        "@augment-vir/common": "^31.38.0",
+        "@sentry/browser": "^10.14.0",
+        "@sentry/core": "^10.14.0",
+        "@sentry/node": "^10.14.0",
+        "date-vir": "^7.4.2",
+        "type-fest": "^5.0.1"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.32.2",
+        "@augment-vir/test": "^31.38.0",
         "@eslint/eslintrc": "^3.3.1",
-        "@eslint/js": "^9.33.0",
-        "@stylistic/eslint-plugin": "^5.2.3",
+        "@eslint/js": "^9.36.0",
+        "@stylistic/eslint-plugin": "^5.4.0",
         "@stylistic/eslint-plugin-ts": "^4.4.1",
-        "@typescript-eslint/eslint-plugin": "^8.39.1",
+        "@typescript-eslint/eslint-plugin": "^8.44.1",
         "@web/dev-server-esbuild": "^1.0.4",
         "@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.2.0",
+        "cspell": "^9.2.1",
         "dependency-cruiser": "^17.0.1",
-        "esbuild": "^0.25.9",
-        "eslint": "^9.33.0",
+        "esbuild": "^0.25.10",
+        "eslint": "^9.36.0",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-jsdoc": "^54.1.0",
+        "eslint-plugin-jsdoc": "^60.2.0",
         "eslint-plugin-monorepo-cop": "^1.0.2",
         "eslint-plugin-playwright": "^2.2.2",
         "eslint-plugin-prettier": "^5.5.4",
         "eslint-plugin-require-extensions": "^0.1.3",
-        "eslint-plugin-sonarjs": "^3.0.4",
+        "eslint-plugin-sonarjs": "^3.0.5",
         "eslint-plugin-unicorn": "^57.0.0",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
-        "npm-check-updates": "^18.0.2",
+        "npm-check-updates": "^18.3.0",
         "prettier": "~3.3.3",
         "prettier-plugin-interpolated-html-tags": "^2.0.1",
         "prettier-plugin-jsdoc": "^1.3.3",
         "prettier-plugin-multiline-arrays": "^4.0.3",
-        "prettier-plugin-organize-imports": "^4.2.0",
+        "prettier-plugin-organize-imports": "^4.3.0",
         "prettier-plugin-packagejson": "^2.5.19",
         "prettier-plugin-sort-json": "^4.1.1",
         "prettier-plugin-toml": "^2.0.6",
-        "typedoc": "^0.28.10",
+        "runstorm": "^0.6.2",
+        "typedoc": "^0.28.13",
         "typescript": "^5.9.2",
-        "typescript-eslint": "^8.39.1",
-        "virmator": "^13.16.2",
-        "vite": "^7.1.2"
+        "typescript-eslint": "^8.44.1",
+        "virmator": "^14.0.4",
+        "vite": "^7.1.7"
     },
     "engines": {
         "node": ">=22"