@lovrozagar/honey 0.1.0

package/src/client/sdk.ts

@@ -0,0 +1,265 @@
+import type { ClientConfig, RequestMeta } from "./http.ts"
+import { HTTPClient, interpolatePath } from "./http.ts"
+import { createTypedWebSocket } from "./ws.ts"
+
+type ServiceEntry = {
+	invalidate?: readonly string[]
+	method: string
+	params?: readonly string[]
+	path: string
+	sse?: boolean
+	ws?: boolean
+}
+
+type ServiceMapNode = ServiceEntry | { [key: string]: ServiceMapNode }
+type ServiceMap = { [key: string]: ServiceMapNode }
+
+export type InvalidationConfig = {
+	staleTime: number
+}
+
+export type SDKConfig = ClientConfig & {
+	invalidation?: InvalidationConfig
+}
+
+/* bridge generic — Proxy target is object, return type is T (erased at runtime) */
+function bridge<T>(value: object): T {
+	return value as T
+}
+
+/* convert OpenAPI {param} to :param for HTTPClient */
+function toColonParams(path: string): string {
+	return path.replace(/\{(\w+)\}/g, ":$1")
+}
+
+/* resolve invalidation targets by substituting mutation params */
+export function resolveInvalidationTargets(
+	targets: readonly string[],
+	params: Record<string, string> | undefined,
+): string[] {
+	const resolved: string[] = []
+	for (const target of targets) {
+		if (!params || !target.includes(":")) { resolved.push(target); continue }
+		const spaceIdx = target.indexOf(" ")
+		const targetMethod = target.slice(0, spaceIdx)
+		const targetPath = target.slice(spaceIdx + 1)
+		let hasUnresolved = false
+		const replaced = targetPath.replace(/:(\w+)/g, (match, key: string) => {
+			const val = params[key]
+			if (val === undefined) { hasUnresolved = true; return match }
+			return encodeURIComponent(val)
+		})
+		if (hasUnresolved) continue
+		resolved.push(`${targetMethod} ${replaced}`)
+	}
+	return resolved
+}
+
+/* cache compiled pattern regexes — hot path for invalidation lookups */
+const patternRegexCache = new Map<string, RegExp>()
+
+/* test if a concrete path matches a route pattern; escapes regex metacharacters in the pattern */
+export function pathMatchesPattern(concretePath: string, pattern: string): boolean {
+	let re = patternRegexCache.get(pattern)
+	if (!re) {
+		/* split on :param placeholders, escape each literal segment's metachars, rejoin with [^/]+ */
+		const parts = pattern.split(/:[^/]+/g)
+		const escaped = parts
+			.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+			.join("[^/]+")
+		re = new RegExp(`^${escaped}$`)
+		patternRegexCache.set(pattern, re)
+	}
+	return re.test(concretePath)
+}
+
+/* two-tier stale lookup: exact concrete match, then pattern fallback; sweeps expired entries in one pass */
+export function lookupStale(
+	staleMap: Map<string, { by: string[], seq: number, until: number }>,
+	concreteSelector: string,
+	concretePath: string,
+	method: string,
+	now: number,
+): { by: string[], isStale: boolean } {
+	const allBy: string[] = []
+	const expired: string[] = []
+
+	const exact = staleMap.get(concreteSelector)
+	if (exact && exact.until > now) allBy.push(...exact.by)
+	else if (exact) expired.push(concreteSelector)
+
+	for (const [key, entry] of staleMap) {
+		if (entry.until <= now) { expired.push(key); continue }
+		if (!key.includes(":")) continue
+		const spaceIdx = key.indexOf(" ")
+		const keyMethod = key.slice(0, spaceIdx)
+		const keyPattern = key.slice(spaceIdx + 1)
+		if (keyMethod !== method) continue
+		if (pathMatchesPattern(concretePath, keyPattern)) {
+			allBy.push(...entry.by)
+		}
+	}
+	for (const key of expired) staleMap.delete(key)
+
+	return { by: [...new Set(allBy)], isStale: allBy.length > 0 }
+}
+
+export function createSDK<T = Record<string, Record<string, (...args: unknown[]) => unknown>>>(
+	serviceMap: ServiceMap,
+	config: SDKConfig,
+): T {
+	const http = new HTTPClient(config)
+	const staleTime = config.invalidation?.staleTime ?? 0
+	const hasInvalidation = staleTime > 0
+	const staleUntil = hasInvalidation
+		? new Map<string, { by: string[], seq: number, until: number }>()
+		: null
+
+	let invalidationSeq = 0
+
+	const rootCache = new Map<string, object>()
+
+	function buildLeafFn(entry: ServiceEntry, namePath: string[]): Function {
+		const path = toColonParams(entry.path)
+		const method = entry.method
+		let fn: Function
+
+		if (entry.ws) {
+			fn = (input?: Record<string, unknown>) => {
+				const opts = {
+					params: input?.["params"] as Record<string, string> | undefined,
+					search: input?.["search"] as Record<string, unknown> | undefined,
+				}
+				let url = http.buildWSUrl(path, opts)
+				const reconnectToken = input?.["reconnectToken"] as string | undefined
+				if (reconnectToken) {
+					const sep = url.includes("?") ? "&" : "?"
+					url = `${url}${sep}reconnect_token=${encodeURIComponent(reconnectToken)}`
+				}
+				return createTypedWebSocket(url, {
+					protocols: input?.["protocols"] as string | string[] | undefined,
+				})
+			}
+		} else if (entry.sse) {
+			fn = (input?: Record<string, unknown>) => http.requestStream(method, path, input ?? {})
+		} else {
+			fn = async (input?: Record<string, unknown>) => {
+				const opts = input ?? {}
+				const params = opts["params"] as Record<string, string> | undefined
+				const concretePath = params ? interpolatePath(path, params) : path
+				const concreteSelector = `${method} ${concretePath}`
+				let requestMeta: RequestMeta | undefined
+
+				if (staleUntil) {
+					const now = Date.now()
+					const { by, isStale } = lookupStale(staleUntil, concreteSelector, concretePath, method, now)
+					requestMeta = { invalidatedBy: by, isStale, selector: concreteSelector, seqSnapshot: invalidationSeq }
+				}
+
+				const result = config.throwOnError === true
+					? await http.request(method, path, opts, requestMeta)
+					: await http.requestSafe(method, path, opts, requestMeta)
+
+				if (staleUntil) {
+					const isSuccess = config.throwOnError === true
+						? true
+						: ((result as { status: number }).status >= 200 && (result as { status: number }).status < 300)
+
+					if (isSuccess) {
+						if (entry.invalidate && entry.invalidate.length > 0) {
+							const seq = ++invalidationSeq
+							const until = Date.now() + staleTime
+							const mutationSelector = concreteSelector
+							const resolved = resolveInvalidationTargets(entry.invalidate, params)
+							for (const target of resolved) {
+								const existing = staleUntil.get(target)
+								if (existing) {
+									if (!existing.by.includes(mutationSelector)) existing.by.push(mutationSelector)
+									existing.until = until
+									existing.seq = seq
+								} else {
+									staleUntil.set(target, { by: [mutationSelector], seq, until })
+								}
+							}
+						}
+
+						if (requestMeta?.isStale) {
+							const snapshot = requestMeta.seqSnapshot
+							const exact = staleUntil.get(concreteSelector)
+							if (exact && exact.seq <= snapshot) staleUntil.delete(concreteSelector)
+							const toDelete: string[] = []
+							for (const [key, staleEntry] of staleUntil) {
+								if (staleEntry.seq > snapshot) continue
+								if (!key.includes(":")) continue
+								const spaceIdx = key.indexOf(" ")
+								const keyMethod = key.slice(0, spaceIdx)
+								const keyPattern = key.slice(spaceIdx + 1)
+								if (keyMethod === method && pathMatchesPattern(concretePath, keyPattern)) toDelete.push(key)
+							}
+							for (const key of toDelete) staleUntil.delete(key)
+						}
+					}
+				}
+
+				return result
+			}
+		}
+
+		Object.defineProperty(fn, "name", { value: namePath.join(".") })
+		return fn
+	}
+
+	function makeNodeProxy(node: ServiceMapNode, namePath: string[]): object {
+		const actionCache = new Map<string, Function>()
+		const childCache = new Map<string, object>()
+		return new Proxy({} as Record<string, unknown>, {
+			get(_, key: string | symbol) {
+				if (typeof key === "symbol") return undefined
+				const child = (node as Record<string, unknown>)[key]
+				if (child === undefined) return undefined
+
+				if (typeof (child as Record<string, unknown>)["method"] === "string") {
+					const cached = actionCache.get(key)
+					if (cached) return cached
+					const fn = buildLeafFn(child as ServiceEntry, [...namePath, key])
+					actionCache.set(key, fn)
+					return fn
+				}
+
+				const cached = childCache.get(key)
+				if (cached) return cached
+				const childProxy = makeNodeProxy(child as ServiceMapNode, [...namePath, key])
+				childCache.set(key, childProxy)
+				return childProxy
+			},
+		})
+	}
+
+	return bridge<T>(
+		new Proxy(
+			{},
+			{
+				get(_target, key: string | symbol) {
+					if (typeof key === "symbol") return undefined
+
+					const cached = rootCache.get(key as string)
+					if (cached) return cached
+
+					const node = serviceMap[key as string]
+					if (node === undefined) return undefined
+
+					let result: object
+					if (typeof (node as Record<string, unknown>)["method"] === "string") {
+						const fn = buildLeafFn(node as ServiceEntry, [key as string])
+						result = fn as unknown as object
+					} else {
+						result = makeNodeProxy(node, [key as string])
+					}
+
+					rootCache.set(key as string, result)
+					return result
+				},
+			},
+		),
+	)
+}

