hanzio 1.2.0 → 2.1.0

package/src/i18n/index.ts

@@ -0,0 +1,125 @@
+export type PlaceholderValue = string | number
+
+// `\w` in PLACEHOLDER_PATTERN, spelled out so the types match the runtime exactly
+type Chars<S extends string> = S extends `${infer C}${infer Rest}`
+	? C | Chars<Rest>
+	: never
+type Letter = Chars<'abcdefghijklmnopqrstuvwxyz'>
+type WordChar = Letter | Uppercase<Letter> | Chars<'0123456789_'>
+
+type IsWord<S extends string> = S extends `${infer C}${infer Rest}`
+	? C extends WordChar
+		? Rest extends ''
+			? true
+			: IsWord<Rest>
+		: false
+	: false
+
+// `{a {b}` holds the placeholder `b`: keep the text after the last `{`
+type AfterLastBrace<S extends string> = S extends `${string}{${infer Rest}`
+	? AfterLastBrace<Rest>
+	: S
+
+type ExtractNames<
+	S extends string,
+	Found extends string = never
+> = S extends `${string}{${infer Body}}${infer Rest}`
+	? ExtractNames<
+			Rest,
+			| Found
+			| (IsWord<AfterLastBrace<Body>> extends true
+					? AfterLastBrace<Body>
+					: never)
+		>
+	: Found
+
+/** `'Hi {name}, you have {count}'` → `'name' | 'count'`; `string` for non-literal templates. */
+export type PlaceholderNames<S extends string> = string extends S
+	? string
+	: ExtractNames<S>
+
+export type PlaceholderParams<S extends string> = Record<
+	PlaceholderNames<S>,
+	PlaceholderValue
+>
+
+/** Params argument: required with placeholders, absent without, optional for non-literal templates. */
+export type PlaceholderArgs<S extends string> = string extends S
+	? [params?: PlaceholderParams<S>]
+	: [PlaceholderNames<S>] extends [never]
+		? []
+		: [params: PlaceholderParams<S>]
+
+/** A `{name}` placeholder: word characters only, so `{ x }` and `{n, plural}` are plain text. */
+const PLACEHOLDER_PATTERN = /\{(\w+)\}/g
+
+/** Unique placeholder names in order of first appearance. */
+export function extractPlaceholders<S extends string>(
+	template: S
+): PlaceholderNames<S>[] {
+	const names = template.matchAll(PLACEHOLDER_PATTERN).map((match) => match[1])
+	return [...new Set(names)] as PlaceholderNames<S>[]
+}
+
+/**
+ * Replaces `{name}` placeholders with `params`. Placeholders without a
+ * (non-null) param are left as-is. There is no escape syntax.
+ */
+export function interpolate<S extends string>(
+	template: S,
+	...args: PlaceholderArgs<S>
+): string {
+	const params: Partial<Record<string, PlaceholderValue>> = args[0] ?? {}
+	return template.replace(PLACEHOLDER_PATTERN, (match, name: string) => {
+		const value = Object.hasOwn(params, name) ? params[name] : undefined
+		return value == null ? match : String(value)
+	})
+}
+
+export type Messages = { readonly [key: string]: string | Messages }
+
+/** Dot-path keys of the string leaves: `{ a: { b: 'x' } }` → `'a.b'`. */
+export type MessageKeys<T> = {
+	[K in keyof T & string]: T[K] extends string ? K : `${K}.${MessageKeys<T[K]>}`
+}[keyof T & string]
+
+/** Message at a dot-path key. */
+export type MessageAt<T, K extends string> = K extends keyof T
+	? T[K]
+	: K extends `${infer Head}.${infer Rest}`
+		? Head extends keyof T
+			? MessageAt<T[Head], Rest>
+			: never
+		: never
+
+/** `{ a: { b: 'x' } }` → `{ 'a.b': 'x' }` */
+export function flattenMessages<const T extends Messages>(
+	messages: T
+): Record<MessageKeys<T>, string> {
+	const out: Record<string, string> = {}
+	const visit = (node: Messages, prefix: string) => {
+		for (const [key, value] of Object.entries(node)) {
+			if (typeof value === 'string') out[prefix + key] = value
+			else visit(value, `${prefix + key}.`)
+		}
+	}
+	visit(messages, '')
+	return out
+}
+
+/**
+ * Typed `t(key, params)` over a nested messages object. With literal messages
+ * (inline `const` objects), params are required exactly when the message has
+ * placeholders. Unknown keys at runtime return the key.
+ */
+export function createTranslator<const T extends Messages>(messages: T) {
+	const flat: Partial<Record<string, string>> = flattenMessages(messages)
+	return <K extends MessageKeys<T>>(
+		key: K,
+		...args: PlaceholderArgs<Extract<MessageAt<T, K>, string>>
+	): string =>
+		interpolate(
+			flat[key] ?? key,
+			...(args as [Record<string, PlaceholderValue>?])
+		)
+}

