hanzio 1.2.0 → 2.0.0

package/src/array/index.ts

@@ -1,9 +1,20 @@
+import { stableStringify } from '../string'
+
 export interface ArrayDifference<TCurrent, TNext> {
 	new: TNext[]
+	/** Items present in both arrays (`update` + `unchanged`). */
 	upsert: TNext[]
 	delete: TCurrent[]
 }
 
+export interface ArrayDifferenceWithChanges<TCurrent, TNext>
+	extends ArrayDifference<TCurrent, TNext> {
+	/** Matched items where `isEqual` returned false. */
+	update: TNext[]
+	/** Matched items where `isEqual` returned true. */
+	unchanged: TNext[]
+}
+
 type PropertyKeyValue = string | number | symbol
 type NonNullableValue<T> = T extends null | undefined ? never : T
 type ItemsMatchingKeyValue<T, TKey extends keyof T, TValue> = [
@@ -25,51 +36,79 @@ export function chunkArray<T>(array: readonly T[], chunkSize: number): T[][] {
 	return chunks
 }
 
-export function findArrayDifferenceByKey<
-	TCurrent,
-	TNext,
-	TKey extends keyof TCurrent & keyof TNext
->(
+type DifferenceKey<TCurrent, TNext> =
+	| (keyof TCurrent & keyof TNext)
+	| ((item: TCurrent | TNext) => unknown)
+
+/**
+ * Splits `next` into items that are new or also in `current` (`upsert`), and
+ * lists the `current` items missing from `next` (`delete`). Items match by a
+ * shared key name or a key function; key values are compared as strings.
+ * Pass `isEqual` to also split `upsert` into `update` and `unchanged`.
+ */
+export function findArrayDifferenceByKey<TCurrent, TNext>(
 	current: readonly TCurrent[],
 	next: readonly TNext[],
-	key: TKey
-): ArrayDifference<TCurrent, TNext> {
-	const currentByKey = new Map(
-		current.map((item) => [String(item[key]), item] as const)
-	)
-	const itemsToDelete = [...current]
+	key: DifferenceKey<TCurrent, TNext>,
+	options: { isEqual: (current: TCurrent, next: TNext) => boolean }
+): ArrayDifferenceWithChanges<TCurrent, TNext>
+export function findArrayDifferenceByKey<TCurrent, TNext>(
+	current: readonly TCurrent[],
+	next: readonly TNext[],
+	key: DifferenceKey<TCurrent, TNext>,
+	options?: { isEqual?: (current: TCurrent, next: TNext) => boolean }
+): ArrayDifference<TCurrent, TNext>
+export function findArrayDifferenceByKey<TCurrent, TNext>(
+	current: readonly TCurrent[],
+	next: readonly TNext[],
+	key: DifferenceKey<TCurrent, TNext>,
+	options: { isEqual?: (current: TCurrent, next: TNext) => boolean } = {}
+):
+	| ArrayDifference<TCurrent, TNext>
+	| ArrayDifferenceWithChanges<TCurrent, TNext> {
+	const { isEqual } = options
+	const getKey = (item: TCurrent | TNext) =>
+		String(typeof key === 'function' ? key(item) : item[key])
+	const currentByKey = new Map(current.map((item) => [getKey(item), item]))
+	const matchedKeys = new Set<string>()
 	const newItems: TNext[] = []
 	const upsertItems: TNext[] = []
+	const updateItems: TNext[] = []
+	const unchangedItems: TNext[] = []
 
 	for (const item of next) {
-		const keyValue = String(item[key])
-
-		if (!currentByKey.has(keyValue)) {
+		const itemKey = getKey(item)
+		if (!currentByKey.has(itemKey)) {
 			newItems.push(item)
 			continue
 		}
 
+		matchedKeys.add(itemKey)
 		upsertItems.push(item)
-		const deleteIndex = itemsToDelete.findIndex(
-			(currentItem) => String(currentItem[key]) === keyValue
-		)
-		if (deleteIndex >= 0) {
-			itemsToDelete.splice(deleteIndex, 1)
+		if (isEqual) {
+			const target = isEqual(currentByKey.get(itemKey) as TCurrent, item)
+				? unchangedItems
+				: updateItems
+			target.push(item)
 		}
 	}
 
-	return {
+	const difference = {
 		new: newItems,
 		upsert: upsertItems,
-		delete: itemsToDelete
+		delete: current.filter((item) => !matchedKeys.has(getKey(item)))
 	}
+
+	return isEqual
+		? { ...difference, update: updateItems, unchanged: unchangedItems }
+		: difference
 }
 
 export function getUniqueValues<T>(array: readonly T[]): T[] {
 	const seen = new Map<string, T>()
 
 	for (const element of array) {
-		const key = JSON.stringify(element)
+		const key = stableStringify(element)
 		if (!seen.has(key)) {
 			seen.set(key, element)
 		}
@@ -82,15 +121,15 @@ export function compact<T>(array: readonly T[]): NonNullableValue<T>[] {
 	return array.filter((item): item is NonNullableValue<T> => item != null)
 }
 
-export function getUniqueValuesByKey<T, TKey extends keyof T>(
+export function getUniqueValuesByKey<T>(
 	array: readonly T[],
-	key: TKey
+	keyOrFn: keyof T | ((item: T) => unknown)
 ): T[] {
-	const seen = new Set<T[TKey]>()
+	const seen = new Set<unknown>()
 	const result: T[] = []
 
 	for (const item of array) {
-		const value = item[key]
+		const value = typeof keyOrFn === 'function' ? keyOrFn(item) : item[keyOrFn]
 		if (seen.has(value)) continue
 		seen.add(value)
 		result.push(item)
@@ -103,28 +142,53 @@ export function groupBy<
 	T,
 	TKey extends keyof T,
 	TGroupKey extends Extract<T[TKey], PropertyKeyValue>
->(array: readonly T[], key: TKey): Record<TGroupKey, T[]>
+>(array: readonly T[], key: TKey): Partial<Record<TGroupKey, T[]>>
 export function groupBy<T, TGroupKey extends PropertyKeyValue>(
 	array: readonly T[],
 	keyFn: (item: T) => TGroupKey
-): Record<TGroupKey, T[]>
+): Partial<Record<TGroupKey, T[]>>
 export function groupBy<T, TGroupKey extends PropertyKeyValue>(
 	array: readonly T[],
 	keyOrFn: keyof T | ((item: T) => TGroupKey)
-): Record<TGroupKey, T[]> {
-	return array.reduce(
-		(result, item) => {
-			const groupKey =
-				typeof keyOrFn === 'function'
-					? keyOrFn(item)
-					: (item[keyOrFn] as TGroupKey)
-
-			result[groupKey] ??= []
-			result[groupKey].push(item)
-			return result
-		},
-		{} as Record<TGroupKey, T[]>
-	)
+): Partial<Record<TGroupKey, T[]>> {
+	const result: Partial<Record<TGroupKey, T[]>> = {}
+
+	for (const item of array) {
+		const groupKey =
+			typeof keyOrFn === 'function'
+				? keyOrFn(item)
+				: (item[keyOrFn] as TGroupKey)
+		result[groupKey] ??= []
+		result[groupKey].push(item)
+	}
+
+	return result
+}
+
+export function countBy<
+	T,
+	TKey extends keyof T,
+	TGroupKey extends Extract<T[TKey], PropertyKeyValue>
+>(array: readonly T[], key: TKey): Partial<Record<TGroupKey, number>>
+export function countBy<T, TGroupKey extends PropertyKeyValue>(
+	array: readonly T[],
+	keyFn: (item: T) => TGroupKey
+): Partial<Record<TGroupKey, number>>
+export function countBy<T, TGroupKey extends PropertyKeyValue>(
+	array: readonly T[],
+	keyOrFn: keyof T | ((item: T) => TGroupKey)
+): Partial<Record<TGroupKey, number>> {
+	const result: Partial<Record<TGroupKey, number>> = {}
+
+	for (const item of array) {
+		const groupKey =
+			typeof keyOrFn === 'function'
+				? keyOrFn(item)
+				: (item[keyOrFn] as TGroupKey)
+		result[groupKey] = (result[groupKey] ?? 0) + 1
+	}
+
+	return result
 }
 
 export function keyBy<
@@ -185,3 +249,92 @@ export function pickItemsInArray<
 			values.includes(item[key])
 	)
 }
+
+/** Wraps a single value in an array; `null`/`undefined` become `[]`. Arrays are copied. */
+export function toArray<T>(value: T | readonly T[] | null | undefined): T[] {
+	if (value == null) return []
+	if (Array.isArray(value)) return [...(value as readonly T[])]
+	return [value as T]
+}
+
+type NumericKey<T> = {
+	[K in keyof T]: T[K] extends number | null | undefined ? K : never
+}[keyof T]
+
+/** Sums a numeric property or callback result; nullish values count as 0. */
+export function sumBy<T>(
+	array: readonly T[],
+	fn: (item: T) => number | null | undefined
+): number
+export function sumBy<T>(array: readonly T[], key: NumericKey<T>): number
+export function sumBy<T>(
+	array: readonly T[],
+	keyOrFn: NumericKey<T> | ((item: T) => number | null | undefined)
+): number {
+	let sum = 0
+	for (const item of array) {
+		const value =
+			typeof keyOrFn === 'function'
+				? keyOrFn(item)
+				: (item[keyOrFn] as number | null | undefined)
+		sum += value ?? 0
+	}
+	return sum
+}
+
+type SortSelector<T> = keyof T | ((item: T) => unknown)
+export type SortCriterion<T> =
+	| SortSelector<T>
+	| { by: SortSelector<T>; order: 'asc' | 'desc' }
+
+/**
+ * Returns a sorted copy. Each criterion is a key, a callback, or
+ * `{ by, order }`; later criteria break ties. The sort is stable, and
+ * `null`/`undefined` values always go last. Without criteria the items
+ * themselves are compared.
+ */
+export function sortBy<T>(
+	array: readonly T[],
+	...criteria: SortCriterion<T>[]
+): T[] {
+	const comparators = (criteria.length ? criteria : [(item: T) => item]).map(
+		(criterion) => {
+			const { by, order } =
+				typeof criterion === 'object'
+					? criterion
+					: { by: criterion, order: 'asc' as const }
+			const select = (item: T) =>
+				typeof by === 'function' ? by(item) : item[by as keyof T]
+			const direction = order === 'desc' ? -1 : 1
+
+			return (left: T, right: T) => {
+				const a = select(left) as number
+				const b = select(right) as number
+				if (a == null || b == null) return a == null ? (b == null ? 0 : 1) : -1
+				return a < b ? -direction : a > b ? direction : 0
+			}
+		}
+	)
+
+	return [...array].sort((left, right) => {
+		for (const compare of comparators) {
+			const result = compare(left, right)
+			if (result !== 0) return result
+		}
+		return 0
+	})
+}
+
+/**
+ * Numbers from `start` up to (not including) `end`. With one argument it
+ * counts from 0. `step` defaults to 1, or -1 when `end < start`.
+ */
+export function range(start: number, end?: number, step?: number): number[] {
+	const from = end === undefined ? 0 : start
+	const to = end ?? start
+	const increment = step ?? (to < from ? -1 : 1)
+	if (increment === 0) throw new Error('Step must not be zero')
+
+	const length = Math.max(Math.ceil((to - from) / increment), 0)
+	return Array.from({ length }, (_, index) => from + index * increment)
+}

package/src/cache/createCache.ts

@@ -0,0 +1,157 @@
+type Entry = {
+	value?: unknown
+	hasValue: boolean
+	expiresAt?: number
+	/** `expiresAt - staleMarginMs`: getOrSet refreshes from here on. */
+	refreshAt?: number
+	inflight?: Promise<unknown>
+}
+
+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 function createCache(options: CreateCacheOptions = {}): KeyValueCache {
+	const {
+		defaultTtlMs,
+		staleMarginMs: defaultStaleMarginMs = 0,
+		maxEntries,
+		now = Date.now
+	} = options
+	const store = new Map<string, Entry>()
+
+	// Stores `value` on `entry` with an expiry counted from `startedAt`.
+	const fill = <T>(
+		entry: Entry,
+		value: T,
+		startedAt: number,
+		setOptions: CacheSetOptions<T> = {}
+	) => {
+		const { ttlMs = defaultTtlMs, staleMarginMs = defaultStaleMarginMs } =
+			setOptions
+		const ttl = typeof ttlMs === 'function' ? ttlMs(value) : ttlMs
+		entry.value = value
+		entry.hasValue = true
+		entry.expiresAt = ttl === undefined ? undefined : startedAt + ttl
+		entry.refreshAt =
+			entry.expiresAt === undefined
+				? undefined
+				: entry.expiresAt - staleMarginMs
+		return entry
+	}
+
+	const isExpired = (entry: Entry) =>
+		entry.expiresAt !== undefined && entry.expiresAt <= now()
+
+	const hasFreshValue = (entry: Entry | undefined) =>
+		entry?.hasValue === true && !isExpired(entry)
+
+	// Map keeps insertion order, so re-inserting on access makes the first key
+	// the least recently used.
+	const touch = (key: string, entry: Entry) => {
+		store.delete(key)
+		store.set(key, entry)
+		if (maxEntries !== undefined) {
+			while (store.size > maxEntries) {
+				store.delete(store.keys().next().value as string)
+			}
+		}
+	}
+
+	const read = (key: string): Entry | undefined => {
+		const entry = store.get(key)
+		if (!entry) return undefined
+		if (isExpired(entry) && !entry.inflight) {
+			store.delete(key)
+			return undefined
+		}
+		touch(key, entry)
+		return entry
+	}
+
+	return {
+		async getOrSet<T>(
+			key: string,
+			fn: () => Promise<T> | T,
+			setOptions?: CacheSetOptions<T>
+		): Promise<T> {
+			const existing = read(key)
+			if (existing?.inflight) return existing.inflight as Promise<T>
+			const isStale =
+				existing?.refreshAt !== undefined && existing.refreshAt <= now()
+			if (existing?.hasValue && !isStale) return existing.value as T
+
+			// Refresh in place so get() keeps serving a stale value meanwhile.
+			const entry: Entry = existing ?? { hasValue: false }
+			const startedAt = now()
+			const promise = (async () => fn())()
+			entry.inflight = promise
+			touch(key, entry)
+
+			try {
+				const value = await promise
+				fill(entry, value, startedAt, setOptions)
+				return value
+			} catch (error) {
+				if (!hasFreshValue(entry) && store.get(key) === entry) {
+					store.delete(key)
+				}
+				throw error
+			} finally {
+				entry.inflight = undefined
+			}
+		},
+		get<T>(key: string): T | undefined {
+			const entry = read(key)
+			return hasFreshValue(entry) ? (entry?.value as T) : undefined
+		},
+		has(key: string): boolean {
+			return hasFreshValue(read(key))
+		},
+		set<T>(key: string, value: T, setOptions?: CacheSetOptions<T>): void {
+			touch(key, fill({ hasValue: false }, value, now(), setOptions))
+		},
+		delete(key: string): void {
+			store.delete(key)
+		},
+		clear(): void {
+			store.clear()
+		},
+		get size() {
+			return store.size
+		}
+	}
+}