hanzio 1.0.0

package/src/cache/index.ts

@@ -0,0 +1,154 @@
+type CacheEntry<T> = {
+	value: T
+	timestamp: number
+}
+
+type AnyFunction = (...args: never[]) => unknown
+type CachedFunction<T extends AnyFunction> = {
+	(...args: Parameters<T>): ReturnType<T>
+	clearCache: () => void
+}
+
+export type CacheFunctionOptions<T extends AnyFunction> = {
+	name: string
+	fn: T
+	cacheTimeMs?: number
+	refreshInBackground?: boolean
+	cacheKeyArgs?: number[]
+	cacheKeyFn?: (...args: Parameters<T>) => unknown[]
+	/** Called when a background refresh fails (default: silent). */
+	onBackgroundRefreshError?: (error: unknown, context: { name: string }) => void
+}
+
+export function cacheFunction<T extends AnyFunction>(
+	options: CacheFunctionOptions<T>
+): CachedFunction<T> {
+	const {
+		name,
+		fn,
+		cacheTimeMs = 10 * 60 * 1000,
+		refreshInBackground = false,
+		cacheKeyArgs,
+		cacheKeyFn,
+		onBackgroundRefreshError
+	} = options
+
+	const cache = new Map<string, CacheEntry<ReturnType<T>>>()
+	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)
+				}
+			}
+		},
+		Math.min(cacheTimeMs / 2, 5 * 60 * 1000)
+	)
+
+	const wrappedFn = (...args: Parameters<T>): ReturnType<T> => {
+		const keyArgs = cacheKeyFn
+			? cacheKeyFn(...args)
+			: cacheKeyArgs
+				? cacheKeyArgs.map((i) => args[i])
+				: args
+		const key = `${name}:${JSON.stringify(keyArgs)}`
+		const now = Date.now()
+
+		const pending = pendingPromises.get(key)
+		if (pending) {
+			return pending as ReturnType<T>
+		}
+
+		const cached = cache.get(key)
+
+		if (cached) {
+			const isCacheFresh = now - cached.timestamp < cacheTimeMs
+
+			if (!isCacheFresh && !refreshInBackground) {
+				cache.delete(key)
+			} else {
+				if (isCacheFresh && !refreshInBackground) {
+					return cached.value
+				}
+
+				if (refreshInBackground) {
+					const existingPending = pendingPromises.get(key)
+					if (existingPending) {
+						return existingPending as ReturnType<T>
+					}
+
+					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
+						})
+					}
+
+					return cached.value
+				}
+
+				if (isCacheFresh) {
+					return cached.value
+				}
+			}
+		}
+
+		const result = fn(...args)
+
+		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
+				})
+
+			pendingPromises.set(key, promise)
+			return promise as ReturnType<T>
+		}
+
+		cache.set(key, { value: result as ReturnType<T>, timestamp: now })
+		return result as ReturnType<T>
+	}
+
+	wrappedFn.clearCache = () => {
+		cache.clear()
+		pendingPromises.clear()
+		clearInterval(cleanupInterval)
+	}
+
+	return wrappedFn
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		'then' in value &&
+		typeof value.then === 'function'
+	)
+}

package/src/date/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Calculate the previous period date range for a given period type.
+ */
+export function getPreviousReportPeriod(
+	periodType: 'MONTHLY' | 'QUARTERLY' | 'YEARLY',
+	referenceDate: Date = new Date()
+): { start: Date; end: Date } {
+	const month = referenceDate.getMonth()
+	const year = referenceDate.getFullYear()
+
+	switch (periodType) {
+		case 'MONTHLY': {
+			const prevMonth = month === 0 ? 11 : month - 1
+			const prevYear = month === 0 ? year - 1 : year
+			return {
+				start: new Date(prevYear, prevMonth, 1),
+				end: new Date(year, month, 0)
+			}
+		}
+		case 'QUARTERLY': {
+			const qStart = Math.floor(month / 3) * 3
+			const prevQStart = qStart === 0 ? 9 : qStart - 3
+			const prevQYear = qStart === 0 ? year - 1 : year
+			return {
+				start: new Date(prevQYear, prevQStart, 1),
+				end: new Date(prevQYear, prevQStart + 3, 0)
+			}
+		}
+		case 'YEARLY': {
+			return {
+				start: new Date(year - 1, 0, 1),
+				end: new Date(year - 1, 11, 31)
+			}
+		}
+	}
+}
+
+/**
+ * Format a date range as a human-readable period label.
+ */
+export function formatPeriodLabel(
+	start: Date | string,
+	end: Date | string,
+	includeDay = false
+): string {
+	const s = start instanceof Date ? start : new Date(start)
+	const e = end instanceof Date ? end : new Date(end)
+	const opts: Intl.DateTimeFormatOptions = {
+		year: 'numeric',
+		month: 'long',
+		...(includeDay && { day: 'numeric' })
+	}
+	return `${s.toLocaleDateString('en-GB', opts)} — ${e.toLocaleDateString('en-GB', opts)}`
+}