package/src/index.ts

@@ -1,3 +1,7 @@
+// Dependency-free helpers only. Modules that need zod, network access or a
+// specific runtime live on subpath exports (hanzio/zod, hanzio/api-wrapper,
+// hanzio/jwt, hanzio/sitemap, hanzio/p-queue, hanzio/cool-console-log,
+// hanzio/secrets).
 export * from './typedswitch'
 export * from './array'
 export * from './string'
@@ -5,12 +9,12 @@ export * from './promise'
 export * from './cache'
 export * from './state'
 export * from './math'
+export * from './color'
 export * from './date'
 export * from './url'
-export * from './zod'
-export * from './api-wrapper'
-export * from './p-queue'
-export * from './cool-console-log'
-export * from './jwt'
-export * from './sitemap'
-export * from './secrets'
+export * from './error'
+export * from './guard'
+export * from './object'
+export * from './types'
+export * from './function'
+export * from './emitter'

package/src/jwt/index.ts

@@ -1,171 +1,245 @@
+import {
+	decodeBase64Url,
+	encodeBase64Url,
+	utf8Decode,
+	utf8Encode
+} from '../crypto/encoding'
+import { getSubtleCrypto } from '../crypto/hash'
+import type { Result } from '../promise'
+import { isRecord } from '../guard'
+
 export type JWTPayload = Record<string, unknown>
 
-const BYTE_CHUNK_SIZE = 0x8000
-const textEncoder = new TextEncoder()
-const textDecoder = new TextDecoder()
+export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512'
+
+export type JwtHeader = { alg: string; typ?: string } & Record<string, unknown>
+
+export type JwtSignOptions = {
+	/** Seconds from now until `exp`. */
+	expiresIn?: number
+	/** Seconds from now until `nbf`. */
+	notBefore?: number
+	issuer?: string
+	audience?: string | string[]
+	/** Default: `'HS256'` */
+	algorithm?: JwtAlgorithm
+}
+
+export type JwtVerifyOptions = {
+	/** Clock skew tolerance for `exp`/`nbf`, in seconds. Default: 0 */
+	leewaySec?: number
+	/** Required `iss` value. */
+	issuer?: string
+	/** Required `aud` value (matches a string `aud` or an entry of an array `aud`). */
+	audience?: string
+	/** Accepted header `alg` values. Default: all of HS256/HS384/HS512. */
+	algorithms?: JwtAlgorithm[]
+}
+
+export type JwtVerifyErrorCode =
+	| 'malformed'
+	| 'unsupported_alg'
+	| 'invalid_signature'
+	| 'expired'
+	| 'not_yet_valid'
+	| 'invalid_issuer'
+	| 'invalid_audience'
+
+export class JwtVerifyError extends Error {
+	readonly code: JwtVerifyErrorCode
+
+	constructor(code: JwtVerifyErrorCode) {
+		super(`JWT verification failed: ${code}`)
+		this.name = 'JwtVerifyError'
+		this.code = code
+	}
+}
+
+const HASHES: Record<JwtAlgorithm, string> = {
+	HS256: 'SHA-256',
+	HS384: 'SHA-384',
+	HS512: 'SHA-512'
+}
+const ALGORITHMS = Object.keys(HASHES) as JwtAlgorithm[]
+const BASE64URL = /^[A-Za-z0-9_-]*$/
+const KEY_CACHE_LIMIT = 100
 
