@lovrozagar/honey 0.6.5 → 0.7.0

package/src/client/sdk.ts

@@ -1,5 +1,6 @@
 import type { ClientConfig, RequestMeta } from "./http.ts"
-import { HTTPClient, interpolatePath } from "./http.ts"
+import { HTTPClient } from "./http.ts"
+import { compilePattern, hasPlaceholder, interpolatePartial, interpolatePath } from "./path.ts"
 import { createTypedWebSocket } from "./ws.ts"
 
 type ServiceEntry = {
@@ -27,57 +28,147 @@ 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")
+function own<T>(record: Record<string, T>, key: string): T | undefined {
+	return Object.hasOwn(record, key) ? record[key] : undefined
 }
 
-/* resolve invalidation targets by substituting mutation params */
+/**
+ * Resolve invalidation targets by substituting the mutation's params. Params that are absent
+ * stay placeholders, so a partially resolved target is a narrower pattern, never dropped:
+ * `PUT /orgs/{org}` invalidating `GET /orgs/:org/members/:id` marks `GET /orgs/acme/members/:id`.
+ */
 export function resolveInvalidationTargets(
 	targets: readonly string[],
 	params: Record<string, string> | undefined,
 ): string[] {
 	const resolved: string[] = []
 	for (const target of targets) {
-		if (!params || !target.includes(":")) {
+		const spaceIdx = target.indexOf(" ")
+		if (spaceIdx === -1 || !params) {
 			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}`)
+		try {
+			resolved.push(`${targetMethod} ${interpolatePartial(targetPath, params)}`)
+		} catch {
+			/* a param value that is not a path segment cannot address a resource; keep the pattern */
+			resolved.push(target)
+		}
 	}
 	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 */
+/** Test if a concrete path matches a route pattern (`:name`, `{name}`, `*`); literal text is escaped. */
 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 compilePattern(pattern).test(concretePath)
+}
+
+/* Bound memory: an entry remembers the last N mutations that marked it, and which concrete
+   paths have already refreshed against a pattern-level mark. */
+const MAX_INVALIDATED_BY = 32
+const MAX_REFRESHED = 1024
+
+type StaleEntry = {
+	by: Set<string>
+	/** Concrete paths that have read once since this pattern was marked (pattern entries only). */
+	refreshed?: Set<string>
+	seq: number
+	until: number
+}
+
+/**
+ * Stale marks, split by kind so a concrete key is never re-read as a pattern (a path may
+ * contain `:`), and a lookup scans only patterns for its own method.
+ */
+export class StaleIndex {
+	readonly exact = new Map<string, StaleEntry>()
+	readonly patterns = new Map<string, Map<string, StaleEntry>>()
+
+	mark(target: string, mutation: string, seq: number, until: number): void {
+		const spaceIdx = target.indexOf(" ")
+		const method = target.slice(0, spaceIdx)
+		const path = target.slice(spaceIdx + 1)
+		const isPattern = hasPlaceholder(path)
+		let table: Map<string, StaleEntry>
+		if (isPattern) {
+			table = this.patterns.get(method) ?? new Map()
+			this.patterns.set(method, table)
+		} else {
+			table = this.exact
+		}
+		const existing = table.get(target)
+		if (existing) {
+			existing.by.delete(mutation)
+			existing.by.add(mutation)
+			if (existing.by.size > MAX_INVALIDATED_BY) {
+				const oldest = existing.by.values().next().value
+				if (oldest !== undefined) existing.by.delete(oldest)
+			}
+			existing.until = until
+			existing.seq = seq
+			/* a new mutation re-marks every instance */
+			if (existing.refreshed) existing.refreshed.clear()
+		} else {
+			table.set(target, { by: new Set([mutation]), refreshed: isPattern ? new Set() : undefined, seq, until })
+		}
+	}
+
+	lookup(
+		concreteSelector: string,
+		concretePath: string,
+		method: string,
+		now: number,
+	): { by: string[]; isStale: boolean } {
+		const by = new Set<string>()
+		const exact = this.exact.get(concreteSelector)
+		if (exact) {
+			if (exact.until > now) for (const m of exact.by) by.add(m)
+			else this.exact.delete(concreteSelector)
+		}
+		const table = this.patterns.get(method)
+		if (table) {
+			for (const [key, entry] of table) {
+				if (entry.until <= now) {
+					table.delete(key)
+					continue
+				}
+				if (entry.refreshed?.has(concretePath)) continue
+				if (pathMatchesPattern(concretePath, key.slice(key.indexOf(" ") + 1))) {
+					for (const m of entry.by) by.add(m)
+				}
+			}
+		}
+		return { by: [...by], isStale: by.size > 0 }
+	}
+
+	/**
+	 * A successful stale read clears the mark for that resource only: the exact entry, and this
+	 * concrete path's share of any pattern entry. Marks newer than the read's snapshot stay.
+	 */
+	clear(concreteSelector: string, concretePath: string, method: string, snapshot: number): void {
+		const exact = this.exact.get(concreteSelector)
+		if (exact && exact.seq <= snapshot) this.exact.delete(concreteSelector)
+		const table = this.patterns.get(method)
+		if (!table) return
+		for (const [key, entry] of table) {
+			if (entry.seq > snapshot || !entry.refreshed) continue
+			if (!pathMatchesPattern(concretePath, key.slice(key.indexOf(" ") + 1))) continue
+			if (entry.refreshed.size >= MAX_REFRESHED) {
+				const oldest = entry.refreshed.values().next().value
+				if (oldest !== undefined) entry.refreshed.delete(oldest)
+			}
+			entry.refreshed.add(concretePath)
+		}
 	}
-	return re.test(concretePath)
 }
 
-/* two-tier stale lookup: exact concrete match, then pattern fallback; sweeps expired entries in one pass */
+/**
+ * Two-tier stale lookup over a flat map (kept for compatibility): exact concrete match, then
+ * pattern entries for the same method. Keys are classified by their template placeholders,
+ * not by containing `:`. Expired entries are swept.
+ */
 export function lookupStale(
 	staleMap: Map<string, { by: string[]; seq: number; until: number }>,
 	concreteSelector: string,
@@ -85,30 +176,33 @@ export function lookupStale(
 	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)
-
+	const allBy = new Set<string>()
 	for (const [key, entry] of staleMap) {
 		if (entry.until <= now) {
-			expired.push(key)
+			staleMap.delete(key)
+			continue
+		}
+		if (key === concreteSelector) {
+			for (const m of entry.by) allBy.add(m)
 			continue
 		}
-		if (!key.includes(":")) continue
 		const spaceIdx = key.indexOf(" ")
-		const keyMethod = key.slice(0, spaceIdx)
+		if (key.slice(0, spaceIdx) !== method) continue
 		const keyPattern = key.slice(spaceIdx + 1)
-		if (keyMethod !== method) continue
-		if (pathMatchesPattern(concretePath, keyPattern)) {
-			allBy.push(...entry.by)
+		if (hasPlaceholder(keyPattern) && pathMatchesPattern(concretePath, keyPattern)) {
+			for (const m of entry.by) allBy.add(m)
 		}
 	}
-	for (const key of expired) staleMap.delete(key)
+	return { by: [...allBy], isStale: allBy.size > 0 }
+}
 
-	return { by: [...new Set(allBy)], isStale: allBy.length > 0 }
+function isServiceEntry(node: unknown): node is ServiceEntry {
+	return (
+		typeof node === "object" &&
+		node !== null &&
+		typeof (node as Record<string, unknown>)["method"] === "string" &&
+		typeof (node as Record<string, unknown>)["path"] === "string"
+	)
 }
 
 export function createSDK<T = Record<string, Record<string, (...args: unknown[]) => unknown>>>(
@@ -117,15 +211,15 @@ export function createSDK<T = Record<string, Record<string, (...args: unknown[])
 ): 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
+	const stale = staleTime > 0 ? new StaleIndex() : null
 
 	let invalidationSeq = 0
 
 	const rootCache = new Map<string, object>()
 
 	function buildLeafFn(entry: ServiceEntry, namePath: string[]): Function {
-		const path = toColonParams(entry.path)
+		/* Paths keep their template; HTTPClient interpolates `{name}` and `:name` alike. */
+		const path = entry.path
 		const method = entry.method
 		let fn: Function
 
@@ -151,13 +245,12 @@ export function createSDK<T = Record<string, Record<string, (...args: unknown[])
 			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 concretePath = interpolatePath(path, params ?? {})
 				const concreteSelector = `${method} ${concretePath}`
 				let requestMeta: RequestMeta | undefined
 
-				if (staleUntil) {
-					const now = Date.now()
-					const { by, isStale } = lookupStale(staleUntil, concreteSelector, concretePath, method, now)
+				if (stale) {
+					const { by, isStale } = stale.lookup(concreteSelector, concretePath, method, Date.now())
 					requestMeta = { invalidatedBy: by, isStale, selector: concreteSelector, seqSnapshot: invalidationSeq }
 				}
 
@@ -166,7 +259,7 @@ export function createSDK<T = Record<string, Record<string, (...args: unknown[])
 						? await http.request(method, path, opts, requestMeta)
 						: await http.requestSafe(method, path, opts, requestMeta)
 
-				if (staleUntil) {
+				if (stale) {
 					const isSuccess =
 						config.throwOnError === true
 							? true
@@ -176,34 +269,13 @@ export function createSDK<T = Record<string, Record<string, (...args: unknown[])
 						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 })
-								}
+							for (const target of resolveInvalidationTargets(entry.invalidate, params)) {
+								stale.mark(target, concreteSelector, 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)
+							stale.clear(concreteSelector, concretePath, method, requestMeta.seqSnapshot)
 						}
 					}
 				}
@@ -216,27 +288,39 @@ export function createSDK<T = Record<string, Record<string, (...args: unknown[])
 		return fn
 	}
 
+	/** Own keys only: names like `toString` or `constructor` must not resolve through the prototype. */
+	function resolveChild(node: Record<string, unknown>, key: string | symbol, namePath: string[]): unknown {
+		if (typeof key === "symbol" || key === "then") return undefined
+		const child = own(node, key)
+		if (child === undefined) {
+			if (key === "toString" || key === "toJSON")
+				return () => `[object HoneySDK${namePath.length ? ` ${namePath.join(".")}` : ""}]`
+			return undefined
+		}
+		return child
+	}
+
 	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
+				const child = resolveChild(node as Record<string, unknown>, key, namePath)
+				if (child === undefined || typeof child === "function") return child
+				const name = key as string
 
-				if (typeof (child as Record<string, unknown>)["method"] === "string") {
-					const cached = actionCache.get(key)
+				if (isServiceEntry(child)) {
+					const cached = actionCache.get(name)
 					if (cached) return cached
-					const fn = buildLeafFn(child as ServiceEntry, [...namePath, key])
-					actionCache.set(key, fn)
+					const fn = buildLeafFn(child, [...namePath, name])
+					actionCache.set(name, fn)
 					return fn
 				}
 
-				const cached = childCache.get(key)
+				const cached = childCache.get(name)
 				if (cached) return cached
-				const childProxy = makeNodeProxy(child as ServiceMapNode, [...namePath, key])
-				childCache.set(key, childProxy)
+				const childProxy = makeNodeProxy(child as ServiceMapNode, [...namePath, name])
+				childCache.set(name, childProxy)
 				return childProxy
 			},
 		})
@@ -247,23 +331,18 @@ export function createSDK<T = Record<string, Record<string, (...args: unknown[])
 			{},
 			{
 				get(_target, key: string | symbol) {
-					if (typeof key === "symbol") return undefined
+					const node = resolveChild(serviceMap as Record<string, unknown>, key, [])
+					if (node === undefined || typeof node === "function") return node
+					const name = key as string
 
-					const cached = rootCache.get(key as string)
+					const cached = rootCache.get(name)
 					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])
-					}
+					const result = isServiceEntry(node)
+						? (buildLeafFn(node, [name]) as unknown as object)
+						: makeNodeProxy(node as ServiceMapNode, [name])
 
-					rootCache.set(key as string, result)
+					rootCache.set(name, result)
 					return result
 				},
 			},

package/src/client/sse.ts

@@ -1,102 +1,128 @@
 export type SSEEvent = {
 	data: string
 	event?: string
+	/** The last event ID (sticky across events, as `EventSource.lastEventId`). Absent while empty. */
 	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
+const DEFAULT_MAX_BUFFER = 1024 * 1024
+
+/**
+ * Parse a `text/event-stream` body per the WHATWG HTML "event stream interpretation" rules:
+ *
+ * - lines end at CRLF, LF or CR (a CR at a chunk boundary waits for a possible LF);
+ * - a leading BOM is skipped;
+ * - `id` persists across events until changed, and an `id` containing NUL is ignored;
+ * - `retry` is accepted only when it is all ASCII digits;
+ * - an event still open when the stream ends is discarded, never dispatched.
+ *
+ * `maxBufferSize` caps both an unterminated line and the data of one event (UTF-16 code
+ * units); exceeding it throws.
+ */
+export async function* parseSSEStream(
+	stream: ReadableStream<Uint8Array>,
+	opts?: { maxBufferSize?: number },
+): AsyncGenerator<SSEEvent, void, undefined> {
+	const decoder = new TextDecoder()
+	const reader = stream.getReader()
+	const maxBuffer = opts?.maxBufferSize ?? DEFAULT_MAX_BUFFER
+
+	let pending = ""
+	let first = true
+	let data: string[] = []
+	let dataSize = 0
+	let hasData = false
 	let event: string | undefined
-	let id: string | undefined
+	let lastId = ""
 	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)
+	const dispatch = (): SSEEvent | undefined => {
+		const out = hasData ? ({ data: data.join("\n") } as SSEEvent) : undefined
+		if (out) {
+			if (event !== undefined && event !== "") out.event = event
+			if (lastId !== "") out.id = lastId
+			if (retry !== undefined) out.retry = retry
+			retry = undefined
 		}
+		data = []
+		dataSize = 0
+		hasData = false
+		event = undefined
+		return out
+	}
 
+	const processLine = (line: string): void => {
+		if (line.charCodeAt(0) === 58 /* : */) return
+		const colon = line.indexOf(":")
+		const field = colon === -1 ? line : line.slice(0, colon)
+		let value = colon === -1 ? "" : line.slice(colon + 1)
+		if (value.charCodeAt(0) === 32) value = value.slice(1)
 		switch (field) {
 			case "data":
-				data = data === undefined ? val : `${data}\n${val}`
+				dataSize += value.length + 1
+				if (dataSize > maxBuffer) throw new Error(`SSE event exceeded ${maxBuffer} characters`)
+				data.push(value)
+				hasData = true
 				break
 			case "event":
-				event = val
+				event = value
 				break
 			case "id":
-				/* per spec: id containing null byte must be ignored */
-				if (!val.includes("\0")) id = val
+				if (!value.includes("\0")) lastId = value
 				break
-			case "retry": {
-				const n = Number(val)
-				if (Number.isFinite(n) && n >= 0) retry = n
+			case "retry":
+				if (/^\d+$/.test(value)) retry = Number(value)
 				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`)
+			pending += decoder.decode(value, { stream: true })
+			if (first && pending.length > 0) {
+				if (pending.charCodeAt(0) === 0xfeff) pending = pending.slice(1)
+				first = false
 			}
 
-			/* 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
+			let start = 0
+			while (start < pending.length) {
+				let end = start
+				while (end < pending.length) {
+					const c = pending.charCodeAt(end)
+					if (c === 10 || c === 13) break
+					end++
+				}
+				if (end === pending.length) break
+				/* A CR as the last character may be the first half of CRLF. */
+				if (pending.charCodeAt(end) === 13 && end === pending.length - 1) break
+				const line = pending.slice(start, end)
+				start = end + (pending.charCodeAt(end) === 13 && pending.charCodeAt(end + 1) === 10 ? 2 : 1)
+				if (line === "") {
+					const out = dispatch()
+					if (out) yield out
+				} else {
+					processLine(line)
+				}
+			}
+			pending = pending.slice(start)
+			if (pending.length > maxBuffer) {
+				throw new Error(`SSE buffer exceeded ${maxBuffer} characters`)
 			}
 		}
-
-		/* flush remaining buffer */
-		if (buffer.trim() !== "") {
-			const event = parseBlock(buffer)
-			if (event) yield event
+		/* A lone CR held back at the end of the stream still terminates its line. */
+		if (pending.endsWith("\r")) {
+			const line = pending.slice(0, -1)
+			if (line === "") {
+				const out = dispatch()
+				if (out) yield out
+			}
 		}
+		/* Anything else still open is an incomplete event: discard it. */
 	} finally {
-		await reader.cancel()
+		await reader.cancel().catch(() => {})
 		reader.releaseLock()
 	}
 }