@vouchington/utils 0.0.0 → 0.1.0

package/README.md

@@ -25,6 +25,18 @@ import { serializeCookie } from '@vouchington/utils/cookies'
   metadata keys and surface/sensitivity lookups.
 - `cookies`: `serializeCookie(name, value, attributes)` validates cookie grammar and requires the
   caller to supply every policy attribute. `SameSite=None` requires `Secure`.
+- `collections`, `async`, and `stable-json`: collection deduplication/merging, bounded async mapping,
+  and deterministic JSON serialization.
+- `dates`, `format`, `strings`, and `text-metrics`: UTC-day, duration, 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.
+- `observability`: SDK-free URL, request, event, and span scrubbing. 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/async.d.mts

@@ -0,0 +1,2 @@
+export declare function mapWithConcurrency<T, R>(items: readonly T[], concurrency: number, mapper: (item: T) => Promise<R>): Promise<R[]>;
+export declare function mapSerially<T, R>(items: readonly T[], mapper: (item: T) => Promise<R>): Promise<R[]>;

package/dist/async.mjs

@@ -0,0 +1,24 @@
+export async function mapWithConcurrency(items, concurrency, mapper) {
+    const count = Math.min(Math.max(1, Number.isFinite(concurrency) ? Math.floor(concurrency) : items.length), items.length);
+    const results = [];
+    let next = 0;
+    let failure;
+    async function worker() {
+        while (next < items.length) {
+            const index = next++;
+            try {
+                results[index] = await mapper(items[index]);
+            }
+            catch (error) {
+                failure ??= { reason: error };
+            }
+        }
+    }
+    await Promise.allSettled(Array.from({ length: count }, worker));
+    if (failure !== undefined)
+        throw failure.reason;
+    return results;
+}
+export function mapSerially(items, mapper) {
+    return mapWithConcurrency(items, 1, mapper);
+}

package/dist/bigint-ids.d.mts

@@ -0,0 +1,2 @@
+export declare function parsePositivePostgresBigint(value: unknown): string | null;
+export declare function parsePositivePostgresBigintParam(query: Record<string, unknown>, key: string): string | undefined;

package/dist/bigint-ids.mjs

@@ -0,0 +1,16 @@
+const MAX_POSTGRES_BIGINT = BigInt('9223372036854775807');
+export function parsePositivePostgresBigint(value) {
+    if (typeof value === 'number')
+        return Number.isSafeInteger(value) && value > 0 ? String(value) : null;
+    return typeof value === 'string' &&
+        /^[1-9]\d*$/.test(value) &&
+        value.length <= 19 &&
+        BigInt(value) <= MAX_POSTGRES_BIGINT
+        ? value
+        : null;
+}
+export function parsePositivePostgresBigintParam(query, key) {
+    return query[key] === undefined
+        ? undefined
+        : (parsePositivePostgresBigint(query[key]) ?? undefined);
+}

package/dist/collections.d.mts

@@ -0,0 +1,11 @@
+export declare function dedupeBy<T, K>(items: readonly T[], key: (item: T) => K): T[];
+export declare function dedupeByLast<T, K>(items: readonly T[], key: (item: T) => K): T[];
+export declare function dedupeById<T extends {
+    id: string;
+}>(items: readonly T[]): T[];
+export declare function mergePageResultsById<T extends {
+    id: string;
+}>(pages?: readonly ({
+    results?: readonly T[] | null;
+} | null | undefined)[] | null): T[];
+export declare function mergeRecords<T, V>(pages: readonly T[], getRecord: (page: T) => Record<string, V>): Record<string, V>;

package/dist/collections.mjs

