hanzio 1.2.0 → 2.1.0

package/src/object/index.ts

@@ -0,0 +1,99 @@
+/** `Object.keys` typed as the object's string keys. */
+export function typedKeys<T extends object>(object: T): (keyof T & string)[] {
+	return Object.keys(object) as (keyof T & string)[]
+}
+
+/** `Object.entries` typed as `[key, value]` pairs per key. */
+export function typedEntries<T extends object>(
+	object: T
+): { [K in keyof T & string]: [K, T[K]] }[keyof T & string][] {
+	return Object.entries(object) as {
+		[K in keyof T & string]: [K, T[K]]
+	}[keyof T & string][]
+}
+
+/** `Object.fromEntries` typed as `Record<K, V>`. */
+export function typedFromEntries<const K extends PropertyKey, V>(
+	entries: Iterable<readonly [K, V]>
+): Record<K, V> {
+	return Object.fromEntries(entries) as Record<K, V>
+}
+
+/** Builds a record with one entry per key. */
+export function recordFromKeys<const K extends PropertyKey, V>(
+	keys: readonly K[],
+	fn: (key: K) => V
+): Record<K, V> {
+	return typedFromEntries(keys.map((key) => [key, fn(key)] as const))
+}
+
+export function mapValues<T extends object, R>(
+	object: T,
+	fn: (value: T[keyof T & string], key: keyof T & string) => R
+): Record<keyof T & string, R> {
+	return typedFromEntries(
+		typedEntries(object).map(([key, value]) => [key, fn(value, key)] as const)
+	)
+}
+
+export function pick<T extends object, const K extends keyof T>(
+	object: T,
+	keys: readonly K[]
+): Pick<T, K> {
+	const result = {} as Pick<T, K>
+	for (const key of keys) {
+		if (key in object) result[key] = object[key]
+	}
+	return result
+}
+
+export function omit<T extends object, const K extends keyof T>(
+	object: T,
+	keys: readonly K[]
+): Omit<T, K> {
+	const result = { ...object }
+	for (const key of keys) delete result[key]
+	return result
+}
+
+type Path = string | readonly (string | number)[]
+
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+function toPath(path: Path): readonly (string | number)[] {
+	if (typeof path !== 'string') return path
+	return path === '' ? [] : path.split('.')
+}
+
+/** Reads a nested value by dot path (`a.b.0.c`) or segment array; undefined when missing. */
+export function getAtPath(object: unknown, path: Path): unknown {
+	let current = object
+	for (const key of toPath(path)) {
+		if (current === null || typeof current !== 'object') return undefined
+		current = (current as Record<PropertyKey, unknown>)[key]
+	}
+	return current
+}
+
+/** Writes a nested value in place, creating arrays for numeric segments and objects otherwise. */
+export function setAtPath(object: object, path: Path, value: unknown): void {
+	const keys = toPath(path)
+	if (keys.length === 0) throw new Error('Path must not be empty')
+	for (const key of keys) {
+		if (UNSAFE_KEYS.has(String(key))) {
+			throw new Error(`Unsafe path segment: ${key}`)
+		}
+	}
+
+	let current = object as Record<PropertyKey, unknown>
+	for (let index = 0; index < keys.length - 1; index++) {
+		const key = keys[index]!
+		let next = current[key]
+		if (next === null || typeof next !== 'object') {
+			next = /^\d+$/.test(String(keys[index + 1])) ? [] : {}
+			current[key] = next
+		}
+		current = next as Record<PropertyKey, unknown>
+	}
+	current[keys.at(-1)!] = value
+}

package/src/p-queue/index.ts

@@ -688,3 +688,5 @@ export default class PQueue<
 		}
 	}
 }
+
+export { PQueue }

package/src/promise/index.ts

@@ -5,27 +5,37 @@ export type BackgroundPromiseOptions = {
 }
 
 export type Success<T> = {
+	ok: true
 	data: T
 	error: null
 }
 
 export type Failure<E> = {
+	ok: false
 	data: null
 	error: E
 }
 
 export type Result<T, E = Error> = Success<T> | Failure<E>
 
+export function ok<T>(data: T): Success<T> {
+	return { ok: true, data, error: null }
+}
+
+export function err<E>(error: E): Failure<E> {
+	return { ok: false, data: null, error }
+}
+
 export function isSuccess<T, E>(result: Result<T, E>): result is Success<T> {
-	return result.error === null
+	return result.ok
 }
 
 export function isFailure<T, E>(result: Result<T, E>): result is Failure<E> {
-	return result.error !== null
+	return !result.ok
 }
 
 export function unwrapResult<T, E>(result: Result<T, E>): T {
-	if (isSuccess(result)) return result.data
+	if (result.ok) return result.data
 	throw result.error
 }
 