package/src/gzip/index.ts

@@ -0,0 +1,29 @@
+import pako from 'pako'
+
+export function compressString(input: string): string {
+	// Convert string to Uint8Array
+	const uint8Array = new TextEncoder().encode(input)
+
+	// Compress the Uint8Array
+	const compressed = pako.deflate(uint8Array)
+
+	// Convert compressed Uint8Array to base64 string for storage
+	return btoa(
+		String.fromCharCode.apply(null, compressed as unknown as number[])
+	)
+}
+
+export function decompressString(compressedString: string): string {
+	// Convert base64 string back to Uint8Array
+	const compressedData = new Uint8Array(
+		atob(compressedString)
+			.split('')
+			.map((char) => char.charCodeAt(0))
+	)
+
+	// Decompress the Uint8Array
+	const decompressed = pako.inflate(compressedData)
+
+	// Convert Uint8Array back to string
+	return new TextDecoder().decode(decompressed)
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from './typedswitch'
+export * from './array'
+export * from './string'
+export * from './promise'
+export * from './cache'
+export * from './state'
+export * from './math'
+export * from './date'
+export * from './url'
+export * from './zod'
+export * from './api-wrapper'
+export * from './p-queue'

package/src/jwt/index.ts

@@ -0,0 +1,25 @@
+import * as jose from 'jose'
+
+export async function jwtSign<_Payload extends object>(
+	payload: jose.JWTPayload,
+	secret: string
+) {
+	const secretKey = new TextEncoder().encode(secret)
+	return await new jose.SignJWT(payload)
+		.setProtectedHeader({ alg: 'HS256' })
+		.setIssuedAt()
+		.sign(secretKey)
+}
+
+export async function jwtVerify<Payload extends object>(
+	token: string,
+	secret: string
+): Promise<Payload | null> {
+	try {
+		const secretKey = new TextEncoder().encode(secret)
+		const { payload } = await jose.jwtVerify(token, secretKey)
+		return payload as Payload
+	} catch (_error) {
+		return null
+	}
+}

package/src/math/index.ts

@@ -0,0 +1,11 @@
+export { linearRegressionTrend } from './linearRegressionTrend'
+export {
+	createResolveColorsByKeys,
+	getHeatmapCellStyle,
+	hashStringToColorIndex,
+	METRICS_SERIES_PALETTE_SIZE,
+	type ResolveColorsByKeysResult,
+	resolveSeriesColorMap,
+	seriesColorKey,
+	withAlpha
+} from './metricsSeriesColors'

package/src/math/linearRegressionTrend.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export function linearRegressionTrend(values: number[]): number[] {
+	const n = values.length
+	if (n < 2) return []
+	for (const v of values) {
+		if (!Number.isFinite(v)) return []
+	}
+
+	let sumX = 0
+	let sumY = 0
+	let sumXY = 0
+	let sumX2 = 0
+	for (let i = 0; i < n; i++) {
+		const x = i
+		const y = values[i]!
+		sumX += x
+		sumY += y
+		sumXY += x * y
+		sumX2 += x * x
+	}
+
+	const denom = n * sumX2 - sumX * sumX
+	if (denom === 0) return []
+
+	const slope = (n * sumXY - sumX * sumY) / denom
+	const intercept = (sumY - slope * sumX) / n
+
+	const out: number[] = []
+	for (let i = 0; i < n; i++) {
+		out.push(intercept + slope * i)
+	}
+	return out
+}

package/src/math/metricsSeriesColors.ts

@@ -0,0 +1,208 @@
+/**
+ * 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.
+ */
+
+/** Matches PrimeVue semantic palette slot count (cyan…blue) and Expo SERIES_COLORS length */
+export const METRICS_SERIES_PALETTE_SIZE = 10
+
+/**
+ * FNV-1a 32-bit hash — stable palette index for a string key.
+ */
+export function hashStringToColorIndex(str: string): number {
+	let hash = 2166136261
+	for (let i = 0; i < str.length; i++) {
+		hash ^= str.charCodeAt(i)
+		hash = Math.imul(hash, 16777619)
+	}
+	return Math.abs(hash) % METRICS_SERIES_PALETTE_SIZE
+}
+
+function circularHueDistance(
+	a: number,
+	b: number,
+	paletteSize: number
+): number {
+	const diff = Math.abs(a - b)
+	return Math.min(diff, paletteSize - diff)
+}
+
+function pickHueMaxMinDistance(
+	candidates: number[],
+	used: Set<number>,
+	paletteSize: number
+): number {
+	let best = candidates[0] ?? 0
+	let bestScore = -1
+	for (const cand of candidates) {
+		let minD = paletteSize
+		for (const u of used) {
+			minD = Math.min(minD, circularHueDistance(cand, u, paletteSize))
+		}
+		if (minD > bestScore || (minD === bestScore && cand < best)) {
+			bestScore = minD
+			best = cand
+		}
+	}
+	return best
+}
+
+/**
+ * Prefer human-visible label so charts and tables agree on the same color key.
+ */
+export function seriesColorKey(label: string | undefined, key: string): string {
+	const fromLabel = label?.trim()
+	if (fromLabel) return fromLabel
+	return key.trim() || key
+}
+
+/**
+ * Map each distinct key to a palette index (hash preference, then max-min circular spacing).
+ */
+export function resolveSeriesColorMap(keys: string[]): Map<string, number> {
+	const result = new Map<string, number>()
+	const uniqueKeys = [...new Set(keys)]
+	if (uniqueKeys.length === 0) return result
+
+	const paletteSize = METRICS_SERIES_PALETTE_SIZE
+
+	if (uniqueKeys.length === 1) {
+		const only = uniqueKeys[0]!
+		result.set(only, hashStringToColorIndex(only))
+		return result
+	}
+
+	const usedIndices = new Set<number>()
+	const entries = uniqueKeys.map((key) => ({
+		key,
+		preferred: hashStringToColorIndex(key)
+	}))
+
+	for (const entry of entries) {
+		if (!usedIndices.has(entry.preferred)) {
+			result.set(entry.key, entry.preferred)
+			usedIndices.add(entry.preferred)
+		}
+	}
+
+	const unassigned = entries.filter((e) => !result.has(e.key))
+	for (const entry of unassigned) {
+		const unused: number[] = []
+		for (let i = 0; i < paletteSize; i++) {
+			if (!usedIndices.has(i)) unused.push(i)
+		}
+		const candidates =
+			unused.length > 0
+				? unused
+				: Array.from({ length: paletteSize }, (_, i) => i)
+		const idx = pickHueMaxMinDistance(candidates, usedIndices, paletteSize)
+		result.set(entry.key, idx)
+		usedIndices.add(idx)
+	}
+
+	return result
+}
+
+export type ResolveColorsByKeysResult = {
+	getColor: (key: string) => string
+	getHoverColor: (key: string) => string
+}
+
+/**
+ * Resolve stable colors per key using palette index → RGB/CSS from the caller.
+ */
+export function createResolveColorsByKeys(
+	keys: string[],
+	getSeriesColor: (index: number) => string,
+	getSeriesHoverColor: (index: number) => string
+): ResolveColorsByKeysResult {
+	const colorMap = resolveSeriesColorMap(keys)
+	return {
+		getColor: (key: string) =>
+			getSeriesColor(colorMap.get(key) ?? hashStringToColorIndex(key)),
+		getHoverColor: (key: string) =>
+			getSeriesHoverColor(colorMap.get(key) ?? hashStringToColorIndex(key))
+	}
+}
+
+function clamp(value: number, min: number, max: number): number {
+	return Math.min(max, Math.max(min, value))
+}
+
+/**
+ * Add alpha to hex, rgb(), or rgba() strings.
+ */
+export function withAlpha(color: string, alpha: number): string {
+	const trimmed = color.trim()
+
+	if (trimmed.startsWith('#')) {
+		const hex = trimmed.slice(1)
+		const normalized =
+			hex.length === 3
+				? hex
+						.split('')
+						.map((c) => c + c)
+						.join('')
+				: hex
+		if (normalized.length === 6) {
+			const r = Number.parseInt(normalized.slice(0, 2), 16)
+			const g = Number.parseInt(normalized.slice(2, 4), 16)
+			const b = Number.parseInt(normalized.slice(4, 6), 16)
+			return `rgba(${r}, ${g}, ${b}, ${alpha})`
+		}
+	}
+
+	if (trimmed.startsWith('rgb(')) {
+		return trimmed.replace('rgb(', 'rgba(').replace(')', `, ${alpha})`)
+	}
+
+	if (trimmed.startsWith('rgba(')) {
+		return trimmed.replace(/,\s*[\d.]+\)$/, `, ${alpha})`)
+	}
+
+	return trimmed
+}
+
+/**
+ * Heatmap cell background from normalized value intensity.
+ */
+export function getHeatmapCellStyle(params: {
+	value: number | null | undefined
+	min: number
+	max: number
+	baseColor: string
+	neutralColor?: string
+	minAlpha?: number
+	maxAlpha?: number
+}): Record<string, string> {
+	const {
+		value,
+		min,
+		max,
+		baseColor,
+		neutralColor,
+		minAlpha = 0.08,
+		maxAlpha = 0.78
+	} = params
+
+	if (value === null || value === undefined || Number.isNaN(value)) {
+		return {}
+	}
+
+	if (!Number.isFinite(min) || !Number.isFinite(max)) {
+		return {}
+	}
+
+	if (max <= min) {
+		return {
+			backgroundColor: withAlpha(neutralColor ?? baseColor, 0.32)
+		}
+	}
+
+	const normalized = clamp((value - min) / (max - min), 0, 1)
+	const alpha = minAlpha + (maxAlpha - minAlpha) * normalized
+
+	return {
+		backgroundColor: withAlpha(baseColor, alpha)
+	}
+}