package/src/client/sse.ts

@@ -0,0 +1,102 @@
+export type SSEEvent = {
+	data: string
+	event?: string
+	id?: string
+	retry?: number
+}
+
+function parseBlock(block: string): SSEEvent | undefined {
+	const lines = block.split(/\r\n|\r|\n/)
+	let isComment = true
+	let data: string | undefined
+	let event: string | undefined
+	let id: string | undefined
+	let retry: number | undefined
+
+	for (const line of lines) {
+		if (line.startsWith(":")) continue
+		isComment = false
+
+		const colonIdx = line.indexOf(":")
+		let field: string
+		let val: string
+		if (colonIdx === -1) {
+			field = line
+			val = ""
+		} else {
+			field = line.slice(0, colonIdx)
+			val = line.slice(colonIdx + 1)
+			if (val.startsWith(" ")) val = val.slice(1)
+		}
+
+		switch (field) {
+			case "data":
+				data = data === undefined ? val : `${data}\n${val}`
+				break
+			case "event":
+				event = val
+				break
+			case "id":
+				/* per spec: id containing null byte must be ignored */
+				if (!val.includes("\0")) id = val
+				break
+			case "retry": {
+				const n = Number(val)
+				if (Number.isFinite(n) && n >= 0) retry = n
+				break
+			}
+		}
+	}
+
+	if (isComment || data === undefined) return undefined
+
+	const sse: SSEEvent = { data }
+	if (event !== undefined) sse.event = event
+	if (id !== undefined) sse.id = id
+	if (retry !== undefined) sse.retry = retry
+	return sse
+}
+
+const DEFAULT_MAX_BUFFER = 1024 * 1024
+
+export async function* parseSSEStream(
+	stream: ReadableStream<Uint8Array>,
+	opts?: { maxBufferSize?: number },
+): AsyncGenerator<SSEEvent, void, undefined> {
+	const decoder = new TextDecoder()
+	const reader = stream.getReader()
+	let buffer = ""
+	const maxBuffer = opts?.maxBufferSize ?? DEFAULT_MAX_BUFFER
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read()
+			if (done) break
+			buffer += decoder.decode(value, { stream: true })
+
+			if (buffer.length > maxBuffer) {
+				throw new Error(`SSE buffer exceeded ${maxBuffer} characters`)
+			}
+
+			/* split on double-newline (any combo of \r\n, \r, \n) */
+			const blocks = buffer.split(/\r\n\r\n|\r\n\r|\r\n\n|\r\r\n|\n\r\n|\n\r|\r\r|\n\n/)
+			/* last element is incomplete — keep in buffer */
+			buffer = blocks.pop() ?? ""
+
+			for (const block of blocks) {
+				if (block.trim() === "") continue
+				const event = parseBlock(block)
+				if (event) yield event
+			}
+		}
+
+		/* flush remaining buffer */
+		if (buffer.trim() !== "") {
+			const event = parseBlock(buffer)
+			if (event) yield event
+		}
+	} finally {
+		await reader.cancel()
+		reader.releaseLock()
+	}
+}

