hanzio 1.2.0 → 2.0.0

package/dist/cache/createCache.d.ts

@@ -0,0 +1,31 @@
+export type CacheSetOptions<T = unknown> = {
+    /** Lifetime of the entry; a function derives it from the value (e.g. a token's `expires_in`). */
+    ttlMs?: number | ((value: T) => number);
+    /** getOrSet recomputes this long before expiry; get still returns the entry until it expires. */
+    staleMarginMs?: number;
+};
+export type CreateCacheOptions = {
+    /** TTL used when a call doesn't pass `ttlMs` (default: no expiry). */
+    defaultTtlMs?: number;
+    /** `staleMarginMs` used when a call doesn't pass one (default: 0). */
+    staleMarginMs?: number;
+    /** Evicts the least recently used entry beyond this size (default: unbounded). */
+    maxEntries?: number;
+    /** Clock, for tests (default: `Date.now`). */
+    now?: () => number;
+};
+export type KeyValueCache = {
+    /**
+     * Get-or-compute. Concurrent callers share one in-flight call; rejections
+     * aren't cached (a stale value stays readable until it expires).
+     */
+    getOrSet<T>(key: string, fn: () => Promise<T> | T, options?: CacheSetOptions<T>): Promise<T>;
+    get<T>(key: string): T | undefined;
+    has(key: string): boolean;
+    set<T>(key: string, value: T, options?: CacheSetOptions<T>): void;
+    delete(key: string): void;
+    clear(): void;
+    readonly size: number;
+};
+/** A small in-memory key/value cache with TTL, LRU bound and in-flight dedupe. */
+export declare function createCache(options?: CreateCacheOptions): KeyValueCache;

package/dist/cache/index.d.ts

@@ -1,7 +1,16 @@
 type AnyFunction = (...args: never[]) => unknown;