@@ -0,0 +1,33 @@
+export function dedupeBy(items, key) {
+    const seen = new Set();
+    return items.filter((item) => {
+        const value = key(item);
+        if (seen.has(value))
+            return false;
+        seen.add(value);
+        return true;
+    });
+}
+export function dedupeByLast(items, key) {
+    return [...new Map(items.map((item) => [key(item), item])).values()];
+}
+export function dedupeById(items) {
+    return dedupeBy(items, (item) => item.id);
+}
+export function mergePageResultsById(pages) {
+    return dedupeById((pages ?? []).flatMap((page) => page?.results ?? []));
+}
+export function mergeRecords(pages, getRecord) {
+    const merged = {};
+    for (const page of pages.toReversed()) {
+        for (const [key, value] of Object.entries(getRecord(page))) {
+            Object.defineProperty(merged, key, {
+                configurable: true,
+                enumerable: true,
+                value,
+                writable: true,
+            });
+        }
+    }
+    return merged;
+}

package/dist/dates.d.mts

@@ -0,0 +1,17 @@
+export declare function getCurrentUtcDay(): string;
+export declare function getUtcDayFromDate(date: Date): string;
+export declare function enumerateUtcDaysInclusive(startDay: string, endDay: string): string[];
+export declare function getPreviousUtcDays(count: number, options?: {
+    includeToday?: boolean;
+    baseDate?: Date;
+}): string[];
+export declare function getDayBounds(day: string): {
+    startMs: number;
+    endMs: number;
+};
+export declare function parseUtcDay(day: string): {
+    year: string;
+    month: string;
+    day: string;
+};
+export declare function parseDuration(value: unknown): number | null;

package/dist/dates.mjs

@@ -0,0 +1,54 @@
+const DAY = 86_400_000;
+const UTC_DAY = /^\d{4}-\d{2}-\d{2}$/;
+export function getCurrentUtcDay() {
+    return getUtcDayFromDate(new Date());
+}
+export function getUtcDayFromDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+export function enumerateUtcDaysInclusive(startDay, endDay) {
+    const start = getDayStart(startDay);
+    const end = getDayStart(endDay);
+    const days = [];
+    for (let date = start; date <= end; date = new Date(date.getTime() + DAY))
+        days.push(getUtcDayFromDate(date));
+    return days;
+}
+export function getPreviousUtcDays(count, options) {
+    if (count <= 0)
+        return [];
+    const offset = options?.includeToday === false ? 1 : 0;
+    const date = options?.baseDate ?? new Date();
+    return Array.from({ length: count }, (_, index) => getUtcDayFromDate(new Date(date.getTime() - (index + offset) * DAY)));
+}
+export function getDayBounds(day) {
+    const startMs = getDayStart(day).getTime();
+    return { startMs, endMs: startMs + DAY };
+}
+export function parseUtcDay(day) {
+    getDayStart(day);
+    const [year, month, dayOfMonth] = day.split('-');
+    return { year: year, month: month, day: dayOfMonth };
+}
+export function parseDuration(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) && value >= 0 ? Math.floor(value) : null;
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    const parts = value.trim().split(':');
+    if (!parts.every((part) => /^\d+$/.test(part)) || parts.length > 3)
+        return null;
+    const values = parts.map(Number);
+    const duration = values.length === 1
+        ? values[0]
+        : values.length === 2
+            ? values[0] * 60 + values[1]
+            : values[0] * 3600 + values[1] * 60 + values[2];
+    return Number.isFinite(duration) ? duration : null;
+}
+function getDayStart(day) {
+    const date = new Date(`${day}T00:00:00.000Z`);
+    if (!UTC_DAY.test(day) || Number.isNaN(date.getTime()) || getUtcDayFromDate(date) !== day)
+        throw new Error(`Invalid UTC day: ${day}`);
+    return date;
+}

package/dist/format.d.mts

@@ -0,0 +1,8 @@
+export type NumberFormatLocale = string | string[];
+export declare function formatNumber(value: number, locale?: NumberFormatLocale): string;
+export declare function formatCompactNumber(value: number, locale?: NumberFormatLocale): string;
+export declare function formatUtcDate(value: string, locale?: string): string;
+export declare function generateExcerpt(markdown: string, maximumLength?: number): string;
+export declare function formatPercent(value: number): string;
+export declare function formatBytes(value: number): string;
+export declare function formatDuration(seconds: number): string;

package/dist/format.mjs