+/**
+ * Signs `payload` as a compact JWS. `iat` is always set to now.
+ * Claims derived from `options` (`exp`, `nbf`, `iss`, `aud`) override the same
+ * claims in `payload`; payload claims are kept when the option is not given.
+ */
 export async function jwtSign<Payload extends JWTPayload>(
 	payload: Payload,
-	secret: string
+	secret: string,
+	options: JwtSignOptions = {}
 ): Promise<string> {
-	const header = encodeJson({ alg: 'HS256' })
-	const body = encodeJson({
-		...payload,
-		iat: Math.floor(Date.now() / 1000)
-	})
-	const data = `${header}.${body}`
-	const signature = await sign(data, secret)
+	const {
+		expiresIn,
+		notBefore,
+		issuer,
+		audience,
+		algorithm = 'HS256'
+	} = options
+	if (!Object.hasOwn(HASHES, algorithm)) {
+		throw new TypeError(`Unsupported JWT algorithm: ${algorithm}`)
+	}
+
+	const now = Math.floor(Date.now() / 1000)
+	const claims: JWTPayload = { ...payload, iat: now }
+	if (expiresIn !== undefined) claims.exp = now + toSeconds(expiresIn)
+	if (notBefore !== undefined) claims.nbf = now + toSeconds(notBefore)
+	if (issuer !== undefined) claims.iss = issuer
+	if (audience !== undefined) claims.aud = audience
+
+	const data = `${encodeJson({ alg: algorithm, typ: 'JWT' })}.${encodeJson(claims)}`
+	const key = await getKey(secret, algorithm, 'sign')
+	const signature = await getSubtleCrypto().sign('HMAC', key, utf8Encode(data))
 
 	return `${data}.${encodeBase64Url(signature)}`
 }
 
+/** Verifies a token. Returns `null` for any failure; use `jwtVerifyResult` for the reason. */
 export async function jwtVerify<Payload extends JWTPayload>(
 	token: string,
-	secret: string
+	secret: string,
+	options?: JwtVerifyOptions
 ): Promise<Payload | null> {
 	try {
-		const parts = token.split('.')
-		if (parts.length !== 3) return null
-
-		const [encodedHeader, encodedPayload, encodedSignature] = parts as [
-			string,
-			string,
-			string
-		]
-		const header = decodeJson(encodedHeader)
-		if (!isJwtHeader(header)) return null
-
-		const data = `${encodedHeader}.${encodedPayload}`
-		const signature = decodeBase64Url(encodedSignature)
-		const isValid = await verify(data, signature, secret)
-		if (!isValid) return null
-
-		const payload = decodeJson(encodedPayload)
-		if (!isJwtPayload(payload) || !isTimeValid(payload)) return null
-
-		return payload as Payload
+		const result = await jwtVerifyResult<Payload>(token, secret, options)
+		return result.ok ? result.data : null
 	} catch (_error) {
 		return null
 	}
 }
 