package/src/client/types.ts

@@ -0,0 +1,211 @@
+import type { FieldError, InferOutput, ParamsFromPath, StandardSchemaLike } from "../types.ts"
+import type { SSEEvent } from "./sse.ts"
+import type { TypedWebSocket } from "./ws.ts"
+
+/** Extract paths that have a specific method registered */
+export type PathsForMethod<TRoutes, M extends string> = {
+	[P in keyof TRoutes & string]: M extends keyof TRoutes[P] ? P : never
+}[keyof TRoutes & string]
+
+/** Extract input type for a route */
+export type InputFor<TRoutes, P extends string, M extends string> = P extends keyof TRoutes
+	? M extends keyof TRoutes[P]
+		? TRoutes[P][M] extends { input: infer I }
+			? I
+			: {}
+		: {}
+	: {}
+
+/** Extract output schema definition for a route */
+export type OutputDefFor<TRoutes, P extends string, M extends string> = P extends keyof TRoutes
+	? M extends keyof TRoutes[P]
+		? TRoutes[P][M] extends { output: infer O }
+			? O
+			: never
+		: never
+	: never
+
+/** Check if output definition is empty (no .output() declared) */
+type IsEmptyOutput<O> = keyof O extends never ? true : false
+
+/** Content-type to return type mapping for non-JSON outputs */
+type ContentTypeReturn<O> = O extends { "text/plain": unknown }
+	? string
+	: O extends { "text/html": unknown }
+		? string
+		: O extends { "text/csv": unknown }
+			? string
+			: O extends { "application/xml": unknown }
+				? string
+				: O extends { "application/octet-stream": unknown }
+					? ArrayBuffer
+					: null
+
+/** Extract the resolved output type — infer from schema validators in the output definition */
+export type OutputFor<TRoutes, P extends string, M extends string> =
+	OutputDefFor<TRoutes, P, M> extends infer O
+		? [O] extends [never]
+			? null
+			: IsEmptyOutput<O> extends true
+				? null
+				: O extends { "application/json": infer JsonMap }
+					? JsonMap extends Record<string, StandardSchemaLike>
+						? InferOutput<JsonMap[keyof JsonMap]>
+						: null
+					: ContentTypeReturn<O>
+		: null
+
+/** Check if a route returns SSE (text/event-stream in output) */
+export type IsSSE<TRoutes, P extends string, M extends string> =
+	OutputDefFor<TRoutes, P, M> extends infer O
+		? O extends { "text/event-stream": unknown }
+			? true
+			: false
+		: false
+
+/** Extract errorsByStatus from route record if available */
+type ErrorsByStatusFor<TRoutes, P extends string, M extends string> = P extends keyof TRoutes
+	? M extends keyof TRoutes[P]
+		? TRoutes[P][M] extends { errorsByStatus: infer S }
+			? S
+			: never
+		: never
+	: never
+
+/** Default Honey error envelope — used when errorsByStatus lists `null` (standard errors) */
+export type ErrorEnvelope<TStatus extends number = number, TKey extends string = string> = {
+	error_key: TKey
+	fields: Record<string, FieldError[]>
+	message: string
+	status: TStatus
+	status_key: string
+	success: false
+}
+
+/** `null` in a route's errorsByStatus means the default envelope, not a null body */
+type ResolveErrorBody<S extends number, T> = T extends null ? ErrorEnvelope<S> : T
+
+/** Object keys of `{ 400: ... }` are `400` or `"400"` depending on TS version */
+type StatusCode<K> = K extends number ? K : K extends `${infer N extends number}` ? N : never
+
+type HasStatusErrors<T> = [StatusCode<keyof T>] extends [never] ? false : true
+
+type ErrorVariants<TErrorsByStatus> = {
+	[K in keyof TErrorsByStatus]: StatusCode<K> extends never
+		? never
+		: {
+				data: null
+				error: ResolveErrorBody<StatusCode<K>, TErrorsByStatus[K]>
+				response: Response
+				status: StatusCode<K>
+			}
+}[keyof TErrorsByStatus]
+
+/**
+ * Result tuple for safe (non-throwing) mode — error is the raw parsed body, not ClientError.
+ * When TErrorsByStatus is known, the typed branch covers every declared error status
+ * (no unknown fallback) so `if (error)` / `if (!error)` narrow.
+ */
+export type ClientResult<TData, TErrorsByStatus = never> =
+	| { data: TData; error: null; response: Response; status: number }
+	| (HasStatusErrors<TErrorsByStatus> extends false
+		? { data: null; error: unknown; response: Response; status: number }
+		: ErrorVariants<TErrorsByStatus>)
+
+/** Resolve return type based on transport + throw mode */
+export type ReturnFor<TRoutes, P extends string, M extends string, TThrow extends boolean = true> =
+	IsSSE<TRoutes, P, M> extends true
+		? AsyncIterable<SSEEvent>
+		: TThrow extends true
+			? Promise<OutputFor<TRoutes, P, M>>
+			: Promise<ClientResult<OutputFor<TRoutes, P, M>, ErrorsByStatusFor<TRoutes, P, M>>>
+
+/** Build the client input type — merge route input with params from path */
+export type ClientInput<TRoutes, P extends string, M extends string> = InputFor<TRoutes, P, M> &
+	ParamsInput<P>
+
+/** Extract params input if path has params */
+type ParamsInput<P extends string> =
+	ParamsFromPath<P> extends Record<string, string>
+		? HasParams<P> extends true
+			? { params: ParamsFromPath<P> }
+			: {}
+		: {}
+
+/** Check if path has any param segments */
+type HasParams<P extends string> = P extends `${string}:${string}` ? true : false
+
+/** Extract error keys for a route */
+export type ErrorsFor<TRoutes, P extends string, M extends string> = P extends keyof TRoutes
+	? M extends keyof TRoutes[P]
+		? TRoutes[P][M] extends { errors: infer E extends string }
+			? E
+			: never
+		: never
+	: never
+
+/** The typed client interface — TThrow controls return type */
+export type HoneyClient<TRoutes, TThrow extends boolean = false> = {
+	$isClientError: (e: unknown) => e is import("./error.ts").ClientError
+
+	$path<P extends keyof TRoutes & string>(
+		path: P,
+		input?: { params?: Record<string, string>; search?: Record<string, unknown> },
+	): string
+
+	$url<P extends keyof TRoutes & string>(
+		path: P,
+		input?: { params?: Record<string, string>; search?: Record<string, unknown> },
+	): string
+
+	delete<P extends PathsForMethod<TRoutes, "delete">>(
+		path: P,
+		...input: OptionalInput<ClientInput<TRoutes, P, "delete">>
+	): ReturnFor<TRoutes, P, "delete", TThrow>
+
+	get<P extends PathsForMethod<TRoutes, "get">>(
+		path: P,
+		...input: OptionalInput<ClientInput<TRoutes, P, "get">>
+	): ReturnFor<TRoutes, P, "get", TThrow>
+
+	patch<P extends PathsForMethod<TRoutes, "patch">>(
+		path: P,
+		...input: OptionalInput<ClientInput<TRoutes, P, "patch">>
+	): ReturnFor<TRoutes, P, "patch", TThrow>
+
+	post<P extends PathsForMethod<TRoutes, "post">>(
+		path: P,
+		...input: OptionalInput<ClientInput<TRoutes, P, "post">>
+	): ReturnFor<TRoutes, P, "post", TThrow>
+
+	put<P extends PathsForMethod<TRoutes, "put">>(
+		path: P,
+		...input: OptionalInput<ClientInput<TRoutes, P, "put">>
+	): ReturnFor<TRoutes, P, "put", TThrow>
+
+	ws(
+		path: string,
+		input?: {
+			params?: Record<string, string>
+			protocols?: string | string[]
+			reconnectToken?: string
+			search?: Record<string, unknown>
+		},
+	): TypedWebSocket
+}
+
+/** Make input optional when it's an empty object */
+type OptionalInput<T> = keyof T extends never
+	? [input?: T]
+	: [RequiresAllOptional<T>] extends [true]
+		? [input?: T]
+		: [input: T]
+
+/** Check if all keys in T are optional */
+type RequiresAllOptional<T> = {
+	[K in keyof T]-?: undefined extends T[K] ? true : false
+}[keyof T] extends true
+	? true
+	: Partial<T> extends T
+		? true
+		: false

