hanzio 1.1.0 → 2.0.0

package/src/cache/index.ts

@@ -1,12 +1,40 @@
-type CacheEntry<T> = {
-	value: T
-	timestamp: number
-}
+import { stableStringify } from '../string'
 
 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
+	timestamp: number
+}
+
+/**
+ * Contract for external cache stores (e.g. a Redis adapter).
+ * Serialization is the adapter's responsibility; this library never imports
+ * the underlying client.
+ */
+export type CacheStore = {
+	get: (key: string) => Promise<CacheStoreEntry | undefined>
+	/** `ttlMs` maps to the store's native expiry (e.g. Redis `PX`). */
+	set: (key: string, entry: CacheStoreEntry, ttlMs: number) => Promise<void>
+	delete: (key: string) => Promise<void>
+	/** Optional; called by clearCache when defined. */
+	clear?: () => Promise<void>
 }
 
 export type CacheFunctionOptions<T extends AnyFunction> = {
@@ -18,11 +46,29 @@ export type CacheFunctionOptions<T extends AnyFunction> = {
 	cacheKeyFn?: (...args: Parameters<T>) => unknown[]
 	/** Called when a background refresh fails (default: silent). */
 	onBackgroundRefreshError?: (error: unknown, context: { name: string }) => void
+	/**
+	 * External cache store (e.g. a Redis adapter). Only supported for async
+	 * functions; when omitted the built-in in-memory cache is used.
+	 */
+	store?: ReturnType<T> extends Promise<unknown> ? CacheStore : never
+	/** Called when a store get/set/delete/clear fails (default: silent). */
+	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 function cacheFunction<T extends AnyFunction>(
+	options: CacheFunctionOptions<T> & { store: CacheStore }
+): CachedFunction<T, Promise<Awaited<ReturnType<T>> | undefined>>
 export function cacheFunction<T extends AnyFunction>(
 	options: CacheFunctionOptions<T>
-): CachedFunction<T> {
+): CachedFunction<T>
+export function cacheFunction<T extends AnyFunction>(
+	options: CacheFunctionOptions<T>
+): CachedFunction<T, unknown> {
 	const {
 		name,
 		fn,
@@ -30,115 +76,220 @@ export function cacheFunction<T extends AnyFunction>(
 		refreshInBackground = false,
 		cacheKeyArgs,
 		cacheKeyFn,
-		onBackgroundRefreshError
+		onBackgroundRefreshError,
+		store,
+		onStoreError,
+		maxEntries
 	} = options
 
-	const cache = new Map<string, CacheEntry<ReturnType<T>>>()
+	const externalStore = store as CacheStore | undefined
+
+	const cache = new Map<string, CacheStoreEntry>()
 	const pendingPromises = new Map<string, Promise<unknown>>()
 
-	const cleanupInterval = setInterval(
-		() => {
-			const now = Date.now()
-			for (const [key, entry] of cache.entries()) {
-				if (now - entry.timestamp >= cacheTimeMs) {
-					cache.delete(key)
+	// Stale entries are kept for an extra TTL so refreshInBackground can serve
+	// them while revalidating.
+	const entryLifetimeMs = refreshInBackground ? cacheTimeMs * 2 : cacheTimeMs
+
+	let cleanupInterval: ReturnType<typeof setInterval> | undefined
+
+	const stopCleanup = () => {
+		if (cleanupInterval !== undefined) {
+			clearInterval(cleanupInterval)
+			cleanupInterval = undefined
+		}
+	}
+
+	// Created lazily on first write and unref'd so it never keeps the process
+	// alive. Stops itself once the cache is empty and restarts on the next
+	// write, so clearCache does not permanently disable sweeping.
+	const ensureCleanup = () => {
+		if (cleanupInterval !== undefined) {
+			return
+		}
+		cleanupInterval = setInterval(
+			() => {
+				const now = Date.now()
+				for (const [key, entry] of cache.entries()) {
+					if (now - entry.timestamp >= entryLifetimeMs) {
+						cache.delete(key)
+					}
 				}
-			}
-		},
-		Math.min(cacheTimeMs / 2, 5 * 60 * 1000)
-	)
+				if (cache.size === 0) {
+					stopCleanup()
+				}
+			},
+			Math.min(cacheTimeMs / 2, 5 * 60 * 1000)
+		)
+		cleanupInterval.unref?.()
+	}
 
-	const wrappedFn = (...args: Parameters<T>): ReturnType<T> => {
+	const buildKey = (args: Parameters<T>): string => {
 		const keyArgs = cacheKeyFn
 			? cacheKeyFn(...args)
 			: cacheKeyArgs
 				? cacheKeyArgs.map((i) => args[i])
 				: args
-		const key = `${name}:${JSON.stringify(keyArgs)}`
-		const now = Date.now()
+		return `${name}:${stableStringify(keyArgs)}`
+	}
 
-		const pending = pendingPromises.get(key)
-		if (pending) {
-			return pending as ReturnType<T>
+	const isFresh = (entry: CacheStoreEntry) =>
+		Date.now() - entry.timestamp < cacheTimeMs
+
+	// The value a call would return straight from the cache, if any.
+	const servable = (entry: CacheStoreEntry | undefined) =>
+		entry && (refreshInBackground || isFresh(entry)) ? entry : undefined
+
+	// Map keeps insertion order, so re-inserting on every hit and write makes
+	// the first key the least recently used.
+	const touch = (key: string, entry: CacheStoreEntry) => {
+		cache.delete(key)
+		cache.set(key, entry)
+		if (maxEntries !== undefined && cache.size > maxEntries) {
+			cache.delete(cache.keys().next().value as string)
 		}
+	}
 
-		const cached = cache.get(key)
+	const guardStore = async <R>(
+		operation: () => Promise<R>
+	): Promise<R | undefined> => {
+		try {
+			return await operation()
+		} catch (error) {
+			onStoreError?.(error, { name })
+			return undefined
+		}
+	}
 
-		if (cached) {
-			const isCacheFresh = now - cached.timestamp < cacheTimeMs
+	const save = (key: string, value: unknown) => {
+		const entry = { value, timestamp: Date.now() }
+		if (externalStore) {
+			return guardStore(() => externalStore.set(key, entry, entryLifetimeMs))
+		}
+		touch(key, entry)
+		ensureCleanup()
+	}
 
-			if (!isCacheFresh && !refreshInBackground) {
-				cache.delete(key)
-			} else {
-				if (isCacheFresh && !refreshInBackground) {
-					return cached.value
-				}
+	// Calls fn and saves the result. Async calls are tracked in
+	// pendingPromises for dedupe. A failed background refresh (`stale` given)
+	// resolves to the stale value instead of rejecting.
+	const run = (
+		key: string,
+		args: Parameters<T>,
+		stale?: CacheStoreEntry
+	): unknown => {
+		const result = fn(...args)
 
-				if (refreshInBackground) {
-					const existingPending = pendingPromises.get(key)
-					if (existingPending) {
-						return existingPending as ReturnType<T>
-					}
+		if (!isPromiseLike(result)) {
+			save(key, result)
+			return result
+		}
 
-					const backgroundUpdate = fn(...args)
-
-					if (isPromiseLike(backgroundUpdate)) {
-						const backgroundPromise = (
-							backgroundUpdate as Promise<ReturnType<T>>
-						)
-							.then((resolvedValue) => {
-								cache.set(key, { value: resolvedValue, timestamp: now })
-								pendingPromises.delete(key)
-								return resolvedValue
-							})
-							.catch((error: unknown) => {
-								pendingPromises.delete(key)
-								onBackgroundRefreshError?.(error, { name })
-							})
-
-						pendingPromises.set(key, backgroundPromise)
-					} else {
-						cache.set(key, {
-							value: backgroundUpdate as ReturnType<T>,
-							timestamp: now
-						})
+		const promise: Promise<unknown> = Promise.resolve(result)
+			.then(
+				async (value) => {
+					// Skip the save when invalidate/clearCache ran meanwhile.
+					if (pendingPromises.get(key) === promise) {
+						await save(key, value)
 					}
-
-					return cached.value
+					return value
+				},
+				(error: unknown) => {
+					if (!stale) throw error
+					onBackgroundRefreshError?.(error, { name })
+					return stale.value
 				}
-
-				if (isCacheFresh) {
-					return cached.value
+			)
+			.finally(() => {
+				if (pendingPromises.get(key) === promise) {
+					pendingPromises.delete(key)
 				}
-			}
+			})
+
+		pendingPromises.set(key, promise)
+		return promise
+	}
+
+	// Serves a cached entry, starting a background refresh when it is stale.
+	const serve = (key: string, args: Parameters<T>, entry: CacheStoreEntry) => {
+		if (!isFresh(entry) && !pendingPromises.has(key)) {
+			run(key, args, entry)
 		}
+		return entry.value
+	}
 
-		const result = fn(...args)
+	const callWithStore = (
+		cacheStore: CacheStore,
+		key: string,
+		args: Parameters<T>
+	): Promise<unknown> => {
+		const pending = pendingPromises.get(key)
+		// Background refresh callers can still use an entry from the store.
+		if (pending && !refreshInBackground) {
+			return pending
+		}
 
-		if (isPromiseLike(result)) {
-			const promise = (result as Promise<ReturnType<T>>)
-				.then((resolvedValue) => {
-					cache.set(key, { value: resolvedValue, timestamp: now })
-					pendingPromises.delete(key)
-					return resolvedValue
-				})
-				.catch((error) => {
-					pendingPromises.delete(key)
-					throw error
-				})
+		return (async () => {
+			const entry = await guardStore(() => cacheStore.get(key))
+			const cached = servable(entry)
 
-			pendingPromises.set(key, promise)
-			return promise as ReturnType<T>
+			if (cached) {
+				return serve(key, args, cached)
+			}
+			if (entry) {
+				await guardStore(() => cacheStore.delete(key))
+			}
+
+			// A concurrent caller may have started a fetch while we awaited the
+			// store lookup.
+			return pendingPromises.get(key) ?? run(key, args)
+		})()
+	}
+
+	const wrappedFn = (...args: Parameters<T>): ReturnType<T> => {
+		const key = buildKey(args)
+
+		if (externalStore) {
+			return callWithStore(externalStore, key, args) as ReturnType<T>
+		}
+
+		const cached = servable(cache.get(key))
+		if (cached) {
+			touch(key, cached)
+			return serve(key, args, cached) as ReturnType<T>
 		}
+		cache.delete(key)
 
-		cache.set(key, { value: result as ReturnType<T>, timestamp: now })
-		return result as ReturnType<T>
+		return (pendingPromises.get(key) ?? run(key, args)) as ReturnType<T>
 	}
 
 	wrappedFn.clearCache = () => {
 		cache.clear()
 		pendingPromises.clear()
-		clearInterval(cleanupInterval)
+		stopCleanup()
+		const clearStore = externalStore?.clear?.bind(externalStore)
+		if (clearStore) {
+			void guardStore(clearStore)
+		}
+	}
+
+	wrappedFn.invalidate = (...args: Parameters<T>) => {
+		const key = buildKey(args)
+		cache.delete(key)
+		pendingPromises.delete(key)
+		if (externalStore) {
+			void guardStore(() => externalStore.delete(key))
+		}
+	}
+
+	wrappedFn.peek = (...args: Parameters<T>): unknown => {
+		const key = buildKey(args)
+		if (externalStore) {
+			return guardStore(() => externalStore.get(key)).then(
+				(entry) => servable(entry)?.value
+			)
+		}
+		return servable(cache.get(key))?.value
 	}
 
 	return wrappedFn
@@ -152,3 +303,4 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 		typeof value.then === 'function'
 	)
 }
+export * from './createCache'

package/src/color/contrast.ts

@@ -0,0 +1,163 @@
+import { clamp } from '../math/scale'
+
+/** 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 function colorFunctionArgs(
+	color: string
+): { name: 'rgb' | 'hsl'; args: string[] } | undefined {
+	const match = /^(rgb|hsl)a?\(([^()]*)\)$/i.exec(color.trim())
+	const args = match?.[2]?.trim().split(/[\s,/]+/)
+	if (!match || !args || (args.length !== 3 && args.length !== 4)) {
+		return undefined
+	}
+	return { name: match[1]!.toLowerCase() as 'rgb' | 'hsl', args }
+}
+
+// A number, or a percentage scaled so 100% = `percentOf`.
+function parseChannel(raw: string, percentOf: number): number | undefined {
+	const isPercent = raw.endsWith('%')
+	const text = isPercent ? raw.slice(0, -1) : raw
+	const n = text === '' ? Number.NaN : Number(text)
+	if (!Number.isFinite(n)) return undefined
+	return isPercent ? (n / 100) * percentOf : n
+}
+
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+	const a = s * Math.min(l, 1 - l)
+	const f = (n: number) => {
+		const k = (n + h / 30) % 12
+		return (l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1))) * 255
+	}
+	return [f(0), f(8), f(4)]
+}
+
+/**
+ * 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 function parseColor(color: string): Rgba | undefined {
+	const trimmed = color.trim()
+
+	const hex = /^#([\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.exec(trimmed)?.[1]
+	if (hex) {
+		const full = hex.length <= 4 ? hex.replace(/./g, '$&$&') : hex
+		const [r = 0, g = 0, b = 0, a = 255] = [0, 2, 4, 6].map((i) =>
+			i < full.length ? Number.parseInt(full.slice(i, i + 2), 16) : undefined
+		)
+		return { r, g, b, a: a / 255 }
+	}
+
+	const fn = colorFunctionArgs(trimmed)
+	if (!fn) return undefined
+	const [x = '', y = '', z = '', alpha = '1'] = fn.args
+	const isRgb = fn.name === 'rgb'
+	const c1 = parseChannel(isRgb ? x : x.replace(/deg$/i, ''), isRgb ? 255 : 360)
+	const c2 = parseChannel(y, isRgb ? 255 : 100)
+	const c3 = parseChannel(z, isRgb ? 255 : 100)
+	const a = parseChannel(alpha, 1)
+	if (c1 === undefined || c2 === undefined || c3 === undefined) return undefined
+	if (a === undefined) return undefined
+
+	const [r, g, b] = isRgb
+		? [c1, c2, c3]
+		: hslToRgb(
+				((c1 % 360) + 360) % 360,
+				clamp(c2 / 100, 0, 1),
+				clamp(c3 / 100, 0, 1)
+			)
+	const channel = (v: number) => Math.round(clamp(v, 0, 255))
+	return { r: channel(r), g: channel(g), b: channel(b), a: clamp(a, 0, 1) }
+}
+
+function toRgba(color: Rgba | string): Rgba {
+	if (typeof color !== 'string') return color
+	const parsed = parseColor(color)
+	if (!parsed) throw new TypeError(`Unsupported color: ${color}`)
+	return parsed
+}
+
+/** `#rrggbb` (or `#rrggbbaa` with `alpha: true`). Throws on unparseable strings. */
+export function toHex(
+	color: Rgba | string,
+	options: { alpha?: boolean } = {}
+): string {
+	const { r, g, b, a } = toRgba(color)
+	const channels = options.alpha ? [r, g, b, a * 255] : [r, g, b]
+	return `#${channels
+		.map((v) =>
+			Math.round(clamp(v, 0, 255))
+				.toString(16)
+				.padStart(2, '0')
+		)
+		.join('')}`
+}
+
+/** `rgb(r, g, b)`, or `rgba(r, g, b, a)` when translucent. Throws on unparseable strings. */
+export function toRgbString(color: Rgba | string): string {
+	const { r, g, b, a } = toRgba(color)
+	const [rr, gg, bb] = [r, g, b].map((v) => Math.round(clamp(v, 0, 255)))
+	return a < 1 ? `rgba(${rr}, ${gg}, ${bb}, ${a})` : `rgb(${rr}, ${gg}, ${bb})`
+}
+
+/** WCAG 2.x relative luminance (0 = black, 1 = white); alpha is ignored. */
+export function relativeLuminance(color: Rgba | string): number {
+	const { r, g, b } = toRgba(color)
+	const [lr, lg, lb] = [r, g, b].map((v) => {
+		const c = clamp(v, 0, 255) / 255
+		return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+	}) as [number, number, number]
+	return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb
+}
+
+/** WCAG contrast ratio between two colors, from 1 to 21. */
+export function contrastRatio(a: Rgba | string, b: Rgba | string): number {
+	const la = relativeLuminance(a)
+	const lb = relativeLuminance(b)
+	return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05)
+}
+
+/** Whichever of `light`/`dark` contrasts more with `background` (ties go to `light`). */
+export function contrastText(
+	background: Rgba | string,
+	options: { light?: string; dark?: string } = {}
+): string {
+	const { light = '#ffffff', dark = '#000000' } = options
+	return contrastRatio(background, light) >= contrastRatio(background, dark)
+		? light
+		: dark
+}
+
+function mix(a: Rgba, b: Rgba, weight: number): Rgba {
+	const t = clamp(weight, 0, 1)
+	const at = (x: number, y: number) => x + (y - x) * t
+	return {
+		r: at(a.r, b.r),
+		g: at(a.g, b.g),
+		b: at(a.b, b.b),
+		a: at(a.a, b.a)
+	}
+}
+
+const hexOf = (color: Rgba) => toHex(color, { alpha: color.a < 1 })
+
+/** Blend `b` into `a` by `weight` (0 = `a`, 1 = `b`) as hex; alpha kept only when translucent. */
+export function mixColors(
+	a: Rgba | string,
+	b: Rgba | string,
+	weight: number
+): string {
+	return hexOf(mix(toRgba(a), toRgba(b), weight))
+}
+
+/** Darken toward black (`amount` < 0) or lighten toward white (> 0); `amount` in -1..1. Returns hex. */
+export function shade(color: Rgba | string, amount: number): string {
+	const base = toRgba(color)
+	const v = amount < 0 ? 0 : 255
+	return hexOf(mix(base, { r: v, g: v, b: v, a: base.a }, Math.abs(amount)))
+}

package/src/color/index.ts

@@ -0,0 +1,22 @@
+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'