-async function sign(data: string, secret: string): Promise<ArrayBuffer> {
-	const key = await getKey(secret, ['sign'])
-	return await getSubtleCrypto().sign('HMAC', key, encodeText(data))
-}
+/**
+ * Verifies signature, `exp`/`nbf` and optional `iss`/`aud`.
+ * Token problems are returned as a failed `Result`; configuration problems
+ * (no Web Crypto, empty secret) throw.
+ */
+export async function jwtVerifyResult<Payload extends JWTPayload>(
+	token: string,
+	secret: string,
+	options: JwtVerifyOptions = {}
+): Promise<Result<Payload, JwtVerifyError>> {
+	const { leewaySec = 0, issuer, audience, algorithms = ALGORITHMS } = options
+
+	const decoded = jwtDecode<Payload>(token)
+	if (!decoded) return fail('malformed')
+
+	const { alg } = decoded.header
+	// Only header algs that are both known HMAC algs and explicitly allowed; never 'none'.
+	if (
+		!Object.hasOwn(HASHES, alg) ||
+		!algorithms.includes(alg as JwtAlgorithm)
+	) {
+		return fail('unsupported_alg')
+	}
 
-async function verify(
-	data: string,
-	signature: ArrayBuffer,
-	secret: string
-): Promise<boolean> {
-	const key = await getKey(secret, ['verify'])
-	return await getSubtleCrypto().verify(
+	const lastDot = token.lastIndexOf('.')
+	let signature: Uint8Array<ArrayBuffer>
+	try {
+		signature = decodeBase64Url(token.slice(lastDot + 1))
+	} catch (_error) {
+		return fail('malformed')
+	}
+
+	const key = await getKey(secret, alg as JwtAlgorithm, 'verify')
+	const isValid = await getSubtleCrypto().verify(
 		'HMAC',
 		key,
 		signature,
-		encodeText(data)
+		utf8Encode(token.slice(0, lastDot))
 	)
-}
+	if (!isValid) return fail('invalid_signature')
 
-async function getKey(
-	secret: string,
-	usages: Array<'sign' | 'verify'>
-): Promise<CryptoKey> {
-	return await getSubtleCrypto().importKey(
-		'raw',
-		encodeText(secret),
-		{
-			name: 'HMAC',
-			hash: 'SHA-256'
-		},
-		false,
-		usages
-	)
-}
+	const { payload } = decoded
+	const { exp, nbf } = payload
+	if (exp !== undefined && typeof exp !== 'number') return fail('malformed')
+	if (nbf !== undefined && typeof nbf !== 'number') return fail('malformed')
 
-function encodeJson(value: JWTPayload): string {
-	return encodeBase64Url(encodeText(JSON.stringify(value)))
-}
-
-function decodeJson(value: string): unknown {
-	return JSON.parse(textDecoder.decode(decodeBase64Url(value)))
-}
-
-function encodeBase64Url(value: Uint8Array | ArrayBuffer): string {
-	const bytes = value instanceof ArrayBuffer ? new Uint8Array(value) : value
-	return btoa(bytesToBinaryString(bytes))
-		.replaceAll('+', '-')
-		.replaceAll('/', '_')
-		.replace(/=+$/, '')
-}
-
-function decodeBase64Url(value: string): ArrayBuffer {
-	const base64 = value.replaceAll('-', '+').replaceAll('_', '/')
-	const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=')
-	return binaryStringToBytes(atob(padded)).buffer
-}
+	const now = Math.floor(Date.now() / 1000)
+	if (exp !== undefined && now >= exp + leewaySec) return fail('expired')
+	if (nbf !== undefined && now + leewaySec < nbf) return fail('not_yet_valid')
+	if (issuer !== undefined && payload.iss !== issuer) {
+		return fail('invalid_issuer')
+	}
+	if (audience !== undefined) {
+		const { aud } = payload
+		const matches = Array.isArray(aud)
+			? aud.includes(audience)
+			: aud === audience
+		if (!matches) return fail('invalid_audience')
+	}
 
-function encodeText(value: string): ArrayBuffer {
-	return toArrayBuffer(textEncoder.encode(value))
+	return { ok: true, data: payload, error: null }
 }
 
-function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
-	return bytes.buffer.slice(
-		bytes.byteOffset,
-		bytes.byteOffset + bytes.byteLength
-	) as ArrayBuffer
-}
+/** Decodes header and payload WITHOUT verifying the signature. Never trust the result for auth. */
+export function jwtDecode<Payload extends JWTPayload = JWTPayload>(
+	token: string
+): { header: JwtHeader; payload: Payload } | null {
+	const parts = token.split('.')
+	if (parts.length !== 3 || !parts.every((part) => BASE64URL.test(part))) {
+		return null
+	}
 
-function bytesToBinaryString(bytes: Uint8Array): string {
-	let binary = ''
+	try {
+		const header = decodeJson(parts[0] as string)
+		const payload = decodeJson(parts[1] as string)
+		if (!isRecord(header) || typeof header.alg !== 'string') return null
+		if (!isRecord(payload)) return null
 
-	for (let offset = 0; offset < bytes.length; offset += BYTE_CHUNK_SIZE) {
-		binary += String.fromCharCode(
-			...bytes.subarray(offset, offset + BYTE_CHUNK_SIZE)
-		)
+		return { header: header as JwtHeader, payload: payload as Payload }
+	} catch (_error) {
+		return null
 	}
-
-	return binary
 }
 
-function binaryStringToBytes(binary: string): Uint8Array<ArrayBuffer> {
-	const bytes = new Uint8Array(binary.length)
+function fail(code: JwtVerifyErrorCode): Result<never, JwtVerifyError> {
+	return { ok: false, data: null, error: new JwtVerifyError(code) }
+}
 
-	for (let index = 0; index < binary.length; index += 1) {
-		bytes[index] = binary.charCodeAt(index)
+function toSeconds(value: number): number {
+	// NaN/Infinity would serialize to `null` and silently drop the claim.
+	if (!Number.isFinite(value)) {
+		throw new TypeError(`Expected a finite number of seconds, got ${value}`)
 	}
-
-	return bytes
+	return Math.floor(value)
 }
 
-function getSubtleCrypto(): SubtleCrypto {
-	const subtle = globalThis.crypto?.subtle
-	if (!subtle) {
-		throw new Error('Web Crypto is not available in this runtime')
-	}
+// ponytail: cleared wholesale at KEY_CACHE_LIMIT entries; swap for an LRU if
+// an app rotates through more than ~100 secrets.
+const keyCache = new Map<string, Promise<CryptoKey>>()
 
-	return subtle
-}
+function getKey(
+	secret: string,
+	algorithm: JwtAlgorithm,
+	usage: 'sign' | 'verify'
+): Promise<CryptoKey> {
+	const cacheKey = `${algorithm}:${usage}:${secret}`
+	const cached = keyCache.get(cacheKey)
+	if (cached) return cached
 
-function isJwtHeader(value: unknown): value is { alg: 'HS256' } {
-	return (
-		typeof value === 'object' &&
-		value !== null &&
-		'alg' in value &&
-		value.alg === 'HS256'
+	if (keyCache.size >= KEY_CACHE_LIMIT) keyCache.clear()
+	const key = getSubtleCrypto().importKey(
+		'raw',
+		utf8Encode(secret),
+		{ name: 'HMAC', hash: HASHES[algorithm] },
+		false,
+		[usage]
 	)
-}
+	keyCache.set(cacheKey, key)
+	key.catch(() => keyCache.delete(cacheKey))
 
-function isJwtPayload(value: unknown): value is JWTPayload {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
+	return key
 }
 
-function isTimeValid(payload: JWTPayload): boolean {
-	const now = Math.floor(Date.now() / 1000)
-
-	if (typeof payload.exp === 'number' && now >= payload.exp) return false
-	if (typeof payload.nbf === 'number' && now < payload.nbf) return false
+function encodeJson(value: JWTPayload): string {
+	return encodeBase64Url(utf8Encode(JSON.stringify(value)))
+}
 
-	return true
+function decodeJson(value: string): unknown {
+	return JSON.parse(utf8Decode(decodeBase64Url(value)))
 }

package/src/math/index.ts

@@ -1,11 +1,6 @@
-export { linearRegressionTrend } from './linearRegressionTrend'
 export {
-	createResolveColorsByKeys,
-	getHeatmapCellStyle,
-	hashStringToColorIndex,
-	METRICS_SERIES_PALETTE_SIZE,
-	type ResolveColorsByKeysResult,
-	resolveSeriesColorMap,
-	seriesColorKey,
-	withAlpha
-} from './metricsSeriesColors'
+	type LinearRegression,
+	linearRegression,
+	linearRegressionTrend
+} from './linearRegressionTrend'
+export { clamp, lerp, normalize } from './scale'

package/src/math/linearRegressionTrend.ts

@@ -1,12 +1,21 @@
+export type LinearRegression = {
+	slope: number
+	intercept: number
+	/** Coefficient of determination (0..1). 1 when all values are equal (exact fit). */
+	r2: number
+	/** Fitted y for each index. */
+	fitted: number[]
+}
+
 /**
  * Least-squares linear regression for y at x = 0, 1, …, n − 1.
- * Returns fitted y for each index, or [] if n < 2 or any input is non-finite.
+ * Returns `null` if n < 2 or any input is non-finite.
  */
-export function linearRegressionTrend(values: number[]): number[] {
+export function linearRegression(values: number[]): LinearRegression | null {
 	const n = values.length
-	if (n < 2) return []
+	if (n < 2) return null
 	for (const v of values) {
-		if (!Number.isFinite(v)) return []
+		if (!Number.isFinite(v)) return null
 	}
 
 	let sumX = 0
@@ -23,14 +32,30 @@ export function linearRegressionTrend(values: number[]): number[] {
 	}
 
 	const denom = n * sumX2 - sumX * sumX
-	if (denom === 0) return []
+	if (denom === 0) return null
 
 	const slope = (n * sumXY - sumX * sumY) / denom
 	const intercept = (sumY - slope * sumX) / n
+	const mean = sumY / n
 
-	const out: number[] = []
+	const fitted: number[] = []
+	let ssRes = 0
+	let ssTot = 0
 	for (let i = 0; i < n; i++) {
-		out.push(intercept + slope * i)
+		const y = values[i]!
+		const f = intercept + slope * i
+		fitted.push(f)
+		ssRes += (y - f) ** 2
+		ssTot += (y - mean) ** 2
 	}
-	return out
+
+	return { slope, intercept, r2: ssTot === 0 ? 1 : 1 - ssRes / ssTot, fitted }
+}
+
+/**
+ * Fitted y for each index of `values` (see `linearRegression`), or [] if n < 2
+ * or any input is non-finite.
+ */
+export function linearRegressionTrend(values: number[]): number[] {
+	return linearRegression(values)?.fitted ?? []
 }

package/src/math/scale.ts

@@ -0,0 +1,17 @@
+export function clamp(value: number, min: number, max: number): number {
+	return Math.min(max, Math.max(min, value))
+}
+
+/** Linear interpolation: `t = 0` → `start`, `t = 1` → `end`. */
+export function lerp(start: number, end: number, t: number): number {
+	return start + (end - start) * t
+}
+
+/**
+ * Position of `value` within `[min, max]` as 0..1 (clamped). Returns 0 when
+ * the range is empty.
+ */
+export function normalize(value: number, min: number, max: number): number {
+	if (max <= min) return 0
+	return clamp((value - min) / (max - min), 0, 1)
+}