@vouchington/utils 0.7.0 → 0.7.2

package/README.md

@@ -21,6 +21,8 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
 - `cache-tags`: canonical printable-ASCII wire encoding, one-segment URL decoding, validation,
   and escape-boundary truncation. Applications own family names, route recognition, and purge policy.
   Single-tag validation rejects spaces and comma separators; raw commas are percent-encoded.
+- `schema-growth`: `buildUnboundedUnpartitionedTables()` and `classifyTableGrowth()` map tables to
+  caller-supplied growth reasons. Applications own every table name and reason.
 - `sentry-envelope`: bounded UTF-8 envelope record scanning and safe item-type diagnostics.
   Callers choose the byte and type-list limits; DSN, tunnel, request, and logging policy stay local.
 - `scopes`: caller-owned scope catalog validation, prerequisite expansion, audience and surface

package/dist/observability-url.mjs

@@ -46,9 +46,7 @@ export function scrubSpanUrlAttributes(data, options = {}) {
     return transformRecord(data, (key, value) => {
         if (URL_COMPONENT_ATTRIBUTE_KEYS.includes(key))
             return DROP;
-        return URL_ATTRIBUTE_KEYS.includes(key) && typeof value === 'string'
-            ? scrubUrl(value, options)
-            : value;
+        return URL_ATTRIBUTE_KEYS.includes(key) ? scrubUrlValue(value, options) : value;
     });
 }
 /** Scrub the `referer`/`referrer` header values of a headers record. */

package/dist/observability.d.mts

@@ -1,5 +1,5 @@
 export { SENSITIVE_VALUE } from './observability-records.mts';
-export { createSpikeWindowTracker, type SpikeWindowTracker } from './spike-window.mts';
+export { createSpikeWindowTracker, DEFAULT_MAX_SPIKE_FINGERPRINTS, type SpikeWindowTracker, } from './spike-window.mts';
 export { composeBeforeSend, scrubBreadcrumbs, scrubEvent, scrubHeaders, scrubRequest, scrubSpanAttributes, type ObservableEvent, type ScrubOptions, } from './observability-event.mts';
 export { scrubCredentialHeaders, scrubRequestCredentialFields, scrubSpanCredentialAttributes, } from './observability-credentials.mts';
 export { SCRUBBED_URL_ATTRIBUTE_KEYS, URL_ATTRIBUTE_KEYS, URL_COMPONENT_ATTRIBUTE_KEYS, scrubHeaderUrls, scrubRequestUrlFields, scrubSpanUrlAttributes, scrubUrlValue, stripUrlQueryAndFragment, type UrlScrubOptions, } from './observability-url.mts';

package/dist/observability.mjs

@@ -1,5 +1,5 @@
 export { SENSITIVE_VALUE } from './observability-records.mjs';
-export { createSpikeWindowTracker } from './spike-window.mjs';
+export { createSpikeWindowTracker, DEFAULT_MAX_SPIKE_FINGERPRINTS, } from './spike-window.mjs';
 export { composeBeforeSend, scrubBreadcrumbs, scrubEvent, scrubHeaders, scrubRequest, scrubSpanAttributes, } from './observability-event.mjs';
 export { scrubCredentialHeaders, scrubRequestCredentialFields, scrubSpanCredentialAttributes, } from './observability-credentials.mjs';
 export { SCRUBBED_URL_ATTRIBUTE_KEYS, URL_ATTRIBUTE_KEYS, URL_COMPONENT_ATTRIBUTE_KEYS, scrubHeaderUrls, scrubRequestUrlFields, scrubSpanUrlAttributes, scrubUrlValue, stripUrlQueryAndFragment, } from './observability-url.mjs';

package/dist/schema-growth.d.mts

@@ -0,0 +1,20 @@
+type GrowthPolicyGroup = {
+    /** Why these tables may grow without a time or size bound. */
+    reason: string;
+    tables: readonly string[];
+    /** Skip tables that are partitioned (they are bounded by partition retention instead). */
+    excludePartitioned?: boolean;
+};
+export interface BuildUnboundedTablesOptions {
+    partitionedTables: ReadonlySet<string>;
+    /** Applied in order; a later group or entry overrides an earlier reason for the same table. */
+    groups?: readonly GrowthPolicyGroup[];
+    /** Per-table `[table, reason]` entries, applied after `groups`. */
+    entries?: Iterable<readonly [table: string, reason: string]>;
+}
+export type TableGrowthClass = 'partitioned' | 'unbounded' | 'unclassified';
+/** Maps every deliberately unbounded, unpartitioned table to its documented reason. */
+export declare function buildUnboundedUnpartitionedTables(options: BuildUnboundedTablesOptions): Map<string, string>;
+/** Partitioned wins over unbounded; anything else needs an explicit growth decision. */
+export declare function classifyTableGrowth(table: string, partitionedTables: ReadonlySet<string>, unboundedTables: ReadonlyMap<string, string>): TableGrowthClass;
+export {};