-type CachedFunction<T extends AnyFunction> = {
+type CachedFunction<T extends AnyFunction, TPeek = Awaited<ReturnType<T>> | undefined> = {
     (...args: Parameters<T>): ReturnType<T>;
     clearCache: () => void;
+    /** Drops the entry (and any in-flight call) for these arguments. */
+    invalidate: (...args: Parameters<T>) => void;
+    /**
+     * What a call would return from the cache right now (including a stale
+     * value with refreshInBackground), without calling fn, starting a refresh
+     * or counting as a use for maxEntries. `undefined` on a miss. With a
+     * `store` this reads the store and returns a Promise.
+     */
+    peek: (...args: Parameters<T>) => TPeek;
 };
 export type CacheStoreEntry = {
     value: unknown;
@@ -40,6 +49,14 @@ export type CacheFunctionOptions<T extends AnyFunction> = {
     onStoreError?: (error: unknown, context: {
         name: string;
     }) => void;
+    /**
+     * Evicts the least recently used entry beyond this many entries (default:
+     * unbounded). Applies to the in-memory cache only.
+     */
+    maxEntries?: number;
 };
+export declare function cacheFunction<T extends AnyFunction>(options: CacheFunctionOptions<T> & {
+    store: CacheStore;
+}): CachedFunction<T, Promise<Awaited<ReturnType<T>> | undefined>>;
 export declare function cacheFunction<T extends AnyFunction>(options: CacheFunctionOptions<T>): CachedFunction<T>;
-export {};
+export * from './createCache';

package/dist/color/contrast.d.ts

@@ -0,0 +1,40 @@
+/** An sRGB color: `r`/`g`/`b` in 0..255, `a` in 0..1. */
+export type Rgba = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/**
+ * Splits `rgb(…)`/`rgba(…)`/`hsl(…)`/`hsla(…)` (comma, space or slash syntax)
+ * into its name and 3-4 raw arguments. Internal; shared with `withAlpha`.
+ */
+export declare function colorFunctionArgs(color: string): {
+    name: 'rgb' | 'hsl';
+    args: string[];
+} | undefined;
+/**
+ * Parse `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`/`rgba()` and
+ * `hsl()`/`hsla()` (comma or space/slash syntax, percentages allowed).
+ * Returns `undefined` for anything else (named colors, CSS variables, …).
+ */
+export declare function parseColor(color: string): Rgba | undefined;
+/** `#rrggbb` (or `#rrggbbaa` with `alpha: true`). Throws on unparseable strings. */
+export declare function toHex(color: Rgba | string, options?: {
+    alpha?: boolean;
+}): string;
+/** `rgb(r, g, b)`, or `rgba(r, g, b, a)` when translucent. Throws on unparseable strings. */
+export declare function toRgbString(color: Rgba | string): string;
+/** WCAG 2.x relative luminance (0 = black, 1 = white); alpha is ignored. */
+export declare function relativeLuminance(color: Rgba | string): number;
+/** WCAG contrast ratio between two colors, from 1 to 21. */
+export declare function contrastRatio(a: Rgba | string, b: Rgba | string): number;
+/** Whichever of `light`/`dark` contrasts more with `background` (ties go to `light`). */
+export declare function contrastText(background: Rgba | string, options?: {
+    light?: string;
+    dark?: string;
+}): string;
+/** Blend `b` into `a` by `weight` (0 = `a`, 1 = `b`) as hex; alpha kept only when translucent. */
+export declare function mixColors(a: Rgba | string, b: Rgba | string, weight: number): string;
+/** Darken toward black (`amount` < 0) or lighten toward white (> 0); `amount` in -1..1. Returns hex. */
+export declare function shade(color: Rgba | string, amount: number): string;

package/dist/color/index.d.ts

@@ -0,0 +1,2 @@
+export { contrastRatio, contrastText, mixColors, parseColor, type Rgba, relativeLuminance, shade, toHex, toRgbString } from './contrast';
+export { createResolveColorsByKeys, getHeatmapCellStyle, hashStringToColorIndex, METRICS_SERIES_PALETTE_SIZE, pickFromPalette, type ResolveColorsByKeysResult, resolveSeriesColorMap, seriesColorKey, withAlpha } from './metricsSeriesColors';

package/dist/{math → color}/metricsSeriesColors.d.ts

@@ -1,13 +1,15 @@
 /**
- * Shared metrics chart series color assignment for web (CSS tokens) and Expo (hex palette).
- * Same hash + collision strategy so labels map to the same slot index everywhere.
+ * Stable series color assignment: the same hash + collision strategy maps a
+ * label to the same palette slot index on every platform.
  */
-/** Matches PrimeVue semantic palette slot count (cyan…blue) and Expo SERIES_COLORS length */
+/** Default palette slot count. */
 export declare const METRICS_SERIES_PALETTE_SIZE = 10;
 /**
  * FNV-1a 32-bit hash — stable palette index for a string key.
  */
-export declare function hashStringToColorIndex(str: string): number;
+export declare function hashStringToColorIndex(str: string, paletteSize?: number): number;
+/** Stable pick from `palette` for `seed` (same seed → same item). Throws on an empty palette. */
+export declare function pickFromPalette<T>(seed: string, palette: readonly T[]): T;
 /**
  * Prefer human-visible label so charts and tables agree on the same color key.
  */
@@ -15,7 +17,7 @@ export declare function seriesColorKey(label: string | undefined, key: string):
 /**
  * Map each distinct key to a palette index (hash preference, then max-min circular spacing).
  */
-export declare function resolveSeriesColorMap(keys: string[]): Map<string, number>;
+export declare function resolveSeriesColorMap(keys: string[], paletteSize?: number): Map<string, number>;
 export type ResolveColorsByKeysResult = {
     getColor: (key: string) => string;
     getHoverColor: (key: string) => string;
@@ -23,9 +25,14 @@ export type ResolveColorsByKeysResult = {
 /**
  * Resolve stable colors per key using palette index → RGB/CSS from the caller.
  */
-export declare function createResolveColorsByKeys(keys: string[], getSeriesColor: (index: number) => string, getSeriesHoverColor: (index: number) => string): ResolveColorsByKeysResult;
+export declare function createResolveColorsByKeys(keys: string[], getSeriesColor: (index: number) => string, getSeriesHoverColor: (index: number) => string, paletteSize?: number): ResolveColorsByKeysResult;
 /**
- * Add alpha to hex, rgb(), or rgba() strings.
+ * Apply `alpha` (0..1) to a color, replacing any existing alpha.
+ *
+ * - `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` → `rgba(r, g, b, a)` (works in React Native)
+ * - `rgb()`/`rgba()`/`hsl()`/`hsla()`, comma or space syntax → `rgba(…)` / `hsla(…)`
+ * - anything else (CSS variables, named colors, `oklch()`, …) →
+ *   `color-mix(in srgb, <color> <alpha*100>%, transparent)` (web only)
  */
 export declare function withAlpha(color: string, alpha: number): string;
 /**

package/dist/cool-console-log/index.d.ts

@@ -31,10 +31,16 @@ export declare const terminalColors: {
     readonly bgWhite: "\u001B[47m";
 };
 export type TerminalColor = keyof typeof terminalColors;
+/**
+ * Whether stdout should get ANSI colors: `NO_COLOR` disables, `FORCE_COLOR`
+ * (other than `'0'`) enables, otherwise only when stdout is a TTY.
+ * Always false where `process` doesn't exist (browsers, Workers).
+ */
+export declare function supportsColor(): boolean;
 /** Log levels supported by the logger */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-/** Attributes that can be passed to log methods */
-export type LogAttributes = Record<string, string | number | boolean>;
+/** Attributes that can be passed to log methods. Objects are rendered as compact JSON. */
+export type LogAttributes = Record<string, unknown>;
 /** Log method signature */
 export type LogMethod = (message: string, attributes?: LogAttributes) => void;
 /** Logger interface with colored output */
@@ -43,14 +49,18 @@ export type CoolLogger = {
     info: LogMethod;
     warn: LogMethod;
     error: LogMethod;
+    /** Returns a logger that adds `attributes` to every entry (call-site attributes win). */
+    child: (attributes: LogAttributes) => CoolLogger;
 };
 /**
  * Options for creating a cool logger
  */
 export type CoolLoggerOptions = {
-    /** Only use colors in development (default: true) */
+    /** Only use colors in development (default: true). Colors also require `supportsColor()`. */
     colorsInDevOnly?: boolean;
-    /** Callback for each log entry (e.g., to add to OpenTelemetry span) */
+    /** Lowest level that is printed (default: 'debug' in dev, 'info' in production) */
+    minLevel?: LogLevel;
+    /** Callback for each log entry, before level filtering (e.g., to add to OpenTelemetry span) */
     onLog?: (level: LogLevel, message: string, attributes?: LogAttributes) => void;
 };
 /**
@@ -62,6 +72,7 @@ export type CoolLoggerOptions = {
  * logger.info('User logged in', { userId: '123' })
  * logger.warn('Rate limit approaching', { remaining: 10 })
  * logger.error('Payment failed', { reason: 'insufficient_funds' })
+ * const requestLog = logger.child({ requestId: 'abc' })
  * ```
  */
 export declare function createCoolLogger(options?: CoolLoggerOptions): CoolLogger;
@@ -85,7 +96,25 @@ export declare function logOperationSummary(operationName: string, durationMs: n
     error?: Error | unknown;
 }): void;
 /**
- * Helper to colorize text for console output
+ * Starts timing an operation. Call the returned `done` to log it via `logOperationSummary`.
+ *
+ * @example
+ * ```ts
+ * const done = startOperation('user.create')
+ * try {
+ *   await doSomething()
+ *   done()
+ * } catch (error) {
+ *   done(false, error)
+ * }
+ * ```
+ */
+export declare function startOperation(operationName: string, options?: {
+    devOnly?: boolean;
+}): (success?: boolean, error?: unknown) => void;
+/**
+ * Helper to colorize text for console output. Returns `text` unchanged in
+ * production or when colors aren't supported (see `supportsColor`).
  *
  * @example
  * ```ts

package/dist/crypto/encoding.d.ts

@@ -0,0 +1,18 @@
+export type BytesLike = Uint8Array | ArrayBuffer;
+export declare function utf8Encode(value: string): Uint8Array<ArrayBuffer>;
+/** Invalid UTF-8 sequences become U+FFFD (same as `TextDecoder` / `Buffer#toString`). */
+export declare function utf8Decode(bytes: BytesLike): string;
+/** Standard base64 with `=` padding. */
+export declare function encodeBase64(bytes: BytesLike): string;
+/** Decodes standard base64 (padding optional). Throws `TypeError` on invalid input. */
+export declare function decodeBase64(value: string): Uint8Array<ArrayBuffer>;
+/** URL-safe base64 without padding (RFC 4648 §5). */
+export declare function encodeBase64Url(bytes: BytesLike): string;
+/** Decodes URL-safe base64 (padding optional). Throws `TypeError` on invalid input. */
+export declare function decodeBase64Url(value: string): Uint8Array<ArrayBuffer>;
+/** Lowercase hex. */
+export declare function bytesToHex(bytes: BytesLike): string;
+/** Decodes hex (either case). Throws `TypeError` on odd length or non-hex characters. */
+export declare function hexToBytes(value: string): Uint8Array<ArrayBuffer>;
+/** UTF-8 for strings; a copy for bytes, so Web Crypto always gets an `ArrayBuffer`-backed view. */
+export declare function toBytes(data: string | BytesLike): Uint8Array<ArrayBuffer>;

package/dist/crypto/hash.d.ts

@@ -0,0 +1,33 @@
+import { type BytesLike } from './encoding';
+export type HmacAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
+export type SignatureEncoding = 'hex' | 'base64' | 'base64url';
+export type HmacSignOptions = {
+    /** Default: `'SHA-256'` */
+    algorithm?: HmacAlgorithm;
+    /** Default: `'hex'` */
+    encoding?: SignatureEncoding;
+};
+export type HmacVerifyOptions = HmacSignOptions & {
+    /** Required prefix stripped before decoding, e.g. `'sha256='`. Missing prefix → `false`. */
+    prefix?: string;
+};
+/**
+ * Constant-time equality for strings (compared as UTF-8) or bytes. Runs over the
+ * longer input, so timing reveals at most the lengths, never where they differ.
+ */
+export declare function safeEqual(a: string | Uint8Array, b: string | Uint8Array): boolean;
+/** Cryptographically secure random bytes. */
+export declare function randomBytes(byteLength: number): Uint8Array<ArrayBuffer>;
+/** Random base64url token. 32 bytes → 43 characters, 256 bits of entropy. */
+export declare function randomToken(byteLength?: number): string;
+export declare function sha256(data: string | BytesLike): Promise<Uint8Array>;
+export declare function sha256Hex(data: string | BytesLike): Promise<string>;
+export declare function hmacSign(secret: string | BytesLike, data: string | BytesLike, options?: HmacSignOptions): Promise<string>;
+/**
+ * Checks `signature` against the HMAC of `data` using Web Crypto's `verify`
+ * (constant-time). Malformed or wrongly-prefixed signatures return `false`;
+ * configuration problems (empty secret, unknown algorithm) throw.
+ */
+export declare function verifyHmacSignature(secret: string | BytesLike, data: string | BytesLike, signature: string, options?: HmacVerifyOptions): Promise<boolean>;
+/** @internal */
+export declare function getSubtleCrypto(): SubtleCrypto;

package/dist/crypto/index.d.ts

@@ -0,0 +1,4 @@
+export { type BytesLike, bytesToHex, decodeBase64, decodeBase64Url, encodeBase64, encodeBase64Url, hexToBytes, utf8Decode, utf8Encode } from './encoding';
+export { type HmacAlgorithm, type HmacSignOptions, type HmacVerifyOptions, hmacSign, randomBytes, randomToken, type SignatureEncoding, safeEqual, sha256, sha256Hex, verifyHmacSignature } from './hash';
+export * from './sealer';
+export * from './webhook';

package/dist/crypto/sealer.d.ts

@@ -0,0 +1,25 @@
+import { type BytesLike } from './encoding';
+export type SealerOptions = {
+    /** High-entropy secret (e.g. `APP_SECRET`). The AES key is derived from it with HKDF-SHA-256. */
+    secret: string | BytesLike;
+    /** HKDF salt. Default: empty */
+    salt?: string;
+    /** HKDF info; use a distinct value per purpose. Default: `'hanzio.sealer.aes-256-gcm.v1'` */
+    info?: string;
+};
+export type Sealer = {
+    seal(plaintext: string): Promise<string>;
+    open(sealed: string): Promise<string>;
+    sealJson(value: unknown): Promise<string>;
+    openJson<T = unknown>(sealed: string): Promise<T>;
+};
+export type SealerErrorCode = 'malformed' | 'unsupported_version' | 'decrypt_failed';
+export declare class SealerError extends Error {
+    readonly code: SealerErrorCode;
+    constructor(code: SealerErrorCode);
+}
+/**
+ * AES-256-GCM sealing with a random 96-bit IV per value. Envelope:
+ * `enc:v1:<b64url(iv)>.<b64url(tag)>.<b64url(ciphertext)>`.
+ */
+export declare function createSealer(options: SealerOptions): Sealer;

package/dist/crypto/webhook.d.ts

@@ -0,0 +1,20 @@
+export type VerifySvixSignatureOptions = {
+    /** Signing secret, `whsec_<base64>` (the prefix is optional). */
+    secret: string;
+    /** The raw request body, exactly as received. */
+    payload: string;
+    headers: Headers | Record<string, string | undefined>;
+    /** Max age/skew of the timestamp header, in seconds. Default: 300 */
+    toleranceSec?: number;
+    /** Current time in milliseconds. Default: `Date.now()` */
+    now?: number;
+};
+/**
+ * Verifies a Svix / Standard Webhooks signature (Resend, Clerk, …): base64
+ * HMAC-SHA256 over `${id}.${timestamp}.${payload}`, keyed by the base64 body
+ * of the `whsec_` secret. Reads `svix-*` headers, falling back to `webhook-*`.
+ * Every `v1,` entry in the space-separated signature header is checked, so
+ * secret rotation works. Returns `false` for missing/stale headers or a bad
+ * signature; throws on an invalid secret.
+ */
+export declare function verifySvixSignature(options: VerifySvixSignatureOptions): Promise<boolean>;

package/dist/date/index.d.ts

@@ -1,11 +1,55 @@
+export type PeriodType = 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY';
+/**
+ * Add `n` periods to `date`, keeping its time of day (wall-clock time in local
+ * mode, so DST shifts don't move it). Month-based adds clamp the day of month:
+ * Jan 31 + 1 month → Feb 28 (or 29).
+ */
+export declare function addPeriod(date: Date, type: PeriodType, n: number, options?: {
+    utc?: boolean;
+}): Date;
+/**
+ * Calendar period containing `referenceDate`, shifted by `offset` periods
+ * (`-1` = previous, `1` = next).
+ *
+ * `start` is midnight on the first day and `end` is midnight at the **start**
+ * of the last day, so the range is inclusive for date-only comparisons. For
+ * timestamps use `timestamp < addPeriod(end, 'DAILY', 1)` as the exclusive bound.
+ *
+ * Uses the local timezone unless `utc: true`. Weeks start on Monday (ISO)
+ * unless `weekStartsOn: 0` (Sunday).
+ */
+export declare function getPeriod(type: PeriodType, referenceDate?: Date, offset?: number, options?: {
+    utc?: boolean;
+    weekStartsOn?: 0 | 1;
+}): {
+    start: Date;
+    end: Date;
+};
 /**
  * Calculate the previous period date range for a given period type.
+ * Same as `getPeriod(periodType, referenceDate, -1)`.
  */
-export declare function getPreviousReportPeriod(periodType: 'MONTHLY' | 'QUARTERLY' | 'YEARLY', referenceDate?: Date): {
+export declare function getPreviousReportPeriod(periodType: PeriodType, referenceDate?: Date): {
     start: Date;
     end: Date;
 };
+export type FormatPeriodLabelOptions = {
+    includeDay?: boolean;
+    /** Default `'en-GB'`. */
+    locale?: string;
+    /** Joins the two formatted dates. Default `' — '`. Ignored when `collapse` is set. */
+    separator?: string;
+    /**
+     * Use `Intl.DateTimeFormat#formatRange`, which drops repeated parts and uses
+     * the locale's range dash: "January – March 2025" instead of
+     * "January 2025 — March 2025".
+     */
+    collapse?: boolean;
+    /** IANA time zone, e.g. `'UTC'` for periods from `getPeriod(..., { utc: true })`. */
+    timeZone?: string;
+};
 /**
  * Format a date range as a human-readable period label.
+ * The third argument is either `includeDay` or an options object.
  */
-export declare function formatPeriodLabel(start: Date | string, end: Date | string, includeDay?: boolean): string;
+export declare function formatPeriodLabel(start: Date | string, end: Date | string, options?: boolean | FormatPeriodLabelOptions): string;

package/dist/emitter/index.d.ts

@@ -0,0 +1,21 @@
+export type Listener<P> = (payload: P) => void;
+/** Payload is optional for events typed `void` or `undefined`. */
+export type EmitArgs<P> = undefined extends P ? [payload?: P] : [payload: P];
+export type Emitter<Events extends Record<string, unknown>> = {
+    /** Adds a listener; returns an unsubscribe function. */
+    on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /** Like `on`, but removed before its first call. */
+    once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void;
+    /**
+     * Calls every listener, even if some throw, then rethrows the error (or an
+     * `AggregateError` if several threw). Listeners added during an emit wait
+     * for the next one; listeners removed during an emit are skipped.
+     */
+    emit<K extends keyof Events>(event: K, ...args: EmitArgs<Events[K]>): void;
+    /** Removes all listeners for `event`, or for every event. */
+    clear(event?: keyof Events): void;
+    listenerCount(event: keyof Events): number;
+};
+/** Typed event emitter. Adding the same listener twice keeps one entry. */
+export declare function createEmitter<Events extends Record<string, unknown>>(): Emitter<Events>;

package/dist/error/index.d.ts

@@ -0,0 +1,12 @@
+/** Thrown by `must` and `invariant` when no custom error is given. */
+export declare class InvariantError extends Error {
+    name: string;
+}
+/** An error's message: Error → `message`, string → itself, `{ message: string }` → that, else `String(error)`. */
+export declare function getErrorMessage(error: unknown, fallback?: string): string;
+/** Returns Errors unchanged, wraps anything else; a `prefix` always wraps as `${prefix}: ${message}` with `cause`. */
+export declare function toError(error: unknown, prefix?: string): Error;
+/** Returns `value`, throwing when it is null or undefined. Pass a function to throw your own error. */
+export declare function must<T>(value: T, message?: string | (() => Error)): NonNullable<T>;
+/** Throws when `condition` is falsy. Pass a function to throw your own error. */
+export declare function invariant(condition: unknown, message?: string | (() => Error)): asserts condition;

package/dist/format/index.d.ts

@@ -0,0 +1,102 @@
+type DateInput = Date | string | number;
+/** Cached `Intl.NumberFormat`, one instance per (locale, options). */
+export declare const getNumberFormat: (locale: string, options?: Intl.NumberFormatOptions | undefined) => Intl.NumberFormat;
+/** Cached `Intl.DateTimeFormat`, one instance per (locale, options). */
+export declare const getDateTimeFormat: (locale: string, options?: Intl.DateTimeFormatOptions | undefined) => Intl.DateTimeFormat;
+/** Cached `Intl.RelativeTimeFormat`, one instance per (locale, options). */
+export declare const getRelativeTimeFormat: (locale: string, options?: Intl.RelativeTimeFormatOptions | undefined) => Intl.RelativeTimeFormat;
+/** Cached `Intl.ListFormat`, one instance per (locale, options). */
+export declare const getListFormat: (locale: string, options?: Intl.ListFormatOptions | undefined) => Intl.ListFormat;
+/** Cached `Intl.PluralRules`, one instance per (locale, options). */
+export declare const getPluralRules: (locale: string, options?: Intl.PluralRulesOptions | undefined) => Intl.PluralRules;
+export declare function formatNumber(value: number, locale: string, options?: Intl.NumberFormatOptions): string;
+/** A fraction (`0.25`) as a percentage (`"25%"`). */
+export declare function formatPercent(value: number, locale: string, options?: Intl.NumberFormatOptions): string;
+/**
+ * An amount in whole currency units (`12.5`, not cents). Pass
+ * `{ maximumFractionDigits: 0 }` for whole-unit prices.
+ */
+export declare function formatCurrency(amount: number, currency: string, locale: string, options?: Intl.NumberFormatOptions): string;
+/** Short compact notation: `1234` -> `"1.2K"` (en-US), `"1,2 t"` (da-DK). */
+export declare function formatCompactNumber(value: number, locale: string): string;
+export type FormatBytesOptions = {
+    /** Default `'en-US'`. */
+    locale?: string;
+    /** Fraction digits (trailing zeros dropped). Default 0 for KB, 1 above. */
+    decimals?: number;
+    /** 1 KB = 1024 B when true (default), 1000 B when false. */
+    binary?: boolean;
+};
+/**
+ * Human-readable file size: `"512 B"`, `"12 KB"`, `"3.4 MB"`. Unit labels are
+ * not localized; the number is.
+ */
+export declare function formatBytes(bytes: number, options?: FormatBytesOptions): string;
+export type DurationParts = {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+};
+/** Break milliseconds into whole units. Negative or non-finite input is 0. */
+export declare function splitDuration(ms: number): DurationParts;
+/** Stopwatch style: `"1:05:09"` from an hour up, `"5:09"` below. */
+export declare function formatClockDuration(ms: number): string;
+export type FormatDurationOptions = {
+    /** `'long'` "1 hour, 5 minutes", `'short'` "1 hr, 5 min" (default), `'narrow'` "1h 5m". */
+    style?: 'long' | 'short' | 'narrow';
+    /** Adjacent units shown, starting at the largest non-zero one. Default 2. */
+    maxUnits?: number;
+};
+/**
+ * Localized duration, truncated (never rounded up). Units are adjacent: with
+ * the default `maxUnits: 2`, 1 day 0 h 5 min reads "1 day", not "1 day, 5 min".
+ */
+export declare function formatDuration(ms: number, locale: string, options?: FormatDurationOptions): string;
+export type FormatRelativeTimeOptions = {
+    /** Reference time. Default `Date.now()`. */
+    now?: DateInput;
+    /** `'auto'` (default) says "yesterday"; `'always'` says "1 day ago". */
+    numeric?: Intl.RelativeTimeFormatNumeric;
+    style?: Intl.RelativeTimeFormatStyle;
+    /**
+     * `false` drops "ago"/"in" and prints the bare amount ("5 minutes"), for
+     * use next to a label that already says when. Default `true`.
+     */
+    withSuffix?: boolean;
+};
+/**
+ * Time from `now` in the best-fitting unit: "5 minutes ago", "in 2 days",
+ * "yesterday". Unparseable input returns `''`.
+ */
+export declare function formatRelativeTime(date: DateInput, locale: string, options?: FormatRelativeTimeOptions): string;
+/**
+ * How long something has waited, compact for a pill or list row: "14 min",
+ * "2 hr", "3 days". Floors (never claims more waiting than happened), never
+ * shows less than "1 min", and treats a future timestamp as no waiting.
+ *
+ * A `number` is a duration in milliseconds; a `Date`/string is a start
+ * timestamp measured against `now`. Unparseable input returns `''`.
+ */
+export declare function formatWait(value: DateInput, locale: string, options?: {
+    now?: DateInput;
+}): string;
+/**
+ * One span with the shared parts collapsed: "24–30 Aug 2026". Without any
+ * date/time fields in `options` it uses day + short month + year; `timeZone`
+ * and friends combine with that default.
+ */
+export declare function formatDateRange(start: DateInput, end: DateInput, locale: string, options?: Intl.DateTimeFormatOptions): string;
+/** "a, b, and c". Falls back to a comma join where `Intl.ListFormat` is missing. */
+export declare function formatList(items: readonly string[], locale: string, options?: Intl.ListFormatOptions): string;
+/** Badge count: `150` -> `"99+"`. Negative or NaN is `"0"`. */
+export declare function formatCappedCount(count: number, max?: number): string;
+/**
+ * Pick the plural form for `count` and fill in `{count}` (locale-formatted).
+ * `pluralize(3, { one: '{count} item', other: '{count} items' }, 'en-US')`.
+ */
+export declare function pluralize(count: number, forms: Partial<Record<Intl.LDMLPluralRule, string>> & {
+    other: string;
+}, locale: string): string;
+export {};

package/dist/function/index.d.ts

@@ -0,0 +1,60 @@
+export type Debounced<A extends unknown[]> = ((...args: A) => void) & {
+    /** Drops the pending call. */
+    cancel(): void;
+    /** Runs the pending call now, if any. */
+    flush(): void;
+    /** True while a trailing call is waiting. */
+    pending(): boolean;
+};
+/**
+ * Calls `fn` with the latest args once calls stop for `waitMs` (trailing).
+ * `leading` also calls on the first call of a burst; `maxWaitMs` forces a
+ * call at least that often during a continuous burst.
+ */
+export declare function debounce<A extends unknown[]>(fn: (...args: A) => void, waitMs: number, options?: {
+    leading?: boolean;
+    maxWaitMs?: number;
+}): Debounced<A>;
+/**
+ * One independent trailing debounce per key. `cancel`/`flush` without a key
+ * apply to every pending key.
+ */
+export declare function keyedDebounce<K, A extends unknown[]>(fn: (key: K, ...args: A) => void, waitMs: number): {
+    call(key: K, ...args: A): void;
+    cancel(key?: K): void;
+    flush(key?: K): void;
+};
+/**
+ * Calls `fn` immediately, then at most once per `intervalMs`. With `trailing`
+ * (default), the last call made during an interval runs when it ends.
+ */
+export declare function throttle<A extends unknown[]>(fn: (...args: A) => void, intervalMs: number, options?: {
+    trailing?: boolean;
+}): ((...args: A) => void) & {
+    cancel(): void;
+};
+/** Calls `fn` on the first call only; later calls return the first result. */
+export declare function once<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;
+export type HeartbeatOptions = {
+    /** Called on the first activity, then at most once per `intervalMs`. */
+    send: () => void;
+    /** Called once when an active heartbeat stops (idle or `stop()`). */
+    onStop?: () => void;
+    intervalMs: number;
+    /** Stop after this long without `activity()`. */
+    idleMs: number;
+    now?: () => number;
+    setTimeout?: (callback: () => void, ms: number) => unknown;
+    clearTimeout?: (timer: unknown) => void;
+};
+/**
+ * Turns bursts of activity into heartbeats (e.g. "is typing" signals): sends
+ * immediately on the first activity, then at most once per `intervalMs` while
+ * activity continues, and stops after `idleMs` without activity.
+ */
+export declare function createHeartbeat(options: HeartbeatOptions): {
+    /** Report activity. */
+    activity(): void;
+    /** Stop now; calls `onStop` if active. Safe to call repeatedly. */
+    stop(): void;
+};

package/dist/guard/index.d.ts

@@ -0,0 +1,20 @@
+import type { NonEmptyArray } from '../types';
+/** Non-null object that is not an array. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Object literal or `Object.create(null)`; excludes arrays, class instances, Dates, Maps. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function isDefined<T>(value: T): value is NonNullable<T>;
+export declare function isTruthy<T>(value: T): value is Exclude<T, false | 0 | 0n | '' | null | undefined>;
+export declare function isString(value: unknown): value is string;
+/** `typeof number`, excluding NaN. Infinity passes. */
+export declare function isNumber(value: unknown): value is number;
+export declare function isBoolean(value: unknown): value is boolean;
+export declare function isFunction(value: unknown): value is (...args: any[]) => any;
+/** Whether `value` is in `list`. Omit `value` to get a reusable guard, e.g. for `.filter`. */
+export declare function isOneOf<const T extends readonly unknown[]>(list: T): (value: unknown) => value is T[number];
+export declare function isOneOf<const T extends readonly unknown[]>(list: T, value: unknown): value is T[number];
+/** Own-property check that narrows `key` to `keyof O`. */
+export declare function hasKey<O extends object>(object: O, key: PropertyKey): key is keyof O;
+export declare function isNonEmpty<T>(array: readonly T[]): array is readonly [T, ...T[]];
+/** Copy of `array` typed as non-empty (e.g. for `z.enum`); throws when empty. */
+export declare function nonEmpty<T>(array: readonly T[], message?: string): NonEmptyArray<T>;