@n-dx/core 0.1.0

package/packages/web/dist/viewer/memory-monitor.js

@@ -0,0 +1,218 @@
+/**
+ * Client-side memory usage monitoring and early warning system.
+ *
+ * Tracks browser memory consumption in real-time, detects approaching
+ * memory limits, and triggers graceful degradation before OOM crashes.
+ *
+ * Uses `performance.memory` (Chrome/Edge) for precise readings and
+ * falls back to heuristic-based estimation on other browsers.
+ *
+ * Designed as a standalone module with zero framework dependencies —
+ * the Preact hook (`useMemoryMonitor`) is provided separately.
+ */
+import { registerPollingSource, } from "./polling-state.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_THRESHOLDS = {
+    elevated: 0.50,
+    warning: 0.70,
+    critical: 0.85,
+};
+const DEFAULT_INTERVAL_MS = 5000;
+/** Key used to register with the centralized polling state manager. */
+const POLLING_STATE_KEY = "memory-monitor";
+/** Heuristic heap limit for browsers without performance.memory (2 GB). */
+const FALLBACK_HEAP_LIMIT = 2 * 1024 * 1024 * 1024;
+/** Maximum number of snapshots kept in history for debugging. */
+const MAX_HISTORY_LENGTH = 60;
+// ─── Module state ────────────────────────────────────────────────────────────
+let config = {
+    intervalMs: DEFAULT_INTERVAL_MS,
+    thresholds: { ...DEFAULT_THRESHOLDS },
+    onLevelChange: null,
+};
+let pollTimer = null;
+let stateUnsub = null;
+let currentLevel = "normal";
+let latestSnapshot = null;
+let snapshotHistory = [];
+let changeListeners = [];
+// ─── Detection ───────────────────────────────────────────────────────────────
+/** Check if the browser exposes precise memory metrics. */
+export function hasPerformanceMemory() {
+    const perf = performance;
+    return (typeof perf.memory !== "undefined" &&
+        typeof perf.memory.usedJSHeapSize === "number");
+}
+// ─── Snapshot ────────────────────────────────────────────────────────────────
+/** Determine the memory level for a given usage ratio. */
+export function classifyLevel(ratio, thresholds) {
+    if (ratio < 0)
+        return "normal"; // no data
+    if (ratio >= thresholds.critical)
+        return "critical";
+    if (ratio >= thresholds.warning)
+        return "warning";
+    if (ratio >= thresholds.elevated)
+        return "elevated";
+    return "normal";
+}
+/** Take a memory snapshot using the best available API. */
+export function takeSnapshot(thresholds = config.thresholds) {
+    const perf = performance;
+    if (perf.memory) {
+        const { usedJSHeapSize, totalJSHeapSize, jsHeapSizeLimit } = perf.memory;
+        const usageRatio = jsHeapSizeLimit > 0 ? usedJSHeapSize / jsHeapSizeLimit : -1;
+        return {
+            usedJSHeapSize,
+            totalJSHeapSize,
+            jsHeapSizeLimit,
+            usageRatio,
+            level: classifyLevel(usageRatio, thresholds),
+            timestamp: new Date().toISOString(),
+            precise: true,
+        };
+    }
+    // Fallback: no precise data available. Return unknowns.
+    return {
+        usedJSHeapSize: -1,
+        totalJSHeapSize: -1,
+        jsHeapSizeLimit: FALLBACK_HEAP_LIMIT,
+        usageRatio: -1,
+        level: "normal",
+        timestamp: new Date().toISOString(),
+        precise: false,
+    };
+}
+// ─── Formatting ──────────────────────────────────────────────────────────────
+/** Format bytes as a human-readable string (e.g. "142.5 MB"). */
+export function formatBytes(bytes) {
+    if (bytes < 0)
+        return "N/A";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+/** Format a usage ratio as a percentage string (e.g. "72.3%"). */
+export function formatRatio(ratio) {
+    if (ratio < 0)
+        return "N/A";
+    return `${(ratio * 100).toFixed(1)}%`;
+}
+// ─── Monitor lifecycle ───────────────────────────────────────────────────────
+/** Subscribe to every new snapshot. Returns an unsubscribe function. */
+export function onSnapshot(listener) {
+    changeListeners.push(listener);
+    return () => {
+        changeListeners = changeListeners.filter((l) => l !== listener);
+    };
+}
+function notifyListeners(snapshot) {
+    for (const listener of changeListeners) {
+        try {
+            listener(snapshot);
+        }
+        catch (err) {
+            console.error("[memory-monitor] listener error:", err);
+        }
+    }
+}
+function poll() {
+    const snapshot = takeSnapshot(config.thresholds);
+    latestSnapshot = snapshot;
+    // Keep a bounded history ring for debugging.
+    snapshotHistory.push(snapshot);
+    if (snapshotHistory.length > MAX_HISTORY_LENGTH) {
+        snapshotHistory = snapshotHistory.slice(-MAX_HISTORY_LENGTH);
+    }
+    // Detect level transitions.
+    const previousLevel = currentLevel;
+    if (snapshot.level !== currentLevel) {
+        currentLevel = snapshot.level;
+        if (config.onLevelChange) {
+            config.onLevelChange(snapshot, previousLevel);
+        }
+    }
+    notifyListeners(snapshot);
+}
+/**
+ * Start the memory monitor with the given configuration overrides.
+ * Safe to call multiple times — restarts with new config if already running.
+ */
+export function startMemoryMonitor(overrides = {}) {
+    // Stop any existing monitor before applying new config.
+    stopMemoryMonitor();
+    config = {
+        intervalMs: overrides.intervalMs ?? DEFAULT_INTERVAL_MS,
+        thresholds: overrides.thresholds
+            ? { ...DEFAULT_THRESHOLDS, ...overrides.thresholds }
+            : { ...DEFAULT_THRESHOLDS },
+        onLevelChange: overrides.onLevelChange ?? null,
+    };
+    // Take an immediate snapshot on start.
+    poll();
+    pollTimer = setInterval(poll, config.intervalMs);
+    // Register with centralized polling state as ESSENTIAL — the memory
+    // monitor must keep running during memory pressure to detect recovery.
+    stateUnsub = registerPollingSource(POLLING_STATE_KEY, {
+        suspend: () => stopPollTimer(),
+        resume: () => {
+            if (pollTimer === null) {
+                pollTimer = setInterval(poll, config.intervalMs);
+            }
+        },
+        dispose: () => {
+            stopPollTimer();
+            stateUnsub = null;
+        },
+        getStatus: () => (pollTimer !== null ? "active" : "idle"),
+    }, { essential: true });
+}
+/** Stop the poll interval timer without touching polling-state registration. */
+function stopPollTimer() {
+    if (pollTimer) {
+        clearInterval(pollTimer);
+        pollTimer = null;
+    }
+}
+/** Stop the memory monitor and clean up. */
+export function stopMemoryMonitor() {
+    stopPollTimer();
+    // Deregister from centralized polling state. Nullify first to
+    // prevent re-entrant dispose.
+    if (stateUnsub) {
+        const unsub = stateUnsub;
+        stateUnsub = null;
+        unsub();
+    }
+}
+/** Get the most recent memory snapshot, or null if the monitor has not run. */
+export function getLatestSnapshot() {
+    return latestSnapshot;
+}
+/** Get the snapshot history (up to MAX_HISTORY_LENGTH entries). */
+export function getSnapshotHistory() {
+    return snapshotHistory;
+}
+/** Get the current memory warning level. */
+export function getCurrentLevel() {
+    return currentLevel;
+}
+/** Reset all module state (for testing). */
+export function resetMemoryMonitor() {
+    stopMemoryMonitor();
+    currentLevel = "normal";
+    latestSnapshot = null;
+    snapshotHistory = [];
+    changeListeners = [];
+    stateUnsub = null;
+    config = {
+        intervalMs: DEFAULT_INTERVAL_MS,
+        thresholds: { ...DEFAULT_THRESHOLDS },
+        onLevelChange: null,
+    };
+}
+//# sourceMappingURL=memory-monitor.js.map

package/packages/web/dist/viewer/memory-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-monitor.js","sourceRoot":"","sources":["../../src/viewer/memory-monitor.ts"],"names":[],"mappings":"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"}

package/packages/web/dist/viewer/message-coalescer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * WebSocket message coalescing for rapid sequential updates.
+ *
+ * When multiple WebSocket messages arrive in quick succession (e.g. a batch
+ * of rex:item-updated events during a bulk operation), this module batches
+ * them into a single flush to avoid redundant fetch calls.
+ *
+ * Two-callback design:
+ *
+ *   onMessage(msg)  — fires immediately for each message, enabling optimistic
+ *                     UI updates with no delay.
+ *   onFlush(batch)  — fires once per throttle window (trailing edge), after
+ *                     messages stop arriving. The batch includes all message
+ *                     types seen, counts per type, and the full ordered list.
+ *                     Consumers use this to trigger a single reconciliation
+ *                     (e.g. fetchPRDData + fetchTaskUsage) instead of N calls.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+/** A parsed WebSocket message. Minimum requirement: a `type` string. */
+export interface ParsedWSMessage {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+/** The coalesced batch delivered to onFlush. */
+export interface CoalescedBatch {
+    /** Deduplicated set of message types in this batch. */
+    readonly types: Set<string>;
+    /** Per-type count of messages in this batch. */
+    readonly countByType: Map<string, number>;
+    /** All messages in arrival order — no data loss. */
+    readonly messages: readonly ParsedWSMessage[];
+    /** Total number of messages. Convenience alias for messages.length. */
+    readonly size: number;
+}
+/** Configuration for the message coalescer. */
+export interface MessageCoalescerConfig {
+    /**
+     * Called once per throttle window with the coalesced batch.
+     * Use this to trigger reconciliation fetches.
+     */
+    onFlush: (batch: CoalescedBatch) => void;
+    /**
+     * Called immediately for each incoming message (before batching).
+     * Use this for optimistic local state updates that should not be delayed.
+     */
+    onMessage?: ((msg: ParsedWSMessage) => void) | undefined;
+    /**
+     * Trailing-edge debounce window in milliseconds.
+     * Messages arriving within this window are coalesced into one flush.
+     * Default: 150ms.
+     */
+    windowMs?: number | undefined;
+    /**
+     * Maximum number of messages to accumulate before forcing a flush.
+     * Prevents unbounded memory growth during sustained bursts.
+     * Default: 50.
+     */
+    maxBatchSize?: number | undefined;
+}
+/** A message coalescer instance. */
+export interface MessageCoalescer {
+    /** Push a new message into the coalescer. */
+    push(msg: ParsedWSMessage): void;
+    /** Force-flush the current batch immediately. No-op if empty. */
+    flush(): void;
+    /** Dispose: cancel timers, clear batch, ignore future pushes. */
+    dispose(): void;
+}
+/**
+ * Create a new message coalescer.
+ *
+ * Usage:
+ * ```ts
+ * const coalescer = createMessageCoalescer({
+ *   onMessage: (msg) => {
+ *     // Immediate optimistic update
+ *     if (msg.type === "rex:item-updated") applyItemUpdate(msg);
+ *   },
+ *   onFlush: (batch) => {
+ *     // Coalesced reconciliation — runs once per window
+ *     if (batch.types.has("rex:item-updated") || batch.types.has("rex:prd-changed")) {
+ *       fetchPRDData();
+ *       fetchTaskUsage();
+ *     }
+ *   },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   coalescer.push(msg);
+ * };
+ * ```
+ */
+export declare function createMessageCoalescer(config: MessageCoalescerConfig): MessageCoalescer;

package/packages/web/dist/viewer/message-coalescer.js

@@ -0,0 +1,121 @@
+/**
+ * WebSocket message coalescing for rapid sequential updates.
+ *
+ * When multiple WebSocket messages arrive in quick succession (e.g. a batch
+ * of rex:item-updated events during a bulk operation), this module batches
+ * them into a single flush to avoid redundant fetch calls.
+ *
+ * Two-callback design:
+ *
+ *   onMessage(msg)  — fires immediately for each message, enabling optimistic
+ *                     UI updates with no delay.
+ *   onFlush(batch)  — fires once per throttle window (trailing edge), after
+ *                     messages stop arriving. The batch includes all message
+ *                     types seen, counts per type, and the full ordered list.
+ *                     Consumers use this to trigger a single reconciliation
+ *                     (e.g. fetchPRDData + fetchTaskUsage) instead of N calls.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_WINDOW_MS = 150;
+const DEFAULT_MAX_BATCH_SIZE = 50;
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a new message coalescer.
+ *
+ * Usage:
+ * ```ts
+ * const coalescer = createMessageCoalescer({
+ *   onMessage: (msg) => {
+ *     // Immediate optimistic update
+ *     if (msg.type === "rex:item-updated") applyItemUpdate(msg);
+ *   },
+ *   onFlush: (batch) => {
+ *     // Coalesced reconciliation — runs once per window
+ *     if (batch.types.has("rex:item-updated") || batch.types.has("rex:prd-changed")) {
+ *       fetchPRDData();
+ *       fetchTaskUsage();
+ *     }
+ *   },
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   coalescer.push(msg);
+ * };
+ * ```
+ */
+export function createMessageCoalescer(config) {
+    const windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+    const maxBatchSize = config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
+    const onFlush = config.onFlush;
+    const onMessage = config.onMessage ?? null;
+    let messages = [];
+    let types = new Set();
+    let countByType = new Map();
+    let timer = null;
+    let disposed = false;
+    function clearTimer() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function buildBatch() {
+        return {
+            types,
+            countByType,
+            messages,
+            size: messages.length,
+        };
+    }
+    function resetBatch() {
+        messages = [];
+        types = new Set();
+        countByType = new Map();
+    }
+    function doFlush() {
+        clearTimer();
+        if (messages.length === 0)
+            return;
+        const batch = buildBatch();
+        resetBatch();
+        onFlush(batch);
+    }
+    function scheduleFlush() {
+        clearTimer();
+        timer = setTimeout(doFlush, windowMs);
+    }
+    function push(msg) {
+        if (disposed)
+            return;
+        // Immediate per-message callback (for optimistic updates)
+        if (onMessage)
+            onMessage(msg);
+        // Accumulate into the current batch
+        messages.push(msg);
+        types.add(msg.type);
+        countByType.set(msg.type, (countByType.get(msg.type) ?? 0) + 1);
+        // Force flush if batch size limit reached
+        if (messages.length >= maxBatchSize) {
+            doFlush();
+            return;
+        }
+        // Reset the trailing-edge debounce timer
+        scheduleFlush();
+    }
+    function flush() {
+        if (disposed)
+            return;
+        doFlush();
+    }
+    function dispose() {
+        disposed = true;
+        clearTimer();
+        resetBatch();
+    }
+    return { push, flush, dispose };
+}
+//# sourceMappingURL=message-coalescer.js.map

package/packages/web/dist/viewer/message-coalescer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-coalescer.js","sourceRoot":"","sources":["../../src/viewer/message-coalescer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA6DH,gFAAgF;AAEhF,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAC9B,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAElC,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA8B;IACnE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACtD,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,sBAAsB,CAAC;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC;IAE3C,IAAI,QAAQ,GAAsB,EAAE,CAAC;IACrC,IAAI,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,IAAI,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,IAAI,KAAK,GAAyC,IAAI,CAAC;IACvD,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,SAAS,UAAU;QACjB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;IACH,CAAC;IAED,SAAS,UAAU;QACjB,OAAO;YACL,KAAK;YACL,WAAW;YACX,QAAQ;YACR,IAAI,EAAE,QAAQ,CAAC,MAAM;SACtB,CAAC;IACJ,CAAC;IAED,SAAS,UAAU;QACjB,QAAQ,GAAG,EAAE,CAAC;QACd,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;QAC1B,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,CAAC;IAED,SAAS,OAAO;QACd,UAAU,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAElC,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,UAAU,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;IAED,SAAS,aAAa;QACpB,UAAU,EAAE,CAAC;QACb,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,SAAS,IAAI,CAAC,GAAoB;QAChC,IAAI,QAAQ;YAAE,OAAO;QAErB,0DAA0D;QAC1D,IAAI,SAAS;YAAE,SAAS,CAAC,GAAG,CAAC,CAAC;QAE9B,oCAAoC;QACpC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAEhE,0CAA0C;QAC1C,IAAI,QAAQ,CAAC,MAAM,IAAI,YAAY,EAAE,CAAC;YACpC,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QAED,yCAAyC;QACzC,aAAa,EAAE,CAAC;IAClB,CAAC;IAED,SAAS,KAAK;QACZ,IAAI,QAAQ;YAAE,OAAO;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,SAAS,OAAO;QACd,QAAQ,GAAG,IAAI,CAAC;QAChB,UAAU,EAAE,CAAC;QACb,UAAU,EAAE,CAAC;IACf,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC"}

package/packages/web/dist/viewer/message-throttle.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Per-type WebSocket message throttle with configurable debounce.
+ *
+ * Sits between the raw WebSocket and downstream handlers (e.g. the message
+ * coalescer) to provide per-message-type trailing-edge debouncing. Each
+ * configured type gets its own independent timer and delay, so different
+ * message types can be throttled at different rates.
+ *
+ * Design decisions:
+ *
+ *   - **Trailing-edge debounce** — messages accumulate during the delay
+ *     window and are forwarded once the timer fires. New messages of the
+ *     same type reset the timer (like the coalescer, but per-type).
+ *
+ *   - **Per-type isolation** — timers are fully independent. A burst of
+ *     rex:item-updated messages doesn't delay rex:prd-changed.
+ *
+ *   - **Bounded memory** — maxPendingPerType caps how many messages can
+ *     accumulate per type before a force-flush, preventing unbounded growth
+ *     during sustained bursts.
+ *
+ *   - **Pass-through** — message types not in the throttledTypes set are
+ *     forwarded immediately with zero delay, preserving low-latency for
+ *     types that don't need throttling.
+ *
+ * Standalone module with zero framework dependencies.
+ * The Preact integration lives in the consumer (views/prd.ts etc.).
+ */
+import type { ParsedWSMessage } from "./message-coalescer.js";
+/** Configuration for the throttled message handler. */
+export interface ThrottledHandlerConfig {
+    /**
+     * Called for each message after its type's debounce window expires.
+     * For unthrottled types, called immediately.
+     */
+    onMessage: (msg: ParsedWSMessage) => void;
+    /**
+     * Default debounce delay in milliseconds for throttled types
+     * that don't have an explicit entry in `delays`.
+     * Default: 250ms.
+     */
+    defaultDelayMs?: number | undefined;
+    /**
+     * Per-message-type delay overrides. Keys are message type strings,
+     * values are delay in milliseconds. Types not listed here fall back
+     * to `defaultDelayMs`.
+     */
+    delays?: Partial<Record<string, number>> | undefined;
+    /**
+     * Message types to throttle. Types not in this set pass through
+     * immediately to `onMessage`.
+     *
+     * If undefined (not provided), ALL types are throttled.
+     * If an empty array/set, NO types are throttled (all pass through).
+     */
+    throttledTypes?: ReadonlySet<string> | readonly string[] | undefined;
+    /**
+     * Maximum pending messages per type before force-flushing.
+     * Prevents unbounded memory growth during sustained bursts.
+     * Default: 20.
+     */
+    maxPendingPerType?: number | undefined;
+}
+/** A throttled message handler instance. */
+export interface MessageThrottle {
+    /** Push a message through the throttle. */
+    push(msg: ParsedWSMessage): void;
+    /** Force-flush all pending messages across all types immediately. */
+    flush(): void;
+    /** Dispose: cancel all timers, clear all pending, ignore future pushes. */
+    dispose(): void;
+}
+/**
+ * Create a new per-type message throttle.
+ *
+ * Usage:
+ * ```ts
+ * const throttle = createMessageThrottle({
+ *   onMessage: (msg) => coalescer.push(msg),
+ *   defaultDelayMs: 250,
+ *   delays: {
+ *     "rex:prd-changed": 500,    // slow — heavy reconciliation
+ *     "rex:item-updated": 150,   // fast — targeted updates
+ *   },
+ *   throttledTypes: ["rex:prd-changed", "rex:item-updated", "rex:item-deleted"],
+ *   maxPendingPerType: 20,
+ * });
+ *
+ * ws.onmessage = (event) => {
+ *   const msg = JSON.parse(event.data);
+ *   throttle.push(msg);
+ * };
+ * ```
+ */
+export declare function createMessageThrottle(config: ThrottledHandlerConfig): MessageThrottle;