@lovrozagar/honey 0.6.8 → 0.7.0

package/src/client/index.ts

@@ -7,9 +7,26 @@ import type { TypedWebSocket } from "./ws.ts"
 import { createTypedWebSocket } from "./ws.ts"
 
 export type { ClientErrorInit } from "./error.ts"
-export { ClientError, isClientError } from "./error.ts"
-export type { ClientConfig, RequestOptions } from "./http.ts"
+export {
+	BadGatewayError,
+	BadRequestError,
+	ClientError,
+	ConflictError,
+	ForbiddenError,
+	GatewayTimeoutError,
+	InternalServerError,
+	isClientError,
+	NotFoundError,
+	RateLimitError,
+	ServiceUnavailableError,
+	UnauthorizedError,
+	UnprocessableEntityError,
+} from "./error.ts"
+export { PathParamError } from "./path.ts"
+export type { AuthExpiredContext, ClientConfig, RedirectPolicy, RequestOptions } from "./http.ts"
 export { HTTPClient, newClientRequestId } from "./http.ts"
+import type { SSEEvent } from "./sse.ts"
+
 export type { SSEEvent } from "./sse.ts"
 export { parseSSEStream } from "./sse.ts"
 export type {
@@ -30,6 +47,10 @@ export { createTypedWebSocket } from "./ws.ts"
 
 const HTTP_METHODS = new Set(["delete", "get", "patch", "post", "put"])
 
+function isAsyncIterable(value: unknown): value is AsyncIterable<SSEEvent> {
+	return typeof value === "object" && value !== null && Symbol.asyncIterator in value
+}
+
 export function createClient<T>(config: ClientConfig & { throwOnError: true }): HoneyClient<InferRoutes<T>, true>
 export function createClient<T>(
 	config: Omit<ClientConfig, "throwOnError"> & { throwOnError?: false },
@@ -43,7 +64,10 @@ export function createClient<T, TThrow extends boolean = false>(
 	const http = new HTTPClient(config)
 
 	return new Proxy({} as HoneyClient<InferRoutes<T>, TThrow>, {
-		get(_target, prop: string) {
+		get(_target, prop: string | symbol) {
+			/* not a thenable, and printable: `await client` and `String(client)` must not hit the method table */
+			if (typeof prop === "symbol" || prop === "then") return undefined
+			if (prop === "toString" || prop === "toJSON") return () => "[object HoneyClient]"
 			if (prop === "$isClientError") return isClientError
 
 			if (prop === "$url") {
@@ -83,30 +107,44 @@ export function createClient<T, TThrow extends boolean = false>(
 					const shouldThrow = config.throwOnError === true
 
 					/**
-					 * Lazy dual-mode: both PromiseLike (REST) and AsyncIterable (SSE).
-					 * - `await api.get(...)` → REST (request or requestSafe)
-					 * - `for await (... of api.get(...))` → SSE (requestStream)
+					 * One call, one request, consumed either way:
+					 * - `await api.get(...)` sends it; an event-stream response resolves to an
+					 *   `AsyncIterable<SSEEvent>` (never buffered), anything else to the parsed body
+					 *   or result tuple. Returning the call from an async function works the same.
+					 * - `for await (... of api.get(...))` before the call has started sends it as a
+					 *   stream request (`accept: text/event-stream`, no timeout).
+					 * - iterating after awaiting reuses the same response instead of sending again.
 					 */
-					let mode: "idle" | "rest" | "sse" = "idle"
-					let restPromise: Promise<unknown> | undefined
-					const lazyRest = (): Promise<unknown> => {
-						if (!restPromise) {
-							restPromise = shouldThrow ? http.request(method, path, opts) : http.requestSafe(method, path, opts)
-						}
-						return restPromise
+					let mode: "auto" | "idle" | "sse" = "idle"
+					let auto: Promise<unknown> | undefined
+					const runAuto = (): Promise<unknown> => {
+						auto ??= http.requestAuto(method, path, opts, shouldThrow)
+						return auto
 					}
 
 					const lazy = new Promise((resolve, reject) => {
 						queueMicrotask(() => {
 							if (mode === "sse") return
-							mode = "rest"
-							lazyRest().then(resolve, reject)
+							mode = "auto"
+							runAuto().then(resolve, reject)
 						})
 					})
 					Object.defineProperty(lazy, Symbol.asyncIterator, {
 						value() {
-							mode = "sse"
-							return http.requestStream(method, path, opts)[Symbol.asyncIterator]()
+							if (mode === "idle") {
+								mode = "sse"
+								return http.requestStream(method, path, opts)[Symbol.asyncIterator]()
+							}
+							return (async function* () {
+								const result = await runAuto()
+								if (isAsyncIterable(result)) {
+									yield* result
+									return
+								}
+								const error = (result as { error?: unknown } | null)?.error
+								if (error) throw error instanceof Error ? error : new Error("Request failed")
+								throw new TypeError(`${method} ${path} did not respond with an event stream`)
+							})()
 						},
 					})
 					return lazy

package/src/client/path.ts

@@ -0,0 +1,169 @@
+/**
+ * Client-side path templates. Two spellings are accepted, segment by segment:
+ *
+ * - Honey route patterns: `:name` (or `:name?`) takes a whole segment, `*name` (or `*`)
+ *   takes the rest of the path. Names follow the router grammar, so `:user-id` is one
+ *   parameter.
+ * - OpenAPI templates: `{name}` anywhere inside a segment (`/ops/{id}:cancel`).
+ *
+ * Values are percent-encoded. A value that would change the path's shape once a URL parser
+ * normalizes it (`""`, `.`, `..`) is rejected, so `{ id: ".." }` can never retarget a request
+ * to the parent resource and `{ org: "" }` can never turn `/:org/:repo` into `//repo`.
+ */
+
+const BRACE_RE = /\{([^{}/]+)\}/g
+
+export class PathParamError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "PathParamError"
+	}
+}
+
+function own(params: Record<string, unknown>, key: string): unknown {
+	return Object.hasOwn(params, key) ? params[key] : undefined
+}
+
+function toValue(params: Record<string, unknown>, key: string): string | undefined {
+	const raw = own(params, key)
+	if (raw === undefined || raw === null) return undefined
+	return typeof raw === "string" ? raw : String(raw)
+}
+
+function encodeSegmentValue(key: string, value: string): string {
+	if (value === "" || value === "." || value === "..") {
+		throw new PathParamError(
+			`Invalid path param ${JSON.stringify(key)}: ${JSON.stringify(value)} is not a path segment`,
+		)
+	}
+	return encodeURIComponent(value)
+}
+
+/** A wildcard value may span segments; each one is encoded and validated on its own. */
+function encodeWildcardValue(key: string, value: string): string {
+	if (value === "") return ""
+	return value
+		.split("/")
+		.map((part) => encodeSegmentValue(key, part))
+		.join("/")
+}
+
+export function interpolatePath(path: string, params: Record<string, unknown> = {}): string {
+	const segments = path.split("/")
+	const out: string[] = []
+	for (let i = 0; i < segments.length; i++) {
+		const seg = segments[i]
+		if (seg.length > 1 && seg.charCodeAt(0) === 58 /* : */) {
+			const optional = seg.endsWith("?")
+			const name = optional ? seg.slice(1, -1) : seg.slice(1)
+			const value = toValue(params, name)
+			if (value === undefined) {
+				if (optional) continue
+				throw new PathParamError(`Missing path param: ${name}`)
+			}
+			out.push(encodeSegmentValue(name, value))
+			continue
+		}
+		if (seg.charCodeAt(0) === 42 /* * */ && i === segments.length - 1) {
+			const name = seg.length > 1 ? seg.slice(1) : "*"
+			const value = toValue(params, name)
+			if (value === undefined) {
+				if (seg.length === 1) {
+					out.push("")
+					continue
+				}
+				throw new PathParamError(`Missing path param: ${name}`)
+			}
+			out.push(encodeWildcardValue(name, value))
+			continue
+		}
+		out.push(
+			seg.replace(BRACE_RE, (_, name: string) => {
+				const value = toValue(params, name)
+				if (value === undefined) throw new PathParamError(`Missing path param: ${name}`)
+				return encodeSegmentValue(name, value)
+			}),
+		)
+	}
+	return out.join("/")
+}
+
+/** True when the template still has a placeholder in either spelling. */
+export function hasPlaceholder(path: string): boolean {
+	for (const seg of path.split("/")) {
+		if (seg.length > 1 && seg.charCodeAt(0) === 58) return true
+		if (seg.charCodeAt(0) === 42) return true
+		BRACE_RE.lastIndex = 0
+		if (BRACE_RE.test(seg)) return true
+	}
+	return false
+}
+
+/**
+ * Substitute the params that are present and leave the others as placeholders. Used for
+ * invalidation targets, where a partially resolved target is still a narrower pattern.
+ */
+export function interpolatePartial(path: string, params: Record<string, unknown>): string {
+	return path
+		.split("/")
+		.map((seg, i, all) => {
+			if (seg.length > 1 && seg.charCodeAt(0) === 58) {
+				const optional = seg.endsWith("?")
+				const name = optional ? seg.slice(1, -1) : seg.slice(1)
+				const value = toValue(params, name)
+				return value === undefined ? seg : encodeSegmentValue(name, value)
+			}
+			if (seg.charCodeAt(0) === 42 && i === all.length - 1) {
+				const value = toValue(params, seg.length > 1 ? seg.slice(1) : "*")
+				return value === undefined ? seg : encodeWildcardValue(seg.slice(1), value)
+			}
+			return seg.replace(BRACE_RE, (match, name: string) => {
+				const value = toValue(params, name)
+				return value === undefined ? match : encodeSegmentValue(name, value)
+			})
+		})
+		.join("/")
+}
+
+function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+const MAX_CACHED_PATTERNS = 1024
+const patternCache = new Map<string, RegExp>()
+
+/** Compile a template to a regex over concrete paths, using the same segment grammar. */
+export function compilePattern(pattern: string): RegExp {
+	let re = patternCache.get(pattern)
+	if (re !== undefined) return re
+	const segments = pattern.split("/")
+	let source = ""
+	for (let i = 0; i < segments.length; i++) {
+		const seg = segments[i]
+		const sep = i === 0 ? "" : "/"
+		if (seg.length > 1 && seg.charCodeAt(0) === 58) {
+			source += seg.endsWith("?") ? `(?:${sep}[^/]+)?` : `${sep}[^/]+`
+			continue
+		}
+		if (seg.charCodeAt(0) === 42 && i === segments.length - 1) {
+			source += `(?:${sep}.*)?`
+			continue
+		}
+		let segSource = ""
+		let last = 0
+		BRACE_RE.lastIndex = 0
+		for (let m = BRACE_RE.exec(seg); m !== null; m = BRACE_RE.exec(seg)) {
+			segSource += `${escapeRegExp(seg.slice(last, m.index))}[^/]+`
+			last = m.index + m[0].length
+		}
+		segSource += escapeRegExp(seg.slice(last))
+		source += sep + segSource
+	}
+	re = new RegExp(`^${source}$`)
+	if (patternCache.size >= MAX_CACHED_PATTERNS) {
+		const oldest = patternCache.keys().next().value
+		if (oldest !== undefined) patternCache.delete(oldest)
+	}
+	patternCache.set(pattern, re)
+	return re
+}

package/src/client/redirect-policy.ts

@@ -0,0 +1,19 @@
+/**
+ * Headers a request may carry to another origin when a `redirect: "follow"` client follows a
+ * cross-origin redirect. Everything else is dropped on that hop: credentials, the auth header and
+ * every header set from config (either form), per call or by an `onRequest` hook, whatever its
+ * name. An allowlist, so a header added later never leaks by default.
+ *
+ * Shared by `createClient` and the generated TypeScript SDK runtime, which embeds this list.
+ */
+export const CROSS_ORIGIN_SAFE_HEADERS: readonly string[] = ["accept", "accept-language", "user-agent"]
+
+/** The headers to send on a cross-origin hop: only the allowlisted ones from `headers`. */
+export function crossOriginHeaders(headers: Headers): Headers {
+	const out = new Headers()
+	for (const name of CROSS_ORIGIN_SAFE_HEADERS) {
+		const value = headers.get(name)
+		if (value !== null) out.set(name, value)
+	}
+	return out
+}