cloudflare-next-intl 0.6.0 → 0.6.2

package/dist/src/error_handling/install_console_error_override.d.ts

@@ -8,11 +8,10 @@ import { type ReportErrorConfig } from './report_error';
  * own `console`). Only takes effect when `config.errorHandling.overrideConsoleError`
  * is `true`.
  *
- * Caps at `MAX_REPORTS_PER_INSTALL` (20) reports per install — a component
- * stuck in a render-error loop calls `console.error` on every render, and
- * without a cap this would report (and, server-side, background via
- * `waitUntil`) unboundedly. Once the cap is hit, `console.error` still runs
- * normally, it just stops being reported.
+ * A component stuck in a render-error loop calls `console.error` on every
+ * render — `reportError`'s own dedup/cap (on by default, see
+ * `errorHandling.dedup`/`maxReports`) is what stops that from reporting
+ * unboundedly; this function does not duplicate that cap itself.
  *
  * `config.errorHandling.ignoreConsoleErrors` (default
  * `defaultIgnoredConsoleErrors` — this package's own Firebase Auth error

package/dist/src/error_handling/install_console_error_override.js

@@ -1,7 +1,6 @@
 import reportError from './report_error';
 import stringifyUnknown from './stringify_unknown';
 import { defaultIgnoredConsoleErrors } from './default_ignored_console_errors';
-const MAX_REPORTS_PER_INSTALL = 20;
 /**
  * Replaces the global `console.error` so every `console.error(...)` call is
  * also routed through `config.errorHandling.onError`/`reportError` — the
@@ -11,11 +10,10 @@ const MAX_REPORTS_PER_INSTALL = 20;
  * own `console`). Only takes effect when `config.errorHandling.overrideConsoleError`
  * is `true`.
  *
- * Caps at `MAX_REPORTS_PER_INSTALL` (20) reports per install — a component
- * stuck in a render-error loop calls `console.error` on every render, and
- * without a cap this would report (and, server-side, background via
- * `waitUntil`) unboundedly. Once the cap is hit, `console.error` still runs
- * normally, it just stops being reported.
+ * A component stuck in a render-error loop calls `console.error` on every
+ * render — `reportError`'s own dedup/cap (on by default, see
+ * `errorHandling.dedup`/`maxReports`) is what stops that from reporting
+ * unboundedly; this function does not duplicate that cap itself.
  *
  * `config.errorHandling.ignoreConsoleErrors` (default
  * `defaultIgnoredConsoleErrors` — this package's own Firebase Auth error
@@ -36,18 +34,14 @@ export default function installConsoleErrorOverride(config, isClient) {
     if (console.error.__isErrorHandlingOverride)
         return;
     const originalConsoleError = console.error.bind(console);
-    let reportCount = 0;
     const override = (message, ...optionalParams) => {
         originalConsoleError(message, ...optionalParams);
-        if (reportCount >= MAX_REPORTS_PER_INSTALL)
-            return;
         const stringified = stringifyUnknown(message, isClient);
         const ignoreList = config.errorHandling?.ignoreConsoleErrors ?? defaultIgnoredConsoleErrors;
         if (ignoreList.some((ignored) => stringified.includes(ignored)))
             return;
         if (config.errorHandling?.ignoreConsoleError?.(stringified))
             return;
-        reportCount++;
         void reportError(config, { error: message, classOrMethodName: 'Global Console Error Handler', params: optionalParams, isClient });
     };
     override.__isErrorHandlingOverride = true;

package/dist/src/error_handling/report_error.d.ts

@@ -6,10 +6,11 @@ export interface ReportErrorConfig {
 /**
  * Reports `params` via `config.errorHandling.onError` (default
  * `console.error(params.formattedMessage)`), unless
- * `config.errorHandling.enable === false` or `params.consent` is set and
- * not `true` (reporting to a third party without cookie consent can itself
- * be GDPR-relevant). Never throws — a broken reporter must not mask the
- * original error.
+ * `config.errorHandling.enable === false`, `params.consent` is set and not
+ * `true` (reporting to a third party without cookie consent can itself be
+ * GDPR-relevant), or dedup throttles it (on by default — see
+ * `errorHandling.dedup`/`throttleMs`/`resetDedup`). Never throws — a broken
+ * reporter must not mask the original error.
  *
  * Always overwrites `params.formattedMessage` with a fresh
  * `formatErrorMessage(params)` before reporting — a human-readable one-line
@@ -17,11 +18,6 @@ export interface ReportErrorConfig {
  * instead of the raw `error`/`params` object, for a default reporter (or a
  * simple `onError`) to print directly.
  *
- * No built-in dedup/throttling: this package has no per-request context to
- * safely scope such state to (module-scope state would leak across
- * concurrent requests in a long-lived server process). Do dedup/throttling
- * in your own `onError` if you need it, scoped to your own request context.
- *
  * When `config.generate?.getCloudflareContext` is set, `waitUntil` is called
  * SYNCHRONOUSLY, in the same tick, with the `callOnError(...)` promise —
  * Cloudflare Workers only extends the request's lifetime for work already
@@ -32,6 +28,12 @@ export interface ReportErrorConfig {
  * `onError` directly when `getCloudflareContext`/`ctx.waitUntil` is unset or
  * unavailable (e.g. outside a Cloudflare Worker).
  *
+ * Passing `params.error` as `null`/`undefined` with `errorHandling.resetDedup: true`
+ * and nothing else is a valid "reset-only" call: the dedup state clears and
+ * `reportError` returns immediately, without calling `onError` — useful to
+ * clear dedup state once at the very start of a request/cron tick, before
+ * any handler that might call `reportError` for a real error runs.
+ *
  * @param config Pass the relevant slices of your `RoutingConfig` directly —
  *   `{ errorHandling: config.errorHandling, generate: config.generate }`.
  */

package/dist/src/error_handling/report_error.js

@@ -1,4 +1,16 @@
 import formatErrorMessage from './format_error_message';
+import stringifyUnknown from './stringify_unknown';
+const DEFAULT_THROTTLE_MS = 5000;
+// Module-scope dedup state — safe by default only because a fresh JS realm
+// (isolate/Worker instance) starts with it cleared. In a long-lived server
+// process reused across many requests, pass `resetDedup: true` on the first
+// `reportError` call of each request/cron tick, or one request's errors can
+// suppress another's.
+let lastDedupKey = null;
+let lastReportedAt = 0;
+function buildDedupKey(params) {
+    return params.dedupKey ?? `${params.classOrMethodName} ${stringifyUnknown(params.error, params.isClient)} ${params.params ? stringifyUnknown(params.params, params.isClient) : ''}`;
+}
 async function callOnError(config, params) {
     const paramsWithFormattedMessage = { ...params, formattedMessage: formatErrorMessage(params) };
     try {
@@ -16,10 +28,11 @@ async function callOnError(config, params) {
 /**
  * Reports `params` via `config.errorHandling.onError` (default
  * `console.error(params.formattedMessage)`), unless
- * `config.errorHandling.enable === false` or `params.consent` is set and
- * not `true` (reporting to a third party without cookie consent can itself
- * be GDPR-relevant). Never throws — a broken reporter must not mask the
- * original error.
+ * `config.errorHandling.enable === false`, `params.consent` is set and not
+ * `true` (reporting to a third party without cookie consent can itself be
+ * GDPR-relevant), or dedup throttles it (on by default — see
+ * `errorHandling.dedup`/`throttleMs`/`resetDedup`). Never throws — a broken
+ * reporter must not mask the original error.
  *
  * Always overwrites `params.formattedMessage` with a fresh
  * `formatErrorMessage(params)` before reporting — a human-readable one-line
@@ -27,11 +40,6 @@ async function callOnError(config, params) {
  * instead of the raw `error`/`params` object, for a default reporter (or a
  * simple `onError`) to print directly.
  *
- * No built-in dedup/throttling: this package has no per-request context to
- * safely scope such state to (module-scope state would leak across
- * concurrent requests in a long-lived server process). Do dedup/throttling
- * in your own `onError` if you need it, scoped to your own request context.
- *
  * When `config.generate?.getCloudflareContext` is set, `waitUntil` is called
  * SYNCHRONOUSLY, in the same tick, with the `callOnError(...)` promise —
  * Cloudflare Workers only extends the request's lifetime for work already
@@ -42,15 +50,36 @@ async function callOnError(config, params) {
  * `onError` directly when `getCloudflareContext`/`ctx.waitUntil` is unset or
  * unavailable (e.g. outside a Cloudflare Worker).
  *
+ * Passing `params.error` as `null`/`undefined` with `errorHandling.resetDedup: true`
+ * and nothing else is a valid "reset-only" call: the dedup state clears and
+ * `reportError` returns immediately, without calling `onError` — useful to
+ * clear dedup state once at the very start of a request/cron tick, before
+ * any handler that might call `reportError` for a real error runs.
+ *
  * @param config Pass the relevant slices of your `RoutingConfig` directly —
  *   `{ errorHandling: config.errorHandling, generate: config.generate }`.
  */
 export default async function reportError(config, params) {
     const errorHandling = config?.errorHandling;
+    if (errorHandling?.resetDedup) {
+        lastDedupKey = null;
+        lastReportedAt = 0;
+        if (params.error === null || params.error === undefined)
+            return;
+    }
     if (errorHandling?.enable === false)
         return;
     if (params.consent !== undefined && params.consent !== true)
         return;
+    if (errorHandling?.dedup !== false) {
+        const throttleMs = errorHandling?.throttleMs ?? DEFAULT_THROTTLE_MS;
+        const dedupKey = buildDedupKey(params);
+        const now = Date.now();
+        if (dedupKey === lastDedupKey && now - lastReportedAt < throttleMs)
+            return;
+        lastDedupKey = dedupKey;
+        lastReportedAt = now;
+    }
     const waitUntil = config?.generate?.getCloudflareContext?.({ async: false })?.ctx?.waitUntil;
     if (waitUntil) {
         waitUntil(callOnError(errorHandling, params));

package/dist/src/types/types.d.ts

@@ -149,6 +149,14 @@ export interface ErrorHandlingParams {
      * yourself — it's always overwritten.
      */
     formattedMessage?: string;
+    /**
+     * Key used by `config.errorHandling.dedupGate` to dedup this report
+     * against the immediately preceding one. Defaults to
+     * `` `${classOrMethodName} ${stringifyUnknown(error)} ${stringifyUnknown(params ?? '')}` ``
+     * when omitted (built by `reportError` itself) — set this explicitly
+     * only if you want a coarser/different dedup key.
+     */
+    dedupKey?: string;
 }
 export interface ErrorHandlingRoutingConfig {
     /**
@@ -193,6 +201,27 @@ export interface ErrorHandlingRoutingConfig {
      * substring match.
      */
     ignoreConsoleError?: (message: string) => boolean;
+    /**
+     * Dedup: `reportError` skips reporting an error whose key (`dedupKey`,
+     * or a built-in key derived from `classOrMethodName`/`error`/`params`
+     * when omitted) matches the immediately preceding reported error's key,
+     * within `throttleMs`. On by default (matches this package's own
+     * internal call sites and `installConsoleErrorOverride`'s console-loop
+     * guard). Set `false` to report every distinct call with no dedup at
+     * all.
+     *
+     * The dedup state lives inside `reportError`'s own module — this is
+     * shared mutable state, safe by default only because a fresh JS realm
+     * (isolate/Worker instance) starts with it cleared; in a long-lived
+     * server process reused across many requests, pass `resetDedup: true`
+     * on the first `reportError` call of each request/cron tick to clear it
+     * (otherwise one request's errors can suppress another's).
+     */
+    dedup?: boolean;
+    /** Throttle window in ms: the same dedup key reported again within this window is skipped. Defaults to `5000`. Only consulted when `dedup` isn't `false`. */
+    throttleMs?: number;
+    /** Clears the dedup last-key/timestamp state before processing this call. Pass `true` on the first `reportError` call of each request/cron tick in a long-lived server process. */
+    resetDedup?: boolean;
 }
 export interface CookieConsentRoutingConfig {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",