@vouchington/utils 0.3.0 → 0.4.0

package/README.md

@@ -31,15 +31,19 @@ import { createMessageTranslator } from '@vouchington/utils/message-catalog'
   and deterministic JSON serialization.
 - `feature-flags`: base64 JSON feature-flag cookie parsing and serialization with caller-injected
   codecs, cookie names, and size policy.
-- `dates`, `format`, `strings`, and `text-metrics`: UTC-day, duration, formatting, text normalization,
-  title casing, and word/sentence helpers.
+- `dates`, `format`, `strings`, and `text-metrics`: UTC-day, duration, weighted-average and display
+  formatting, text normalization, title casing, and word/sentence helpers.
 - `gtin`, `bigint-ids`, and `validation`: GTIN predicates, canonical positive PostgreSQL bigint IDs,
   and basic email/UUID predicates.
 - `query` and `query-string`: generic array/boolean/number parsing, bounded integer parsing, and
   query-string serialization. Cursor parsing intentionally belongs to `@vouchington/pagination`.
 - `slugs` and `urls`: ASCII-only slugification and URL/hostname primitives. URL hostname helpers
-  return `null` for invalid input; `normalizeAsciiHostname` names its ASCII-only contract directly.
-  `matchesHostnamePattern` supports exact and inclusive `*.` hostname patterns.
+  return `null` for invalid input; `normalizeAsciiHostname` names its ASCII-only contract directly,
+  while `normalizeHostname` also supports WHATWG IDN conversion. `matchesHostnamePattern` supports
+  exact and inclusive `*.` hostname patterns.
+- `hashtags`: caller-configured authored/key length and separator policy for canonical ASCII hashtag
+  keys. The package does not choose application limits or accepted input separators.
+- `fetch-ports`: the Fetch standard forbidden-port list and membership predicates.
 - `language-tags`: caller-configured locale normalization and strict `Accept-Language` parsing and
   best matching. HTTP ranges reject malformed syntax and quality parameters; explicit `q=0` ranges
   exclude a candidate when they tie for that candidate's most-specific matching range, so `en;q=0`
@@ -53,8 +57,9 @@ import { createMessageTranslator } from '@vouchington/utils/message-catalog'
   descriptors. Catalog segments cannot contain dots because dots delimit nested keys. Plural values
   and configured number parameters must be finite numbers; callers own catalog content, locale
   choice, and number formatting.
