hanzio 1.1.0 → 2.0.0

package/src/api-wrapper/actions-impl.ts

@@ -1,80 +1,18 @@
+import { createCache } from '../cache/createCache'
 import type { ActionCache, DefineAction } from './types'
 
-type CacheEntry = {
-	value?: unknown
-	hasValue: boolean
-	expiresAt?: number
-	inflight?: Promise<unknown>
-}
-
 export function createActionCache(): ActionCache {
-	const store = new Map<string, CacheEntry>()
-
-	const isExpired = (entry: CacheEntry) =>
-		entry.expiresAt !== undefined && entry.expiresAt <= Date.now()
-
-	const cache = (async <T>(
+	const store = createCache()
+	const cache = (<T>(
 		key: string,
 		fn: () => Promise<T> | T,
 		options?: { ttlMs?: number }
-	): Promise<T> => {
-		const existing = store.get(key)
-		if (existing && !isExpired(existing)) {
-			if (existing.inflight) return existing.inflight as Promise<T>
-			if (existing.hasValue) return existing.value as T
-		}
+	): Promise<T> => store.getOrSet(key, fn, options)) as ActionCache
 
-		const promise = (async () => fn())()
-		const entry: CacheEntry = {
-			hasValue: false,
-			inflight: promise,
-			expiresAt:
-				options?.ttlMs !== undefined ? Date.now() + options.ttlMs : undefined
-		}
-		store.set(key, entry)
-
-		try {
-			const value = await promise
-			entry.value = value
-			entry.hasValue = true
-			entry.inflight = undefined
-			return value
-		} catch (error) {
-			store.delete(key)
-			throw error
-		}
-	}) as ActionCache
-
-	cache.get = <T>(key: string): T | undefined => {
-		const entry = store.get(key)
-		if (!entry || !entry.hasValue) return undefined
-		if (isExpired(entry)) {
-			store.delete(key)
-			return undefined
-		}
-		return entry.value as T
-	}
-
-	cache.set = <T>(
-		key: string,
-		value: T,
-		options?: { ttlMs?: number }
-	): void => {
-		store.set(key, {
-			value,
-			hasValue: true,
-			expiresAt:
-				options?.ttlMs !== undefined ? Date.now() + options.ttlMs : undefined
-		})
-	}
-
-	cache.invalidate = (key: string): void => {
-		store.delete(key)
-	}
-
-	cache.clear = (): void => {
-		store.clear()
-	}
+	cache.get = (key) => store.get(key)
+	cache.set = (key, value, options) => store.set(key, value, options)
+	cache.invalidate = (key) => store.delete(key)
+	cache.clear = () => store.clear()
 
 	return cache
 }
@@ -87,10 +25,11 @@ export function makeDefineAction<TApi>(): DefineAction<TApi> {
 				noRuntimeInput: false as const
 			})
 		}
-		const def = args[0] as { handler: unknown }
+		const def = args[0] as { handler: unknown; input?: unknown }
 		return {
 			...def,
-			noRuntimeInput: true as const
+			// A schema-validated action takes input; a bare handler doesn't.
+			noRuntimeInput: def.input === undefined
 		}
 	}
 	return defineAction as DefineAction<TApi>

package/src/api-wrapper/builders.ts

@@ -1,4 +1,5 @@
 import { ZodError } from 'zod'