@@ -57,17 +67,302 @@ export function backgroundPromiseSync<T>(
 	})
 }
 
-export function promiseTimeout(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms))
+/** Resolves after `ms`; rejects with `signal.reason` if the signal aborts first. */
+export function promiseTimeout(
+	ms: number,
+	options: { signal?: AbortSignal } = {}
+): Promise<void> {
+	const { signal } = options
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason)
+			return
+		}
+		const onAbort = () => {
+			clearTimeout(timer)
+			reject(signal?.reason)
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener('abort', onAbort)
+			resolve()
+		}, ms)
+		signal?.addEventListener('abort', onAbort, { once: true })
+	})
 }
 
+/**
+ * Accepts a promise or a function; sync throws inside the function are
+ * captured too.
+ */
 export async function tryCatch<T, E = Error>(
-	promise: Promise<T>
+	input: Promise<T> | (() => T | Promise<T>)
 ): Promise<Result<T, E>> {
 	try {
-		const data = await promise
-		return { data, error: null }
+		return ok(await (typeof input === 'function' ? input() : input))
 	} catch (error) {
-		return { data: null, error: error as E }
+		return err(error as E)
+	}
+}
+
+export class PromiseTimeoutError extends Error {
+	readonly timeoutMs: number
+
+	constructor(timeoutMs: number, message?: string) {
+		super(message ?? `Promise timed out after ${timeoutMs}ms`)
+		this.name = 'PromiseTimeoutError'
+		this.timeoutMs = timeoutMs
+	}
+}
+
+/**
+ * Rejects with `PromiseTimeoutError` after `ms`, or with `signal.reason` when
+ * the signal aborts. Pass a function to receive a signal that aborts on
+ * timeout, so the underlying work can stop too.
+ */
+export async function withTimeout<T>(
+	input: Promise<T> | ((signal: AbortSignal) => Promise<T>),
+	ms: number,
+	options: { signal?: AbortSignal; message?: string } = {}
+): Promise<T> {
+	const controller = new AbortController()
+	const onAbort = () => controller.abort(options.signal?.reason)
+	if (options.signal?.aborted) onAbort()
+	else options.signal?.addEventListener('abort', onAbort, { once: true })
+
+	const timer = setTimeout(
+		() => controller.abort(new PromiseTimeoutError(ms, options.message)),
+		ms
+	)
+	let rejectOnAbort: () => void = () => {}
+
+	try {
+		const aborted = new Promise<never>((_, reject) => {
+			rejectOnAbort = () => reject(controller.signal.reason)
+			controller.signal.addEventListener('abort', rejectOnAbort, { once: true })
+		})
+		if (controller.signal.aborted) throw controller.signal.reason
+
+		const promise =
+			typeof input === 'function' ? input(controller.signal) : input
+		return await Promise.race([promise, aborted])
+	} finally {
+		clearTimeout(timer)
+		options.signal?.removeEventListener('abort', onAbort)
+		controller.signal.removeEventListener('abort', rejectOnAbort)
+	}
+}
+
+export type BackoffOptions = {
+	/** Delay for the first retry (default 300ms). */
+	baseMs?: number
+	/** Upper bound for any delay (default 30s). */
+	maxMs?: number
+	/**
+	 * `true`/`'full'`: random delay in [0, computed] (default).
+	 * `'partial'`: computed plus 0–`jitterRatio` extra (may exceed `maxMs`).
+	 */
+	jitter?: boolean | 'full' | 'partial'
+	/** Max extra fraction for `'partial'` jitter (default 0.25). */
+	jitterRatio?: number
+	/** Source of randomness in [0, 1) (default `Math.random`). */
+	random?: () => number
+}
+
+/** Exponential backoff delay for a 1-based retry attempt. */
+export function exponentialBackoff(
+	attempt: number,
+	options: BackoffOptions = {}
+): number {
+	const {
+		baseMs = 300,
+		maxMs = 30_000,
+		jitter = true,
+		jitterRatio = 0.25,
+		random = Math.random
+	} = options
+	const delay = Math.min(maxMs, baseMs * 2 ** Math.max(0, attempt - 1))
+	if (jitter === 'partial')
+		return Math.round(delay * (1 + jitterRatio * random()))
+	return jitter ? Math.round(random() * delay) : delay
+}
+
+export type RetryOptions = {
+	/** Retries after the first attempt (default 3). */
+	retries?: number
+	/** Delay before retry `attempt` (1-based). Default: `exponentialBackoff`. */
+	delayMs?: number | ((attempt: number, error: unknown) => number)
+	/** Return false to stop retrying and rethrow (default: always retry). */
+	shouldRetry?: (error: unknown, attempt: number) => boolean
+	onRetry?: (error: unknown, attempt: number, delayMs: number) => void
+	signal?: AbortSignal
+}
+
+export async function retry<T>(
+	fn: (context: { attempt: number; signal?: AbortSignal }) => Promise<T> | T,
+	options: RetryOptions = {}
+): Promise<T> {
+	const { retries = 3, delayMs, shouldRetry, onRetry, signal } = options
+
+	for (let attempt = 0; ; attempt++) {
+		signal?.throwIfAborted()
+		try {
+			return await fn({ attempt, signal })
+		} catch (error) {
+			const nextAttempt = attempt + 1
+			if (attempt >= retries || shouldRetry?.(error, nextAttempt) === false) {
+				throw error
+			}
+			const delay =
+				delayMs === undefined
+					? exponentialBackoff(nextAttempt)
+					: typeof delayMs === 'function'
+						? delayMs(nextAttempt, error)
+						: delayMs
+			onRetry?.(error, nextAttempt, delay)
+			await promiseTimeout(delay, { signal })
+		}
+	}
+}
+
+/** Maps with bounded concurrency; results keep input order. */
+export async function pMap<T, R>(
+	items: Iterable<T>,
+	fn: (item: T, index: number) => Promise<R> | R,
+	options: { concurrency?: number; signal?: AbortSignal } = {}
+): Promise<R[]> {
+	const { concurrency = Number.POSITIVE_INFINITY, signal } = options
+	if (!(concurrency >= 1)) {
+		throw new Error('Concurrency must be at least 1')
+	}
+
+	const list = [...items]
+	const results = new Array<R>(list.length)
+	let next = 0
+
+	const worker = async () => {
+		while (next < list.length) {
+			signal?.throwIfAborted()
+			const index = next++
+			results[index] = await fn(list[index]!, index)
+		}
+	}
+
+	await Promise.all(
+		Array.from({ length: Math.min(concurrency, list.length) }, worker)
+	)
+	return results
+}
+
+const clock = (): number => globalThis.performance?.now() ?? Date.now()
+
+/** Starts a clock; call the returned function to read elapsed ms. */
+export function startTimer(): () => number {
+	const start = clock()
+	return () => clock() - start
+}
+
+/** Runs `fn` and reports how long it took (throws pass through). */
+export async function timed<T>(
+	fn: () => Promise<T> | T
+): Promise<{ result: T; durationMs: number }> {
+	const elapsed = startTimer()
+	const result = await fn()
+	return { result, durationMs: elapsed() }
+}
+
+/**
+ * Aborts when any input aborts, with that signal's `reason`. Undefined inputs
+ * are skipped; no inputs gives a signal that never aborts.
+ */
+export function anySignal(
+	...signals: (AbortSignal | undefined)[]
+): AbortSignal {
+	const list = signals.filter((signal) => signal !== undefined)
+	if (list.length === 1) return list[0]!
+	if (typeof AbortSignal.any === 'function') return AbortSignal.any(list)
+
+	// ponytail: fallback keeps listeners on inputs until one aborts (no WeakRef).
+	const controller = new AbortController()
+	const aborted = list.find((signal) => signal.aborted)
+	if (aborted) {
+		controller.abort(aborted.reason)
+		return controller.signal
+	}
+	const onAbort = (event: Event) => {
+		for (const signal of list) signal.removeEventListener('abort', onAbort)
+		controller.abort((event.target as AbortSignal).reason)
+	}
+	for (const signal of list) signal.addEventListener('abort', onAbort)
+	return controller.signal
+}
+
+/** Aborts with a `TimeoutError` after `ms`, or earlier if `signal` aborts. */
+export function timeoutSignal(ms: number, signal?: AbortSignal): AbortSignal {
+	if (typeof AbortSignal.timeout === 'function') {
+		return anySignal(AbortSignal.timeout(ms), signal)
+	}
+	const controller = new AbortController()
+	setTimeout(() => {
+		const reason = new Error('The operation timed out.')
+		reason.name = 'TimeoutError'
+		controller.abort(reason)
+	}, ms)
+	return anySignal(controller.signal, signal)
+}
+
+/**
+ * Settles like `promise`, but rejects with `signal.reason` as soon as the
+ * signal aborts. The underlying work is not cancelled.
+ */
+export async function raceAbort<T>(
+	promise: Promise<T>,
+	signal: AbortSignal | undefined
+): Promise<T> {
+	if (!signal) return promise
+	let onAbort = () => {}
+	const aborted = new Promise<never>((_, reject) => {
+		onAbort = () => reject(signal.reason)
+		if (signal.aborted) onAbort()
+		else signal.addEventListener('abort', onAbort, { once: true })
+	})
+	try {
+		return await Promise.race([aborted, promise])
+	} finally {
+		signal.removeEventListener('abort', onAbort)
+	}
+}
+
+export type LatestGuard = {
+	/** Starts a new generation; earlier tokens become stale. */
+	next(): number
+	isCurrent(token: number): boolean
+	/** Marks every outstanding token stale. */
+	invalidate(): void
+	/** Runs `fn` under a new token; stale results and errors become `{ stale: true }`. */
+	run<T>(
+		fn: () => Promise<T> | T
+	): Promise<{ stale: true } | { stale: false; value: T }>
+}
+
+/** Ignores results of async work superseded by a newer call. */
+export function createLatestGuard(): LatestGuard {
+	let current = 0
+	const isCurrent = (token: number) => token === current
+	return {
+		next: () => ++current,
+		isCurrent,
+		invalidate: () => {
+			current++
+		},
+		async run(fn) {
+			const token = ++current
+			try {
+				const value = await fn()
+				return isCurrent(token) ? { stale: false, value } : { stale: true }
+			} catch (error) {
+				if (!isCurrent(token)) return { stale: true }
+				throw error
+			}
+		}
 	}
 }