-- `observability`: SDK-free URL, request, event, and span scrubbing. Callers provide credential
-  headers and environment or spike policy; this package has no product defaults.
+- `observability`: SDK-free URL, request, event, and span scrubbing plus a bounded spike-window
+  tracker. Callers provide credential headers and environment or spike policy; this package has no
+  product defaults.
 
 ```ts
 const money = createMoneyCatalog([{ code: 'credit', minorUnitExponent: 2 }] as const, 6)

package/dist/fetch-ports.d.mts

@@ -0,0 +1,4 @@
+/** Ports blocked by https://fetch.spec.whatwg.org/#port-blocking. */
+export declare const FETCH_FORBIDDEN_PORTS: readonly number[];
+export declare function isFetchForbiddenPort(port: number): boolean;
+export declare function isFetchSafePort(port: number): boolean;

package/dist/fetch-ports.mjs

@@ -0,0 +1,15 @@
+/** Ports blocked by https://fetch.spec.whatwg.org/#port-blocking. */
+export const FETCH_FORBIDDEN_PORTS = Object.freeze([
+    1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102,
+    103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465,
+    512, 513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993,
+    995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668,
+    6669, 6679, 6697, 10080,
+]);
+const FETCH_FORBIDDEN_PORT_SET = new Set(FETCH_FORBIDDEN_PORTS);
+export function isFetchForbiddenPort(port) {
+    return FETCH_FORBIDDEN_PORT_SET.has(port);
+}
+export function isFetchSafePort(port) {
+    return Number.isInteger(port) && port >= 0 && port <= 65_535 && !isFetchForbiddenPort(port);
+}

package/dist/format.d.mts

@@ -6,3 +6,5 @@ export declare function generateExcerpt(markdown: string, maximumLength?: number
 export declare function formatPercent(value: number): string;
 export declare function formatBytes(value: number): string;
 export declare function formatDuration(seconds: number): string;
+/** Calculates the weighted mean of numeric record keys, or null when the total weight is zero. */
+export declare function calculateWeightedAverage(weights: Readonly<Record<string, number>>): number | null;

package/dist/format.mjs

@@ -66,3 +66,11 @@ export function formatDuration(seconds) {
         ? `${hours}:${String(minutes).padStart(2, '0')}:${String(remainder).padStart(2, '0')}`
         : `${String(minutes).padStart(2, '0')}:${String(remainder).padStart(2, '0')}`;
 }
+/** Calculates the weighted mean of numeric record keys, or null when the total weight is zero. */
+export function calculateWeightedAverage(weights) {
+    const total = Object.values(weights).reduce((sum, weight) => sum + weight, 0);
+    if (total === 0)
+        return null;
+    const weightedTotal = Object.entries(weights).reduce((sum, [value, weight]) => sum + Number(value) * weight, 0);
+    return weightedTotal / total;
+}

package/dist/hashtags.d.mts

@@ -0,0 +1,15 @@
+export interface HashtagNormalizerOptions {
+    maximumAuthoredLength: number;
+    maximumKeyLength: number;
+    separators: readonly string[];
+}
+export interface NormalizedHashtag {
+    authored: string;
+    key: string;
+}
+export interface HashtagNormalizer {
+    normalize(input: string): NormalizedHashtag | null;
+    normalizeQuery(input: string): string;
+}
+/** Creates an ASCII hashtag normalizer whose length and separator policy is caller-owned. */
+export declare function createHashtagNormalizer(options: HashtagNormalizerOptions): HashtagNormalizer;

package/dist/hashtags.mjs

@@ -0,0 +1,44 @@
+const HASHTAG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Creates an ASCII hashtag normalizer whose length and separator policy is caller-owned. */
+export function createHashtagNormalizer(options) {
+    assertLength(options.maximumAuthoredLength, 'maximumAuthoredLength');
+    assertLength(options.maximumKeyLength, 'maximumKeyLength');
+    const maximumAuthoredLength = options.maximumAuthoredLength;
+    const maximumKeyLength = options.maximumKeyLength;
+    const separatorPattern = createSeparatorPattern(options.separators);
+    function normalizeQuery(input) {
+        const withoutPrefix = input.trim().replace(/^#/, '');
+        const separated = separatorPattern
+            ? withoutPrefix.replace(separatorPattern, '-')
+            : withoutPrefix;
+        return separated.replace(/-+/g, '-').toLowerCase();
+    }
+    return {
+        normalize(input) {
+            const authored = input.trim();
+            const key = normalizeQuery(authored);
+            if (authored.length === 0 ||
+                authored.length > maximumAuthoredLength ||
+                key.length === 0 ||
+                key.length > maximumKeyLength ||
+                !HASHTAG_PATTERN.test(key)) {
+                return null;
+            }
+            return { authored, key };
+        },
+        normalizeQuery,
+    };
+}
+function assertLength(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+}
+function createSeparatorPattern(separators) {
+    const tokens = [...new Set(separators.filter((separator) => separator.length > 0))].sort((left, right) => right.length - left.length);
+    if (tokens.length === 0)
+        return null;
+    return new RegExp(`(?:${tokens.map(escapeRegularExpression).join('|')})+`, 'g');
+}
+function escapeRegularExpression(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/observability.d.mts

@@ -1,4 +1,5 @@
 export declare const SENSITIVE_VALUE = "[Filtered]";
+export { createSpikeWindowTracker, type SpikeWindowTracker } from './spike-window.mts';
 export interface ScrubOptions {
     credentialHeaders: readonly string[];
 }

package/dist/observability.mjs

@@ -1,4 +1,5 @@
 export const SENSITIVE_VALUE = '[Filtered]';
+export { createSpikeWindowTracker } from './spike-window.mjs';
 const URL_ATTRIBUTES = [
     'url',
     'url.full',

package/dist/spike-window.d.mts

@@ -0,0 +1,6 @@
+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;

package/dist/spike-window.mjs

@@ -0,0 +1,41 @@
+/** Tracks per-fingerprint occurrence counts while evicting expired windows. */
+export function createSpikeWindowTracker(limit, windowMs) {
+    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');
+    const windows = new Map();
+    let lastSweepAt = -Infinity;
+    let lastTimestamp = -Infinity;
+    function sweepExpiredWindows(timestamp) {
+        if (timestamp - lastSweepAt < windowMs)
+            return;
+        lastSweepAt = timestamp;
+        for (const [fingerprint, window] of windows) {
+            if (timestamp - window.windowStart >= windowMs)
+                windows.delete(fingerprint);
+        }
+    }
+    return {
+        get size() {
+            return windows.size;
+        },
+        recordAndCheck(fingerprint, timestamp) {
+            if (!Number.isFinite(timestamp))
+                throw new RangeError('timestamp must be finite');
+            if (timestamp < lastTimestamp) {
+                windows.clear();
+                lastSweepAt = timestamp;
+            }
+            lastTimestamp = timestamp;
+            sweepExpiredWindows(timestamp);
+            const existing = windows.get(fingerprint);
+            const window = existing && timestamp - existing.windowStart < windowMs
+                ? existing
+                : { count: 0, windowStart: timestamp };
+            window.count += 1;
+            windows.set(fingerprint, window);
+            return window.count <= limit;
+        },
+    };
+}

package/dist/urls.d.mts

@@ -4,6 +4,10 @@ export declare function sanitizeImageUrl(value: string | null | undefined): stri
 export declare function isExternalHttpUrl(value: string | null | undefined): boolean;
 export declare function isAsciiHostname(value: string): boolean;
 export declare function normalizeAsciiHostname(value: string): string | null;
+/** Normalizes ASCII or IDN hostnames, using WHATWG URL punycode conversion for Unicode input. */
+export declare function normalizeHostname(value: string): string | null;
+/** Removes one leading lowercase `www.` and trailing dots for presentation. */
+export declare function formatHostnameForDisplay(hostname: string): string;
 export declare function extractUrlHostname(value: string): string | null;
 export declare function getFirstPathSegment(pathname: string): string | null;
 export declare function matchesPathnamePattern(pathname: string, pattern: string): boolean;

package/dist/urls.mjs

@@ -52,6 +52,28 @@ export function normalizeAsciiHostname(value) {
         return null;
     }
 }
+/** Normalizes ASCII or IDN hostnames, using WHATWG URL punycode conversion for Unicode input. */
+export function normalizeHostname(value) {
+    const ascii = normalizeAsciiHostname(value);
+    // oxlint-disable-next-line no-control-regex -- detect input requiring WHATWG punycode conversion.
+    if (ascii !== null || !/[^\x00-\x7F]/.test(value))
+        return ascii;
+    const input = value
+        .trim()
+        .replace(/^(https?):\/+|^(https?):/i, (_match, first, second) => `${first ?? second}://`);
+    try {
+        const candidate = /^[a-z][a-z0-9+.-]*:\/\//i.test(input) ? input : `https://${input}`;
+        const url = new URL(candidate);
+        return url.username || url.password ? null : normalizeAsciiHostname(url.hostname);
+    }
+    catch {
+        return null;
+    }
+}
+/** Removes one leading lowercase `www.` and trailing dots for presentation. */
+export function formatHostnameForDisplay(hostname) {
+    return hostname.replace(/^www\./, '').replace(/\.+$/, '');
+}
 export function extractUrlHostname(value) {
     try {
         return new URL(value).hostname || null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -144,6 +144,16 @@
       "types": "./dist/observability.d.mts",
       "import": "./dist/observability.mjs",
       "default": "./dist/observability.mjs"
+    },
+    "./hashtags": {
+      "types": "./dist/hashtags.d.mts",
+      "import": "./dist/hashtags.mjs",
+      "default": "./dist/hashtags.mjs"
+    },
+    "./fetch-ports": {
+      "types": "./dist/fetch-ports.d.mts",
+      "import": "./dist/fetch-ports.mjs",
+      "default": "./dist/fetch-ports.mjs"
     }
   },
   "publishConfig": {