@@ -0,0 +1,68 @@
+const numbers = new Map();
+const compact = new Map();
+const dates = new Map();
+const key = (locale) => (Array.isArray(locale) ? locale.join('\0') : locale);
+export function formatNumber(value, locale = 'en') {
+    const cacheKey = key(locale);
+    const formatter = numbers.get(cacheKey) ?? new Intl.NumberFormat(locale, { maximumFractionDigits: 0 });
+    numbers.set(cacheKey, formatter);
+    return formatter.format(value);
+}
+export function formatCompactNumber(value, locale = 'en') {
+    const cacheKey = `${key(locale)}:${value >= 1_000_000_000 ? 1 : 0}`;
+    const formatter = compact.get(cacheKey) ??
+        new Intl.NumberFormat(locale, {
+            notation: 'compact',
+            maximumFractionDigits: 1,
+            minimumFractionDigits: value >= 1_000_000_000 ? 1 : 0,
+        });
+    compact.set(cacheKey, formatter);
+    return formatter.format(value);
+}
+export function formatUtcDate(value, locale = 'en-US') {
+    const formatter = dates.get(locale) ??
+        new Intl.DateTimeFormat(locale, {
+            month: 'short',
+            day: 'numeric',
+            year: 'numeric',
+            timeZone: 'UTC',
+        });
+    dates.set(locale, formatter);
+    return formatter.format(new Date(value));
+}
+export function generateExcerpt(markdown, maximumLength = 200) {
+    const text = markdown
+        .replaceAll(/#{1,6}\s+/g, '')
+        .replaceAll(/\*\*([^*]+)\*\*/g, '$1')
+        .replaceAll(/\*([^*]+)\*/g, '$1')
+        .replaceAll(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+        .replaceAll(/`([^`]+)`/g, '$1')
+        .replaceAll(/\n+/g, ' ')
+        .trim();
+    if (text.length <= maximumLength)
+        return text;
+    const truncated = text.slice(0, maximumLength);
+    const boundary = truncated.lastIndexOf(' ');
+    return `${boundary > 0 ? truncated.slice(0, boundary) : truncated}...`;
+}
+export function formatPercent(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}
+export function formatBytes(value) {
+    if (value < 1024)
+        return `${value} B`;
+    if (value < 1024 ** 2)
+        return `${(value / 1024).toFixed(1)} KB`;
+    if (value < 1024 ** 3)
+        return `${(value / 1024 ** 2).toFixed(1)} MB`;
+    return `${(value / 1024 ** 3).toFixed(2)} GB`;
+}
+export function formatDuration(seconds) {
+    const total = Math.floor(seconds);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const remainder = total % 60;
+    return hours > 0
+        ? `${hours}:${String(minutes).padStart(2, '0')}:${String(remainder).padStart(2, '0')}`
+        : `${String(minutes).padStart(2, '0')}:${String(remainder).padStart(2, '0')}`;
+}

package/dist/gtin.d.mts

@@ -0,0 +1,2 @@
+export declare function isValidGtinFormat(value: string): boolean;
+export declare function isValidGtinCheckDigit(value: string): boolean;

package/dist/gtin.mjs

@@ -0,0 +1,13 @@
+const FORMAT = /^\d{8}$|^\d{12}$|^\d{13}$|^\d{14}$/;
+export function isValidGtinFormat(value) {
+    return FORMAT.test(value);
+}
+export function isValidGtinCheckDigit(value) {
+    if (!isValidGtinFormat(value))
+        return false;
+    const digits = value.padStart(14, '0').split('').map(Number);
+    const total = digits
+        .slice(0, 13)
+        .reduce((sum, digit, index) => sum + digit * (index % 2 === 0 ? 3 : 1), 0);
+    return (10 - (total % 10)) % 10 === digits[13];
+}

package/dist/observability.d.mts

@@ -0,0 +1,18 @@
+export declare const SENSITIVE_VALUE = "[Filtered]";
+export interface ScrubOptions {
+    credentialHeaders: readonly string[];
+}
+export interface ObservableEvent {
+    [key: string]: unknown;
+    breadcrumbs?: Array<{
+        data?: Record<string, unknown>;
+    }>;
+    request?: object;
+}
+export declare function stripUrlQueryAndFragment(value: string): string;
+export declare function scrubHeaders(headers: Record<string, unknown>, credentialHeaders: readonly string[]): Record<string, unknown>;
+export declare function scrubSpanAttributes<T extends Record<string, unknown>>(data: T, options: ScrubOptions): T;
+export declare function scrubEvent<T extends ObservableEvent>(event: T, options: ScrubOptions): T;
+export declare function composeBeforeSend<T extends ObservableEvent, THint>(beforeSend: ((event: T, hint: THint) => T | null | Promise<T | null>) | undefined, options: ScrubOptions): (event: T, hint: THint) => T | null | Promise<T | null>;
+export declare function isAllowedEnvironment(value: string | undefined, allowed: readonly string[]): boolean;
+export declare function shouldReportSpike(count: number, threshold: number): boolean;

package/dist/observability.mjs

@@ -0,0 +1,120 @@
+export const SENSITIVE_VALUE = '[Filtered]';
+const URL_ATTRIBUTES = [
+    'url',
+    'url.full',
+    'http.url',
+    'http.target',
+    'http.request.header.referer',
+    'http.request.header.referrer',
+];
+const URL_COMPONENT_ATTRIBUTES = ['url.query', 'http.query', 'url.fragment', 'http.fragment'];
+export function stripUrlQueryAndFragment(value) {
+    const match = /[?#]/.exec(value);
+    return match ? value.slice(0, match.index) : value;
+}
+export function scrubHeaders(headers, credentialHeaders) {
+    const credentials = new Set(credentialHeaders.map((name) => name.toLowerCase()));
+    return Object.fromEntries(Object.entries(headers).map(([name, value]) => [
+        name,
+        credentials.has(name.toLowerCase())
+            ? SENSITIVE_VALUE
+            : isUrlHeader(name)
+                ? scrubUrlHeaderValue(value)
+                : value,
+    ]));
+}
+export function scrubSpanAttributes(data, options) {
+    const credentialKeys = new Set(options.credentialHeaders.flatMap((name) => {
+        const lower = name.toLowerCase();
+        return [`http.request.header.${lower}`, `http.request.header.${lower.replaceAll('-', '_')}`];
+    }));
+    const result = Object.entries(data).flatMap(([key, value]) => {
+        if (URL_COMPONENT_ATTRIBUTES.includes(key))
+            return [];
+        if (credentialKeys.has(key) || key.startsWith('http.request.header.cookie.'))
+            return [[key, SENSITIVE_VALUE]];
+        return [
+            [
+                key,
+                URL_ATTRIBUTES.includes(key) && typeof value === 'string'
+                    ? stripUrlQueryAndFragment(value)
+                    : value,
+            ],
+        ];
+    });
+    const changed = result.length !== Object.keys(data).length || result.some(([key, value]) => data[key] !== value);
+    return (changed ? Object.fromEntries(result) : data);
+}
+export function scrubEvent(event, options) {
+    const request = scrubRequest(event.request, options);
+    const breadcrumbs = event.breadcrumbs?.map((breadcrumb) => breadcrumb.data
+        ? { ...breadcrumb, data: scrubSpanAttributes(breadcrumb.data, options) }
+        : breadcrumb);
+    const changed = request !== event.request ||
+        breadcrumbs?.some((breadcrumb, index) => breadcrumb !== event.breadcrumbs?.[index]);
+    return changed
+        ? {
+            ...event,
+            ...(request === event.request ? {} : { request }),
+            ...(breadcrumbs === event.breadcrumbs ? {} : { breadcrumbs }),
+        }
+        : event;
+}
+export function composeBeforeSend(beforeSend, options) {
+    return (event, hint) => {
+        const result = beforeSend ? beforeSend(event, hint) : event;
+        if (isPromiseLike(result))
+            return Promise.resolve(result).then((next) => next === null ? null : scrubEvent(next, options));
+        return result === null ? null : scrubEvent(result, options);
+    };
+}
+function isPromiseLike(value) {
+    return value !== null && typeof value.then === 'function';
+}
+export function isAllowedEnvironment(value, allowed) {
+    return value !== undefined && allowed.includes(value);
+}
+export function shouldReportSpike(count, threshold) {
+    return Number.isFinite(count) && Number.isFinite(threshold) && count >= threshold;
+}
+function scrubRequest(request, options) {
+    if (!request)
+        return request;
+    const fields = request;
+    const headers = isRecord(fields.headers)
+        ? scrubHeaders(fields.headers, options.credentialHeaders)
+        : fields.headers;
+    const cookies = isRecord(fields.cookies)
+        ? Object.fromEntries(Object.keys(fields.cookies).map((name) => [name, SENSITIVE_VALUE]))
+        : fields.cookies;
+    const result = Object.entries(fields).flatMap(([key, value]) => key === 'query_string'
+        ? []
+        : [
+            [
+                key,
+                key === 'url' && typeof value === 'string'
+                    ? stripUrlQueryAndFragment(value)
+                    : key === 'headers'
+                        ? headers
+                        : key === 'cookies'
+                            ? cookies
+                            : value,
+            ],
+        ]);
+    const changed = result.length !== Object.keys(fields).length ||
+        result.some(([key, value]) => fields[key] !== value);
+    return (changed ? Object.fromEntries(result) : request);
+}
+function isUrlHeader(name) {
+    return ['referer', 'referrer'].includes(name.toLowerCase());
+}
+function scrubUrlHeaderValue(value) {
+    if (typeof value === 'string')
+        return stripUrlQueryAndFragment(value);
+    return Array.isArray(value)
+        ? value.map((item) => (typeof item === 'string' ? stripUrlQueryAndFragment(item) : item))
+        : value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/query-string.d.mts

@@ -0,0 +1 @@
+export declare function buildQueryString(params: Record<string, unknown>): string;

package/dist/query-string.mjs

@@ -0,0 +1,11 @@
+export function buildQueryString(params) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value == null)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value])
+            query.append(key, String(item));
+    }
+    const serialized = query.toString();
+    return serialized ? `?${serialized}` : '';
+}

package/dist/query.d.mts

@@ -0,0 +1,9 @@
+export declare function parseStringArray(value: unknown): string[];
+export declare function parseBooleanish(value: unknown): boolean;
+export declare function parseNumberParam(query: Record<string, unknown>, key: string): number | undefined;
+export declare function parseNumberParams(query: Record<string, unknown>, keys: readonly string[]): Record<string, number>;
+export declare function parseBoundedInteger(value: unknown, bounds: {
+    default: number;
+    minimum: number;
+    maximum: number;
+}): number;

package/dist/query.mjs

@@ -0,0 +1,48 @@
+export function parseStringArray(value) {
+    const values = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [];
+    return values.flatMap((item) => {
+        const normalized = String(item).trim();
+        return normalized ? [normalized] : [];
+    });
+}
+export function parseBooleanish(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return value !== 0;
+    return typeof value === 'string' && ['1', 'true'].includes(value.toLowerCase());
+}
+export function parseNumberParam(query, key) {
+    const input = query[key];
+    if (input === undefined || input === null || (typeof input === 'string' && input.trim() === '')) {
+        return undefined;
+    }
+    const value = Number(input);
+    return Number.isNaN(value) ? undefined : value;
+}
+export function parseNumberParams(query, keys) {
+    return Object.fromEntries(keys.flatMap((key) => {
+        const value = parseNumberParam(query, key);
+        return value === undefined ? [] : [[key, value]];
+    }));
+}
+export function parseBoundedInteger(value, bounds) {
+    if (!Number.isSafeInteger(bounds.default) ||
+        !Number.isSafeInteger(bounds.minimum) ||
+        !Number.isSafeInteger(bounds.maximum) ||
+        bounds.minimum > bounds.maximum ||
+        bounds.default < bounds.minimum ||
+        bounds.default > bounds.maximum)
+        throw new RangeError('Invalid integer bounds');
+    if (value === undefined || value === null || value === '')
+        return bounds.default;
+    const text = typeof value === 'number' ? String(value) : typeof value === 'string' ? value : '';
+    if (!/^-?\d+$/.test(text))
+        throw new TypeError('Expected a canonical integer');
+    const parsed = Number(text);
+    if (!Number.isSafeInteger(parsed))
+        throw new TypeError('Expected a safe integer');
+    if (parsed < bounds.minimum || parsed > bounds.maximum)
+        throw new RangeError(`Expected an integer between ${bounds.minimum} and ${bounds.maximum}`);
+    return parsed;
+}

package/dist/slugs.d.mts

@@ -0,0 +1 @@
+export declare function slugifyAscii(value: string): string;

package/dist/slugs.mjs

@@ -0,0 +1,9 @@
+export function slugifyAscii(value) {
+    return value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}

package/dist/stable-json.d.mts

@@ -0,0 +1 @@
+export declare function stableJsonStringify(value: unknown): string;

package/dist/stable-json.mjs

@@ -0,0 +1,51 @@
+export function stableJsonStringify(value) {
+    return `${format(sort(value))}\n`;
+}
+function sort(value) {
+    if (hasToJson(value))
+        return sort(value.toJSON());
+    if (Array.isArray(value)) {
+        return Array.from(value, (item) => item === undefined || typeof item === 'function' || typeof item === 'symbol'
+            ? null
+            : sort(item));
+    }
+    if (value === undefined || typeof value === 'function' || typeof value === 'symbol')
+        return null;
+    if (value == null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, nested]) => nested !== undefined && typeof nested !== 'function' && typeof nested !== 'symbol')
+        .toSorted(([left], [right]) => (left < right ? -1 : 1))
+        .map(([key, nested]) => [key, sort(nested)]));
+}
+function hasToJson(value) {
+    return (value != null &&
+        typeof value === 'object' &&
+        typeof value.toJSON === 'function');
+}
+function format(value, indent = 0, prefix = 0) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        const canInline = value.every((item) => item == null || ['boolean', 'number', 'string'].includes(typeof item));
+        if (canInline) {
+            const inline = `[${value.map((item) => JSON.stringify(item)).join(', ')}]`;
+            if (inline.length <= 100 - indent - prefix)
+                return inline;
+        }
+        const child = ' '.repeat(indent + 2);
+        return `[\n${value.map((item) => `${child}${format(item, indent + 2)}`).join(',\n')}\n${' '.repeat(indent)}]`;
+    }
+    if (value == null || typeof value !== 'object')
+        return JSON.stringify(value);
+    const entries = Object.entries(value);
+    if (!entries.length)
+        return '{}';
+    const child = ' '.repeat(indent + 2);
+    return `{\n${entries
+        .map(([key, nested]) => {
+        const serialized = JSON.stringify(key);
+        return `${child}${serialized}: ${format(nested, indent + 2, serialized.length + 2)}`;
+    })
+        .join(',\n')}\n${' '.repeat(indent)}}`;
+}

package/dist/strings.d.mts

@@ -0,0 +1,3 @@
+export declare function toTitleCase(value: string): string;
+export declare function normalizeKey(value: string): string;
+export declare function stripControlCharacters(value: string): string;

package/dist/strings.mjs

@@ -0,0 +1,53 @@
+const LOWERCASE = new Set([
+    'a',
+    'an',
+    'the',
+    'and',
+    'but',
+    'or',
+    'nor',
+    'for',
+    'yet',
+    'so',
+    'at',
+    'by',
+    'in',
+    'of',
+    'on',
+    'to',
+    'up',
+    'as',
+    'is',
+    'if',
+    'it',
+    'via',
+    'vs',
+    'with',
+    'from',
+    'into',
+    'over',
+    'upon',
+    'than',
+    'that',
+    'then',
+]);
+export function toTitleCase(value) {
+    const words = value.split(/\s+/);
+    return words
+        .map((word, index) => {
+        if (word.length <= 4 && word === word.toUpperCase())
+            return word;
+        const lower = word.toLowerCase();
+        if (index > 0 && index < words.length - 1 && LOWERCASE.has(lower))
+            return lower;
+        return `${word.charAt(0).toUpperCase()}${lower.slice(1)}`;
+    })
+        .join(' ');
+}
+export function normalizeKey(value) {
+    return value.trim().toLowerCase();
+}
+export function stripControlCharacters(value) {
+    // oxlint-disable-next-line no-control-regex -- this explicitly filters unsupported C0 controls and DEL.
+    return value.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+}

package/dist/text-metrics.d.mts

@@ -0,0 +1,2 @@
+export declare function countWords(value: string): number;
+export declare function countSentences(value: string): number;

package/dist/text-metrics.mjs

@@ -0,0 +1,6 @@
+export function countWords(value) {
+    return value.trim().split(/\s+/).filter(Boolean).length;
+}
+export function countSentences(value) {
+    return value.split(/[.!?]+["')}\]]*(?:\s|$)/).filter((sentence) => sentence.trim()).length;
+}

package/dist/urls.d.mts

@@ -0,0 +1,9 @@
+export declare function extractUrlScheme(value: string): string | null;
+export declare function sanitizeLinkUrl(value: string | null | undefined): string | null;
+export declare function sanitizeImageUrl(value: string | null | undefined): string | null;
+export declare function isExternalHttpUrl(value: string | null | undefined): boolean;
+export declare function isAsciiHostname(value: string): boolean;
+export declare function normalizeAsciiHostname(value: string): string | null;
+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

@@ -0,0 +1,93 @@
+const SCHEME = /^([a-z][a-z0-9+.-]*):/i;
+const LINK_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
+const IMAGE_SCHEMES = new Set(['http', 'https']);
+export function extractUrlScheme(value) {
+    return value.match(SCHEME)?.[1]?.toLowerCase() ?? null;
+}
+function sanitize(value, allowed) {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    // oxlint-disable-next-line no-control-regex -- reject URL-parser-normalized C0/DEL bypasses.
+    if (!normalized || /[\u0000-\u001F\u007F]/.test(normalized))
+        return null;
+    const scheme = extractUrlScheme(normalized);
+    if (!scheme && normalized.startsWith('//'))
+        return null;
+    return !scheme || allowed.has(scheme) ? normalized : null;
+}
+export function sanitizeLinkUrl(value) {
+    return sanitize(value, LINK_SCHEMES);
+}
+export function sanitizeImageUrl(value) {
+    return sanitize(value, IMAGE_SCHEMES);
+}
+export function isExternalHttpUrl(value) {
+    const sanitized = sanitizeLinkUrl(value);
+    const scheme = sanitized ? extractUrlScheme(sanitized) : null;
+    return scheme === 'http' || scheme === 'https';
+}
+export function isAsciiHostname(value) {
+    return (Boolean(value) &&
+        value.length <= 255 &&
+        value.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label)));
+}
+export function normalizeAsciiHostname(value) {
+    const input = value
+        .trim()
+        .replace(/^(https?):\/+|^(https?):/i, (_match, first, second) => `${first ?? second}://`);
+    if (!input)
+        return null;
+    try {
+        const candidate = /^[a-z][a-z0-9+.-]*:\/\//i.test(input) ? input : `https://${input}`;
+        const authority = candidate.match(/^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i)?.[1];
+        // oxlint-disable-next-line no-control-regex -- validate the authority before URL punycode conversion.
+        if (!authority || /[^\x00-\x7F]/.test(authority))
+            return null;
+        const url = new URL(candidate);
+        const hostname = url.hostname.toLowerCase().replace(/\.$/, '');
+        return !url.username && !url.password && hostname.length <= 255 && isAsciiHostname(hostname)
+            ? hostname
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function extractUrlHostname(value) {
+    try {
+        return new URL(value).hostname || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function getFirstPathSegment(pathname) {
+    if (pathname === '/')
+        return null;
+    const index = pathname.indexOf('/', 1);
+    return index < 0 ? '/' : pathname.slice(0, index);
+}
+export function matchesPathnamePattern(pathname, pattern) {
+    let pathIndex = 0;
+    let patternIndex = 0;
+    let wildcardPathIndex = -1;
+    let wildcardPatternIndex = -1;
+    while (pathIndex < pathname.length) {
+        if (pattern[patternIndex] === '%') {
+            wildcardPatternIndex = patternIndex++;
+            wildcardPathIndex = pathIndex;
+        }
+        else if (pattern[patternIndex] === '_' || pattern[patternIndex] === pathname[pathIndex]) {
+            pathIndex++;
+            patternIndex++;
+        }
+        else if (wildcardPatternIndex >= 0) {
+            patternIndex = wildcardPatternIndex + 1;
+            pathIndex = ++wildcardPathIndex;
+        }
+        else
+            return false;
+    }
+    while (pattern[patternIndex] === '%')
+        patternIndex++;
+    return patternIndex === pattern.length;
+}

package/dist/validation.d.mts

@@ -0,0 +1,2 @@
+export declare function isEmailAddress(value: string): boolean;
+export declare function isUuid(value: string): boolean;

package/dist/validation.mjs

@@ -0,0 +1,7 @@
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isEmailAddress(value) {
+    return Boolean(value) && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+export function isUuid(value) {
+    return UUID.test(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -54,6 +54,81 @@
       "types": "./dist/cookies.d.mts",
       "import": "./dist/cookies.mjs",
       "default": "./dist/cookies.mjs"
+    },
+    "./collections": {
+      "types": "./dist/collections.d.mts",
+      "import": "./dist/collections.mjs",
+      "default": "./dist/collections.mjs"
+    },
+    "./dates": {
+      "types": "./dist/dates.d.mts",
+      "import": "./dist/dates.mjs",
+      "default": "./dist/dates.mjs"
+    },
+    "./format": {
+      "types": "./dist/format.d.mts",
+      "import": "./dist/format.mjs",
+      "default": "./dist/format.mjs"
+    },
+    "./gtin": {
+      "types": "./dist/gtin.d.mts",
+      "import": "./dist/gtin.mjs",
+      "default": "./dist/gtin.mjs"
+    },
+    "./bigint-ids": {
+      "types": "./dist/bigint-ids.d.mts",
+      "import": "./dist/bigint-ids.mjs",
+      "default": "./dist/bigint-ids.mjs"
+    },
+    "./query": {
+      "types": "./dist/query.d.mts",
+      "import": "./dist/query.mjs",
+      "default": "./dist/query.mjs"
+    },
+    "./query-string": {
+      "types": "./dist/query-string.d.mts",
+      "import": "./dist/query-string.mjs",
+      "default": "./dist/query-string.mjs"
+    },
+    "./slugs": {
+      "types": "./dist/slugs.d.mts",
+      "import": "./dist/slugs.mjs",
+      "default": "./dist/slugs.mjs"
+    },
+    "./strings": {
+      "types": "./dist/strings.d.mts",
+      "import": "./dist/strings.mjs",
+      "default": "./dist/strings.mjs"
+    },
+    "./text-metrics": {
+      "types": "./dist/text-metrics.d.mts",
+      "import": "./dist/text-metrics.mjs",
+      "default": "./dist/text-metrics.mjs"
+    },
+    "./urls": {
+      "types": "./dist/urls.d.mts",
+      "import": "./dist/urls.mjs",
+      "default": "./dist/urls.mjs"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.mts",
+      "import": "./dist/validation.mjs",
+      "default": "./dist/validation.mjs"
+    },
+    "./async": {
+      "types": "./dist/async.d.mts",
+      "import": "./dist/async.mjs",
+      "default": "./dist/async.mjs"
+    },
+    "./stable-json": {
+      "types": "./dist/stable-json.d.mts",
+      "import": "./dist/stable-json.mjs",
+      "default": "./dist/stable-json.mjs"
+    },
+    "./observability": {
+      "types": "./dist/observability.d.mts",
+      "import": "./dist/observability.mjs",
+      "default": "./dist/observability.mjs"
     }
   },
   "publishConfig": {