+import { buildQueryString } from '../url'
 import { type ConfigError, RequestValidationError } from './errors'
 import { normalizeHeaders } from './headers'
 import type {
@@ -9,70 +10,88 @@ import type {
 } from './shared'
 import type { ApiEndpoint } from './types'
 
-export function buildUrl(
-	endpoint: ApiEndpoint,
-	params: PathParams | undefined,
-	reqQuery: QueryParams | undefined,
-	baseApiUrls: Record<string, BaseApiUrl>,
-	defaultBaseApiUrl: string | undefined,
-	url: string | undefined,
+export type BuildUrlOptions = {
+	endpoint: ApiEndpoint
+	params: PathParams | undefined
+	queryParams: QueryParams
+	baseApiUrls: Record<string, BaseApiUrl>
+	defaultBaseApiUrl: string | undefined
+	url: string | undefined
+	doNotEncodeQueryParams?: boolean
 	configError: (msg: string) => ConfigError
-) {
+}
+
+export function buildUrl(options: BuildUrlOptions) {
+	const {
+		endpoint,
+		params,
+		queryParams,
+		baseApiUrls,
+		defaultBaseApiUrl,
+		url,
+		doNotEncodeQueryParams,
+		configError
+	} = options
+
+	let finalUrl: string
 	if (url) {
-		const finalUrl = replacePathParams(url, params, configError)
-		const queryString = new URLSearchParams(
-			buildQueryParamsRaw(endpoint, reqQuery)
-		).toString()
-		return {
-			finalUrl,
-			fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
+		finalUrl = replaceUrlPathParams(url, params, configError)
+	} else {
+		const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0]
+		if (!defaultBaseUrl) {
+			throw configError('At least one base API URL is required')
 		}
-	}
 
-	const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0]
-	if (!defaultBaseUrl) {
-		throw configError('At least one base API URL is required')
-	}
+		const baseUrlKey = endpoint.baseApiUrl ?? defaultBaseUrl
+		const configBaseUrl = baseApiUrls[baseUrlKey]
+		if (!configBaseUrl) {
+			throw configError(`Unknown base API URL: ${baseUrlKey}`)
+		}
 
-	const baseUrlKey = endpoint.baseApiUrl ?? defaultBaseUrl
-	const configBaseUrl = baseApiUrls[baseUrlKey]
-	if (!configBaseUrl) {
-		throw configError(`Unknown base API URL: ${baseUrlKey}`)
+		const baseUrl =
+			typeof configBaseUrl === 'function' ? configBaseUrl() : configBaseUrl
+		const path =
+			typeof endpoint.path === 'function'
+				? endpoint.path(baseUrl)
+				: endpoint.path
+		// Substitute endpoint parameters without interpreting a port or IPv6 host as one.
+		finalUrl = joinUrlPath(
+			baseUrl,
+			replacePathParams(path, params, configError)
+		)
 	}
 
-	const baseUrl =
-		typeof configBaseUrl === 'function' ? configBaseUrl() : configBaseUrl
-	const path =
-		typeof endpoint.path === 'function' ? endpoint.path(baseUrl) : endpoint.path
-	const finalUrl = replacePathParams(`${baseUrl}${path}`, params, configError)
-	const queryString = new URLSearchParams(
-		buildQueryParamsRaw(endpoint, reqQuery)
-	).toString()
-
+	const queryString = buildQueryString(queryParams, {
+		encode: !doNotEncodeQueryParams
+	})
 	return {
 		finalUrl,
 		fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
 	}
 }
 
-export function buildQueryParamsRaw(
+export function buildPathParams(
 	endpoint: ApiEndpoint,
-	query: QueryParams | undefined
-): Record<string, string> {
-	const defaultParams = endpoint.reqDefaultQueryParams ?? {}
-	const merged = { ...defaultParams, ...(query ?? {}) }
-	return Object.fromEntries(
-		Object.entries(merged)
-			.filter(([, value]) => value !== undefined)
-			.map(([key, value]) => [key, String(value)])
-	)
+	params: PathParams | undefined,
+	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
+): PathParams | undefined {
+	if (!endpoint.reqParamsSchema) return params
+
+	try {
+		return endpoint.reqParamsSchema.parse(params) as PathParams
+	} catch (error) {
+		if (error instanceof ZodError) {
+			throw new RequestValidationError(error, 'params', params, ctx())
+		}
+		throw error
+	}
 }
 
 export function buildQueryParams(
 	endpoint: ApiEndpoint,
 	query: QueryParams | undefined,
 	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
-): Record<string, string> {
+): QueryParams {
 	const defaultParams = endpoint.reqDefaultQueryParams ?? {}
 	let parsedQuery: QueryParams
 	if (endpoint.reqQuerySchema) {
@@ -87,13 +106,7 @@ export function buildQueryParams(
 	} else {
 		parsedQuery = query ?? {}
 	}
-	const merged = { ...defaultParams, ...parsedQuery }
-
-	return Object.fromEntries(
-		Object.entries(merged)
-			.filter(([, value]) => value !== undefined)
-			.map(([key, value]) => [key, String(value)])
-	)
+	return { ...defaultParams, ...parsedQuery }
 }
 
 export function buildRequestBody(
@@ -160,12 +173,31 @@ export function buildHeaders(
 	})
 }
 
+/** Joins with exactly one `/`; empty paths and query-only paths are appended as-is. */
+export function joinUrlPath(base: string, path: string): string {
+	if (!path || path.startsWith('?')) return `${base}${path}`
+	return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`
+}
+
+/** Substitutes `:params` in the path of a full URL only, so ports are left alone. */
+function replaceUrlPathParams(
+	url: string,
+	params: PathParams | undefined,
+	configError: (msg: string) => ConfigError
+): string {
+	const origin = url.match(/^[a-z][a-z\d+.-]*:\/\/[^/?#]*/i)?.[0] ?? ''
+	const rest = url.slice(origin.length)
+	const suffixIndex = rest.search(/[?#]/)
+	const path = suffixIndex === -1 ? rest : rest.slice(0, suffixIndex)
+	return `${origin}${replacePathParams(path, params, configError)}${rest.slice(path.length)}`
+}
+
 export function replacePathParams(
 	path: string,
 	params: PathParams | undefined,
 	configError: (msg: string) => ConfigError
 ): string {
-	return path.replace(/:(\w+)/g, (_, key: string) => {
+	return path.replace(/:([A-Za-z_]\w*)/g, (_, key: string) => {
 		const value = params?.[key]
 		if (value === undefined) {
 			throw configError(`Missing required path parameter: ${key}`)