package/dist/schema-growth.mjs

@@ -0,0 +1,20 @@
+/** Maps every deliberately unbounded, unpartitioned table to its documented reason. */
+export function buildUnboundedUnpartitionedTables(options) {
+    const result = new Map();
+    for (const group of options.groups ?? []) {
+        for (const table of group.tables) {
+            if (group.excludePartitioned && options.partitionedTables.has(table))
+                continue;
+            result.set(table, group.reason);
+        }
+    }
+    for (const [table, reason] of options.entries ?? [])
+        result.set(table, reason);
+    return result;
+}
+/** Partitioned wins over unbounded; anything else needs an explicit growth decision. */
+export function classifyTableGrowth(table, partitionedTables, unboundedTables) {
+    if (partitionedTables.has(table))
+        return 'partitioned';
+    return unboundedTables.has(table) ? 'unbounded' : 'unclassified';
+}

package/dist/spike-window.d.mts

@@ -2,5 +2,10 @@ export interface SpikeWindowTracker {
     readonly size: number;
     recordAndCheck(fingerprint: string, timestamp: number): boolean;
 }
-/** Tracks per-fingerprint occurrence counts while evicting expired windows. */
-export declare function createSpikeWindowTracker(limit: number, windowMs: number): SpikeWindowTracker;
+/** Default cap on distinct fingerprints tracked at once. */
+export declare const DEFAULT_MAX_SPIKE_FINGERPRINTS = 1000;
+/**
+ * Tracks per-fingerprint occurrence counts while evicting expired windows. At most
+ * `maxFingerprints` distinct fingerprints are kept; the least recently seen is evicted first.
+ */
+export declare function createSpikeWindowTracker(limit: number, windowMs: number, maxFingerprints?: number): SpikeWindowTracker;

package/dist/spike-window.mjs

@@ -1,9 +1,16 @@
-/** Tracks per-fingerprint occurrence counts while evicting expired windows. */
-export function createSpikeWindowTracker(limit, windowMs) {
+/** Default cap on distinct fingerprints tracked at once. */
+export const DEFAULT_MAX_SPIKE_FINGERPRINTS = 1000;
+/**
+ * Tracks per-fingerprint occurrence counts while evicting expired windows. At most
+ * `maxFingerprints` distinct fingerprints are kept; the least recently seen is evicted first.
+ */
+export function createSpikeWindowTracker(limit, windowMs, maxFingerprints = DEFAULT_MAX_SPIKE_FINGERPRINTS) {
     if (!Number.isSafeInteger(limit) || limit < 0)
         throw new RangeError('limit must be a non-negative safe integer');
     if (!Number.isFinite(windowMs) || windowMs <= 0)
         throw new RangeError('windowMs must be positive and finite');
+    if (!Number.isSafeInteger(maxFingerprints) || maxFingerprints < 1)
+        throw new RangeError('maxFingerprints must be a positive safe integer');
     const windows = new Map();
     let lastSweepAt = -Infinity;
     let lastTimestamp = -Infinity;
@@ -34,7 +41,14 @@ export function createSpikeWindowTracker(limit, windowMs) {
                 ? existing
                 : { count: 0, windowStart: timestamp };
             window.count += 1;
+            windows.delete(fingerprint);
             windows.set(fingerprint, window);
+            if (windows.size > maxFingerprints) {
+                for (const oldest of windows.keys()) {
+                    windows.delete(oldest);
+                    break;
+                }
+            }
             return window.count <= limit;
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -30,6 +30,11 @@
       "import": "./dist/api-response-contract.mjs",
       "default": "./dist/api-response-contract.mjs"
     },
+    "./schema-growth": {
+      "types": "./dist/schema-growth.d.mts",
+      "import": "./dist/schema-growth.mjs",
+      "default": "./dist/schema-growth.mjs"
+    },
     "./cache-tags": {
       "types": "./dist/cache-tags.d.mts",
       "import": "./dist/cache-tags.mjs",