hanzio 1.2.0 → 2.0.0

package/src/cache/index.ts

@@ -1,12 +1,21 @@
-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 = {
@@ -44,11 +53,22 @@ export type CacheFunctionOptions<T extends AnyFunction> = {
 	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>
 export function cacheFunction<T extends AnyFunction>(
 	options: CacheFunctionOptions<T>
-): CachedFunction<T> {
+): CachedFunction<T, unknown> {
 	const {
 		name,
 		fn,
@@ -58,12 +78,13 @@ export function cacheFunction<T extends AnyFunction>(
 		cacheKeyFn,
 		onBackgroundRefreshError,
 		store,
-		onStoreError
+		onStoreError,
+		maxEntries
 	} = options
 
 	const externalStore = store as CacheStore | undefined
 
-	const cache = new Map<string, CacheEntry<ReturnType<T>>>()
+	const cache = new Map<string, CacheStoreEntry>()
 	const pendingPromises = new Map<string, Promise<unknown>>()
 
 	// Stale entries are kept for an extra TTL so refreshInBackground can serve
@@ -109,91 +130,99 @@ export function cacheFunction<T extends AnyFunction>(
 			: cacheKeyArgs
 				? cacheKeyArgs.map((i) => args[i])
 				: args
-		return `${name}:${JSON.stringify(keyArgs)}`
+		return `${name}:${stableStringify(keyArgs)}`
 	}
 
-	const saveEntry = (key: string, value: ReturnType<T>) => {
-		cache.set(key, { value, timestamp: Date.now() })
-		ensureCleanup()
-	}
+	const isFresh = (entry: CacheStoreEntry) =>
+		Date.now() - entry.timestamp < cacheTimeMs
 
-	const fetchAndPopulate = (
-		key: string,
-		args: Parameters<T>
-	): ReturnType<T> => {
-		const result = fn(...args)
+	// The value a call would return straight from the cache, if any.
+	const servable = (entry: CacheStoreEntry | undefined) =>
+		entry && (refreshInBackground || isFresh(entry)) ? entry : undefined
 
-		if (!isPromiseLike(result)) {
-			saveEntry(key, result as ReturnType<T>)
-			return result as ReturnType<T>
+	// 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 promise = (result as Promise<ReturnType<T>>)
-			.then((value) => {
-				saveEntry(key, value)
-				pendingPromises.delete(key)
-				return value
-			})
-			.catch((error: unknown) => {
-				pendingPromises.delete(key)
-				throw error
-			})
+	const guardStore = async <R>(
+		operation: () => Promise<R>
+	): Promise<R | undefined> => {
+		try {
+			return await operation()
+		} catch (error) {
+			onStoreError?.(error, { name })
+			return undefined
+		}
+	}
 
-		pendingPromises.set(key, promise)
-		return promise as ReturnType<T>
+	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()
 	}
 
-	const startBackgroundRefresh = (
+	// 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>,
-		staleValue: ReturnType<T>
-	) => {
+		stale?: CacheStoreEntry
+	): unknown => {
 		const result = fn(...args)
 
 		if (!isPromiseLike(result)) {
-			saveEntry(key, result as ReturnType<T>)
-			return
+			save(key, result)
+			return result
 		}
 
-		const promise = (result as Promise<ReturnType<T>>)
-			.then((value) => {
-				saveEntry(key, value)
-				pendingPromises.delete(key)
-				return value
-			})
-			.catch((error: unknown) => {
-				pendingPromises.delete(key)
-				onBackgroundRefreshError?.(error, { name })
-				// Anyone awaiting this promise gets the stale value instead of
-				// undefined or a rejection.
-				return staleValue
+		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 value
+				},
+				(error: unknown) => {
+					if (!stale) throw error
+					onBackgroundRefreshError?.(error, { name })
+					return stale.value
+				}
+			)
+			.finally(() => {
+				if (pendingPromises.get(key) === promise) {
+					pendingPromises.delete(key)
+				}
 			})
 
 		pendingPromises.set(key, promise)
+		return promise
 	}
 
-	const saveToStore = async (
-		cacheStore: CacheStore,
-		key: string,
-		value: unknown
-	) => {
-		try {
-			await cacheStore.set(
-				key,
-				{ value, timestamp: Date.now() },
-				entryLifetimeMs
-			)
-		} catch (error) {
-			onStoreError?.(error, { name })
+	// 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 callWithStore = (
 		cacheStore: CacheStore,
+		key: string,
 		args: Parameters<T>
 	): Promise<unknown> => {
-		const key = buildKey(args)
-
 		const pending = pendingPromises.get(key)
 		// Background refresh callers can still use an entry from the store.
 		if (pending && !refreshInBackground) {
@@ -201,111 +230,66 @@ export function cacheFunction<T extends AnyFunction>(
 		}
 
 		return (async () => {
-			let entry: CacheStoreEntry | undefined
-			try {
-				entry = await cacheStore.get(key)
-			} catch (error) {
-				onStoreError?.(error, { name })
-			}
+			const entry = await guardStore(() => cacheStore.get(key))
+			const cached = servable(entry)
 
+			if (cached) {
+				return serve(key, args, cached)
+			}
 			if (entry) {
-				const isFresh = Date.now() - entry.timestamp < cacheTimeMs
-
-				if (isFresh) {
-					return entry.value
-				}
-
-				if (refreshInBackground) {
-					if (!pendingPromises.has(key)) {
-						const staleValue = entry.value
-						const refresh = (fn(...args) as Promise<unknown>)
-							.then(async (value) => {
-								await saveToStore(cacheStore, key, value)
-								pendingPromises.delete(key)
-								return value
-							})
-							.catch((error: unknown) => {
-								pendingPromises.delete(key)
-								onBackgroundRefreshError?.(error, { name })
-								return staleValue
-							})
-						pendingPromises.set(key, refresh)
-					}
-					return entry.value
-				}
-
-				try {
-					await cacheStore.delete(key)
-				} catch (error) {
-					onStoreError?.(error, { name })
-				}
+				await guardStore(() => cacheStore.delete(key))
 			}
 
 			// A concurrent caller may have started a fetch while we awaited the
 			// store lookup.
-			const existing = pendingPromises.get(key)
-			if (existing) {
-				return existing
-			}
-
-			const promise = (fn(...args) as Promise<unknown>)
-				.then(async (value) => {
-					await saveToStore(cacheStore, key, value)
-					pendingPromises.delete(key)
-					return value
-				})
-				.catch((error: unknown) => {
-					pendingPromises.delete(key)
-					throw error
-				})
-
-			pendingPromises.set(key, promise)
-			return promise
+			return pendingPromises.get(key) ?? run(key, args)
 		})()
 	}
 
 	const wrappedFn = (...args: Parameters<T>): ReturnType<T> => {
-		if (externalStore) {
-			return callWithStore(externalStore, args) as ReturnType<T>
-		}
-
 		const key = buildKey(args)
-		const cached = cache.get(key)
-
-		if (cached) {
-			const isFresh = Date.now() - cached.timestamp < cacheTimeMs
-
-			if (isFresh) {
-				return cached.value
-			}
-
-			if (refreshInBackground) {
-				if (!pendingPromises.has(key)) {
-					startBackgroundRefresh(key, args, cached.value)
-				}
-				return cached.value
-			}
 
-			cache.delete(key)
+		if (externalStore) {
+			return callWithStore(externalStore, key, args) as ReturnType<T>
 		}
 
-		const pending = pendingPromises.get(key)
-		if (pending) {
-			return pending 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)
 
-		return fetchAndPopulate(key, args)
+		return (pendingPromises.get(key) ?? run(key, args)) as ReturnType<T>
 	}
 
 	wrappedFn.clearCache = () => {
 		cache.clear()
 		pendingPromises.clear()
 		stopCleanup()
-		if (externalStore?.clear) {
-			externalStore.clear().catch((error: unknown) => {
-				onStoreError?.(error, { name })
-			})
+		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
@@ -319,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'