package/src/secrets/core.ts

@@ -68,6 +68,15 @@ export type SecretSet<K extends string, Parsed = Record<K, string>> = {
 	reload: (options?: SecretRequestOptions) => Promise<SecretSet<K, Parsed>>
 }
 
+/** A declaration that must be loaded explicitly before its values can be read. */
+export type LazySecretSet<
+	K extends string,
+	Parsed = Record<K, string>
+> = SecretSet<K, Parsed> & {
+	/** Initialize once. Concurrent calls share a load; use reload to refresh. */
+	load: (options?: SecretRequestOptions) => Promise<LazySecretSet<K, Parsed>>
+}
+
 // Shared across bundled entry points and package copies in the same JS realm.
 // Only helper-written values are registered; original environment overrides aren't.
 const registryKey = Symbol.for('hanzio.secrets.environmentWrites.v1')
@@ -118,21 +127,19 @@ function readOverrides<K extends string>(
 	) as Partial<Record<K, string>>
 }
 
-export async function defineSecretSet<
+export function createSecretSet<
 	const Keys extends readonly string[],
 	Parsed = Record<Keys[number], string>
 >(
 	keys: Keys,
 	options: CustomLoaderDefineSecretSetOptions<Keys[number], Parsed>,
 	environmentVariables?: EnvironmentVariables
-): Promise<SecretSet<Keys[number], Parsed>> {
+): LazySecretSet<Keys[number], Parsed> {
 	type K = Keys[number]
 
 	const keySet = [...new Set(keys)] as K[]
-	const environment = resolveSecretEnvironment(
-		options.environment,
-		environmentVariables
-	)
+	let environment: string | undefined
+	let initialized = false
 	const logger =
 		options.logger === false ? undefined : (options.logger ?? defaultLogger)
 
@@ -157,7 +164,8 @@ export async function defineSecretSet<
 	// Build, validate, and commit one snapshot under the caller’s deadline.
 	const loadSnapshot = async (
 		request: SecretRequestOptions,
-		signal: AbortSignal
+		signal: AbortSignal,
+		environment: string
 	) => {
 		// Fetch only keys that lack genuine local overrides.
 		const local = readOverrides(keySet, environmentVariables)
@@ -261,6 +269,7 @@ export async function defineSecretSet<
 		cached = next
 		parsed = nextParsed
 		sources = nextSources
+		initialized = true
 	}
 
 	const load = (request: SecretRequestOptions = {}): Promise<void> => {
@@ -273,12 +282,18 @@ export async function defineSecretSet<
 			const start = Date.now()
 
 			try {
+				environment ??= resolveSecretEnvironment(
+					options.environment,
+					environmentVariables
+				)
+				const resolvedEnvironment = environment
+
 				await withSecretDeadline(
 					{
 						timeoutMs: request.timeoutMs ?? options.timeoutMs,
 						signal: request.signal ?? options.signal
 					},
-					(signal) => loadSnapshot(request, signal)
+					(signal) => loadSnapshot(request, signal, resolvedEnvironment)
 				)
 
 				// Report the sources of committed values, not attempted fetches.
@@ -293,7 +308,7 @@ export async function defineSecretSet<
 				const counts = Object.fromEntries(sourceCounts)
 
 				log('info', 'Loaded secrets', {
-					environment,
+					environment: resolvedEnvironment,
 					count: keySet.length,
 					durationMs: Date.now() - start,
 					source: Object.keys(counts).join(' + ') || 'none',
@@ -306,7 +321,7 @@ export async function defineSecretSet<
 						: new SecretLoadError('LOADER', 'Secret loading failed.')
 
 				log('error', 'Secret loading failed', {
-					environment,
+					environment: environment ?? 'unresolved',
 					count: keySet.length,
 					durationMs: Date.now() - start,
 					code: safe.code
@@ -321,8 +336,19 @@ export async function defineSecretSet<
 		return inFlight
 	}
 
-	const secretSet: SecretSet<K, Parsed> = {
+	const assertLoaded = () => {
+		if (!initialized) {
+			throw new SecretLoadError(
+				'CONFIGURATION',
+				'Secret set has not been loaded. Await load() before reading values.'
+			)
+		}
+	}
+
+	const secretSet: LazySecretSet<K, Parsed> = {
 		secret(key) {
+			assertLoaded()
+
 			if (!Object.hasOwn(cached, key)) {
 				throw new SecretLoadError('MISSING_SECRETS', `Secret ${key} not found`)
 			}
@@ -331,9 +357,29 @@ export async function defineSecretSet<
 		},
 
 		// Return copies so consumers cannot mutate the internal snapshots.
-		secrets: () => ({ ...cached }),
-		parsed: () => structuredClone(parsed),
-		sources: () => ({ ...sources }),
+		secrets() {
+			assertLoaded()
+
+			return { ...cached }
+		},
+		parsed() {
+			assertLoaded()
+
+			return structuredClone(parsed)
+		},
+		sources() {
+			assertLoaded()
+
+			return { ...sources }
+		},
+
+		async load(request) {
+			if (!initialized) {
+				await load(request)
+			}
+
+			return secretSet
+		},
 
 		async reload(request) {
 			await load(request)
@@ -342,7 +388,17 @@ export async function defineSecretSet<
 		}
 	}
 
-	await load()
-
 	return secretSet
 }
+
+/** Compatibility API: declares and loads a complete snapshot before returning. */
+export async function defineSecretSet<
+	const Keys extends readonly string[],
+	Parsed = Record<Keys[number], string>
+>(
+	keys: Keys,
+	options: CustomLoaderDefineSecretSetOptions<Keys[number], Parsed>,
+	environmentVariables?: EnvironmentVariables
+): Promise<SecretSet<Keys[number], Parsed>> {
+	return createSecretSet(keys, options, environmentVariables).load()
+}

package/src/secrets/index.ts

@@ -1,5 +1,6 @@
 import {
-	defineSecretSet as defineCoreSecretSet,
+	createSecretSet as createCoreSecretSet,
+	type LazySecretSet,
 	type CommonSecretSetOptions,
 	type CustomLoaderDefineSecretSetOptions,
 	type SecretSet,
@@ -51,13 +52,13 @@ export function getSecretEnvironment(): SecretEnvironment {
 	) as SecretEnvironment
 }
 
-export async function defineSecretSet<
+export function createSecretSet<
 	const Keys extends readonly string[],
 	Parsed = Record<Keys[number], string>
 >(
 	keys: Keys,
 	options: DefineSecretSetOptions<Keys[number], Parsed>
-): Promise<SecretSet<Keys[number], Parsed>> {
+): LazySecretSet<Keys[number], Parsed> {
 	let loader: SecretSetLoader<Keys[number]>
 
 	if (!options.loader) {
@@ -69,7 +70,7 @@ export async function defineSecretSet<
 	}
 
 	// Supply process.env only from this Node/Bun entry point, keeping the core portable.
-	return defineCoreSecretSet(
+	return createCoreSecretSet(
 		keys,
 		{ ...options, loader },
 		getProcessEnvironment()
@@ -92,3 +93,14 @@ function createDefaultInfisicalLoader<K extends string, Parsed>(
 				options.clientSecretEnvKey ?? 'INFISICAL_CLIENT_SECRET'
 		})
 }
+
+/** Compatibility API: load immediately and fail before application startup. */
+export async function defineSecretSet<
+	const Keys extends readonly string[],
+	Parsed = Record<Keys[number], string>
+>(
+	keys: Keys,
+	options: DefineSecretSetOptions<Keys[number], Parsed>
+): Promise<SecretSet<Keys[number], Parsed>> {
+	return createSecretSet(keys, options).load()
+}