package/src/client/ws.ts

@@ -0,0 +1,115 @@
+export type TypedWebSocket = {
+	close(code?: number, reason?: string): void
+	off(event: "close" | "error" | "message" | "open", handler: (...args: never[]) => void): void
+	on(event: "close", handler: (code: number, reason: string) => void): void
+	on(event: "error", handler: (error: unknown) => void): void
+	on(event: "message", handler: (data: string) => void): void
+	on(event: "open", handler: () => void): void
+	readonly readyState: number
+	send(data: ArrayBuffer | ArrayBufferView | object | string): void
+}
+
+export type WSOptions = {
+	protocols?: string | string[]
+}
+
+export function createTypedWebSocket(
+	url: string,
+	opts?: WSOptions,
+	WebSocketImpl: typeof WebSocket = WebSocket,
+): TypedWebSocket {
+	const ws = opts?.protocols ? new WebSocketImpl(url, opts.protocols) : new WebSocketImpl(url)
+
+	/* map user handlers → wrapped listeners for proper removal */
+	const listenerMap = new WeakMap<(...args: never[]) => void, EventListener>()
+	/* buffer sends until OPEN */
+	const sendBuffer: Array<string | Uint8Array<ArrayBuffer>> = []
+	let buffering = true
+
+	ws.addEventListener("open", () => {
+		buffering = false
+		for (const msg of sendBuffer) {
+			ws.send(msg)
+		}
+		sendBuffer.length = 0
+	})
+
+	function close(code?: number, reason?: string) {
+		buffering = false
+		sendBuffer.length = 0
+		ws.close(code, reason)
+	}
+
+	function on(event: "close", handler: (code: number, reason: string) => void): void
+	function on(event: "error", handler: (error: unknown) => void): void
+	function on(event: "message", handler: (data: string) => void): void
+	function on(event: "open", handler: () => void): void
+	function on(event: string, handler: (...args: never[]) => void): void {
+		let wrapped: EventListener
+		switch (event) {
+			case "message":
+				wrapped = (e: Event) => (handler as (data: string) => void)((e as MessageEvent).data)
+				break
+			case "open":
+				wrapped = () => (handler as () => void)()
+				break
+			case "close":
+				wrapped = (e: Event) =>
+					(handler as (code: number, reason: string) => void)(
+						(e as CloseEvent).code,
+						(e as CloseEvent).reason,
+					)
+				break
+			case "error":
+				wrapped = (e: Event) => (handler as (error: unknown) => void)(e)
+				break
+			default:
+				return
+		}
+		listenerMap.set(handler, wrapped)
+		ws.addEventListener(event, wrapped)
+	}
+
+	function off(event: string, handler: (...args: never[]) => void): void {
+		const wrapped = listenerMap.get(handler)
+		if (wrapped) {
+			ws.removeEventListener(event, wrapped)
+			listenerMap.delete(handler)
+		}
+	}
+
+	function toWsData(data: ArrayBuffer | ArrayBufferView | string): string | Uint8Array<ArrayBuffer> {
+		if (typeof data === "string") return data
+		const view = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+		const copy = new Uint8Array(view.byteLength)
+		copy.set(view)
+		return copy
+	}
+
+	function send(data: ArrayBuffer | ArrayBufferView | object | string) {
+		const payload =
+			typeof data === "string" || data instanceof ArrayBuffer || ArrayBuffer.isView(data)
+				? toWsData(data)
+				: JSON.stringify(data)
+
+		if (buffering) {
+			sendBuffer.push(payload)
+		} else {
+			ws.send(payload)
+		}
+	}
+
+	const typed: TypedWebSocket = {
+		close,
+		off,
+		on,
+		get readyState() {
+			return ws.readyState
+		},
+		send,
+	}
+
+	Object.defineProperty(typed, "_ws", { enumerable: false, value: ws })
+
+	return typed
+}