@vouchington/utils 0.3.0 → 0.4.1

package/README.md

@@ -31,15 +31,23 @@ 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.
+- `http-body`: bounded Fetch response-body reads with abort propagation and typed missing/oversize
+  errors.
+- `http-link-pagination`: fail-closed RFC 8288 next-link parsing with same-origin URL and
+  unambiguous cursor extraction.
 - `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 +61,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/http-body.d.mts

@@ -0,0 +1,18 @@
+export interface ReadResponseBodyOptions {
+    readonly response: Response;
+    readonly url: string;
+    readonly maxSizeBytes: number;
+    readonly signal?: AbortSignal;
+}
+export declare class MissingResponseBodyError extends Error {
+    readonly url: string;
+    constructor(url: string);
+}
+export declare class ResponseBodyTooLargeError extends Error {
+    readonly url: string;
+    readonly sizeBytes: number;
+    readonly maxSizeBytes: number;
+    constructor(url: string, sizeBytes: number, maxSizeBytes: number);
+}
+export declare function readResponseBodyAsBuffer({ response, url, maxSizeBytes, signal, }: ReadResponseBodyOptions): Promise<Buffer>;
+export declare function readResponseBody(options: ReadResponseBodyOptions): Promise<string>;

package/dist/http-body.mjs

@@ -0,0 +1,86 @@
+export class MissingResponseBodyError extends Error {
+    url;
+    constructor(url) {
+        super(`HTTP response from ${url} has no body`);
+        this.name = 'MissingResponseBodyError';
+        this.url = url;
+    }
+}
+export class ResponseBodyTooLargeError extends Error {
+    url;
+    sizeBytes;
+    maxSizeBytes;
+    constructor(url, sizeBytes, maxSizeBytes) {
+        super(`HTTP response from ${url} exceeded ${maxSizeBytes} bytes (read ${sizeBytes})`);
+        this.name = 'ResponseBodyTooLargeError';
+        this.url = url;
+        this.sizeBytes = sizeBytes;
+        this.maxSizeBytes = maxSizeBytes;
+    }
+}
+function abortReason(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    if (signal.reason !== undefined)
+        return new Error(String(signal.reason));
+    return new Error('HTTP response body read aborted');
+}
+function validateMaxSize(maxSizeBytes) {
+    if (!Number.isSafeInteger(maxSizeBytes) || maxSizeBytes < 0) {
+        throw new RangeError('maxSizeBytes must be a non-negative safe integer');
+    }
+}
+export async function readResponseBodyAsBuffer({ response, url, maxSizeBytes, signal, }) {
+    validateMaxSize(maxSizeBytes);
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new MissingResponseBodyError(url);
+    let abortListener;
+    let abortPromise;
+    if (signal) {
+        abortPromise = new Promise((_resolve, reject) => {
+            abortListener = () => {
+                const reason = abortReason(signal);
+                void reader.cancel(reason).catch(() => undefined);
+                reject(reason);
+            };
+            if (signal.aborted)
+                abortListener();
+            else
+                signal.addEventListener('abort', abortListener, { once: true });
+        });
+        void abortPromise.catch(() => undefined);
+    }
+    const chunks = [];
+    let totalSize = 0;
+    try {
+        for (;;) {
+            const result = await (abortPromise
+                ? Promise.race([reader.read(), abortPromise])
+                : reader.read());
+            if (signal?.aborted)
+                throw abortReason(signal);
+            if (result.done)
+                return Buffer.concat(chunks, totalSize);
+            totalSize += result.value.byteLength;
+            if (totalSize > maxSizeBytes) {
+                const error = new ResponseBodyTooLargeError(url, totalSize, maxSizeBytes);
+                await reader.cancel(error).catch(() => undefined);
+                throw error;
+            }
+            chunks.push(result.value);
+        }
+    }
+    catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        if (signal && abortListener)
+            signal.removeEventListener('abort', abortListener);
+        reader.releaseLock();
+    }
+}
+export async function readResponseBody(options) {
+    return (await readResponseBodyAsBuffer(options)).toString('utf8');
+}

package/dist/http-link-pagination.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Resolve the `rel=next` target in an RFC 8288 Link header without permitting a
+ * response to redirect an authenticated pagination client to another origin.
+ *
+ * A malformed or unsafe Link header is treated as having no next page. Callers
+ * can therefore stop safely without having to distinguish an exhausted list
+ * from a provider that returned an unusable continuation.
+ */
+export declare function nextPageUrlFromLinkHeader(linkHeader: string | null | undefined, requestUrl: string | URL): URL | null;
+/** Return an unambiguous next-page cursor from a safe Link header target. */
+export declare function nextPageCursorFromLinkHeader(linkHeader: string | null | undefined, requestUrl: string | URL, cursorParameter?: string): string | null;
+/** Validate a pagination request URL before it is used as a Link resolution base. */
+export declare function validatePaginationRequestUrl(requestUrl: string | URL): URL;

package/dist/http-link-pagination.mjs

@@ -0,0 +1,141 @@
+/**
+ * Resolve the `rel=next` target in an RFC 8288 Link header without permitting a
+ * response to redirect an authenticated pagination client to another origin.
+ *
+ * A malformed or unsafe Link header is treated as having no next page. Callers
+ * can therefore stop safely without having to distinguish an exhausted list
+ * from a provider that returned an unusable continuation.
+ */
+export function nextPageUrlFromLinkHeader(linkHeader, requestUrl) {
+    const baseUrl = validatePaginationRequestUrl(requestUrl);
+    if (linkHeader == null)
+        return null;
+    const links = parseLinkHeader(linkHeader);
+    if (!links)
+        return null;
+    const nextLinks = links.filter((link) => link.relations.includes('next'));
+    if (nextLinks.length !== 1)
+        return null;
+    let nextUrl;
+    try {
+        nextUrl = new URL(nextLinks[0].target, baseUrl);
+    }
+    catch {
+        return null;
+    }
+    if (nextUrl.origin !== baseUrl.origin ||
+        nextUrl.username !== '' ||
+        nextUrl.password !== '' ||
+        nextUrl.hash !== '') {
+        return null;
+    }
+    return nextUrl;
+}
+/** Return an unambiguous next-page cursor from a safe Link header target. */
+export function nextPageCursorFromLinkHeader(linkHeader, requestUrl, cursorParameter = 'page') {
+    const nextUrl = nextPageUrlFromLinkHeader(linkHeader, requestUrl);
+    if (!nextUrl)
+        return null;
+    const values = nextUrl.searchParams.getAll(cursorParameter);
+    return values.length === 1 && values[0] !== '' ? values[0] : null;
+}
+/** Validate a pagination request URL before it is used as a Link resolution base. */
+export function validatePaginationRequestUrl(requestUrl) {
+    let url;
+    try {
+        url = new URL(requestUrl);
+    }
+    catch {
+        throw new Error('pagination request URL must be an absolute HTTP(S) URL without credentials');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.hash !== '') {
+        throw new Error('pagination request URL must be an absolute HTTP(S) URL without credentials');
+    }
+    return url;
+}
+function parseLinkHeader(header) {
+    const links = [];
+    let index = 0;
+    while (index < header.length) {
+        index = skipWhitespace(header, index);
+        if (header[index] !== '<')
+            return null;
+        const targetEnd = header.indexOf('>', index + 1);
+        if (targetEnd === -1)
+            return null;
+        const target = header.slice(index + 1, targetEnd);
+        if (target === '')
+            return null;
+        index = targetEnd + 1;
+        const relations = [];
+        while (true) {
+            index = skipWhitespace(header, index);
+            if (index === header.length || header[index] === ',')
+                break;
+            if (header[index] !== ';')
+                return null;
+            index = skipWhitespace(header, index + 1);
+            const name = readToken(header, index);
+            if (!name)
+                return null;
+            index = name.end;
+            index = skipWhitespace(header, index);
+            if (header[index] !== '=')
+                return null;
+            index = skipWhitespace(header, index + 1);
+            const value = readParameterValue(header, index);
+            if (!value)
+                return null;
+            index = value.end;
+            if (name.value.toLowerCase() === 'rel') {
+                relations.push(...value.value.toLowerCase().split(/\s+/).filter(Boolean));
+            }
+        }
+        links.push({ target, relations });
+        if (index === header.length)
+            return links;
+        index += 1;
+        if (index === header.length)
+            return null;
+    }
+    return null;
+}
+function skipWhitespace(value, index) {
+    while (value[index] === ' ' || value[index] === '\t')
+        index += 1;
+    return index;
+}
+function readToken(value, index) {
+    const start = index;
+    while (index < value.length && isTokenCharacter(value[index]))
+        index += 1;
+    return index === start ? null : { value: value.slice(start, index), end: index };
+}
+function isTokenCharacter(value) {
+    return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]$/.test(value);
+}
+function readParameterValue(value, index) {
+    if (value[index] !== '"')
+        return readToken(value, index);
+    let parsed = '';
+    index += 1;
+    while (index < value.length) {
+        const character = value[index];
+        if (character === '"')
+            return { value: parsed, end: index + 1 };
+        if (character === '\\') {
+            const escaped = value[index + 1];
+            if (!escaped)
+                return null;
+            parsed += escaped;
+            index += 2;
+            continue;
+        }
+        parsed += character;
+        index += 1;
+    }
+    return null;
+}

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.1",
   "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,26 @@
       "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"
+    },
+    "./http-body": {
+      "types": "./dist/http-body.d.mts",
+      "import": "./dist/http-body.mjs",
+      "default": "./dist/http-body.mjs"
+    },
+    "./http-link-pagination": {
+      "types": "./dist/http-link-pagination.d.mts",
+      "import": "./dist/http-link-pagination.mjs",
+      "default": "./dist/http-link-pagination.mjs"
     }
   },
   "publishConfig": {