@lovrozagar/honey 0.1.0 → 0.2.0

package/src/ip-restrict.ts

@@ -1,3 +1,4 @@
+import { namedMiddleware } from "./middleware.ts"
 import { HoneyError } from "./error.ts"
 import type { MiddlewareFn } from "./middleware.ts"
 import { EK, SK } from "./types.ts"
@@ -188,5 +189,5 @@ export function ipRestrict(opts: IpRestrictOptions): MiddlewareFn<{ req: Request
 		return next()
 	}
 
-	return mw
+	return namedMiddleware("ipRestrict", mw)
 }

package/src/logger.ts

@@ -1,3 +1,4 @@
+import { namedMiddleware } from "./middleware.ts"
 import type { MiddlewareFn } from "./middleware.ts"
 
 /* ── log levels (pino-compatible numeric values) ── */
@@ -45,9 +46,10 @@ function createLogger(opts?: CreateLoggerOptions): LoggerInstance {
 
 	function emit(level: number, first: Record<string, unknown> | string, second?: string): void {
 		if (level < threshold) return
-		const obj = typeof first === "string"
-			? { ...base, level, msg: first, time: Date.now() }
-			: { ...base, ...first, level, msg: second ?? "", time: Date.now() }
+		const obj =
+			typeof first === "string"
+				? { ...base, level, msg: first, time: Date.now() }
+				: { ...base, ...first, level, msg: second ?? "", time: Date.now() }
 		write(JSON.stringify(obj))
 	}
 
@@ -95,25 +97,23 @@ function defaultLog(data: LogData): void {
 const noop = () => {}
 const noopLogger: LoggerInstance = createLogger({ level: "fatal", write: noop })
 
-function logger(
-	options?: LoggerOptions,
-): MiddlewareFn<{ path: string, req: Request }, { log: LoggerInstance }> {
+function logger(options?: LoggerOptions): MiddlewareFn<{ path: string; req: Request }, { log: LoggerInstance }> {
 	const log = options?.log ?? defaultLog
 	const skip = options?.skip
 	const instance = options?.instance
 
-	return async (ctx, next) => {
+	return namedMiddleware("logger", async (ctx, next) => {
 		const start = performance.now()
 		const method = ctx.req.method
 		const path = ctx.path
-		const rid = (ctx as Record<string, unknown>)["requestId"] as string | null ?? null
+		const rid = ((ctx as Record<string, unknown>)["requestId"] as string | null) ?? null
 
 		const child = instance
 			? instance.child({
-				method,
-				path,
-				...(rid ? { requestId: rid } : {}),
-			})
+					method,
+					path,
+					...(rid ? { requestId: rid } : {}),
+				})
 			: noopLogger
 
 		if (instance) {
@@ -142,7 +142,7 @@ function logger(
 		}
 
 		return response
-	}
+	})
 }
 
 export { createLogger, logger }

package/src/middleware.ts

@@ -1,27 +1,39 @@
 /** phantom wrapper — at runtime it's just Response, carries TAdds for inference */
 export type MiddlewareResult<TAdds = {}> = Response & {
-	readonly __adds?: TAdds;
-};
-
-export type MiddlewareFn<
-	TCtx = {},
-	TAdds = {},
-	TErrors extends string = string,
-> = ((
+	readonly __adds?: TAdds
+}
+
+export type MiddlewareFn<TCtx = {}, TAdds = {}, TErrors extends string = string> = ((
 	ctx: TCtx,
 	next: {
-		<T>(additions: T): Promise<MiddlewareResult<T>>;
-		(): Promise<MiddlewareResult<{}>>;
+		<T>(additions: T): Promise<MiddlewareResult<T>>
+		(): Promise<MiddlewareResult<{}>>
 	},
 ) => Promise<MiddlewareResult<TAdds>>) & {
-	errors?: readonly TErrors[];
-};
+	errors?: readonly TErrors[]
+	/** Meta this middleware contributes to every route that mounts it. Codegen + `ctx.meta` */
+	meta?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Stamp a stable name on a middleware closure.
+ *
+ * `Function.prototype.name` is inferred by whatever transpiled the module — jiti (used by
+ * `honey generate`) and rollup (used by `vite build`) disagree about a closure returned from
+ * a factory, which made the generated manifest differ between the two. Naming shipped
+ * middleware explicitly makes the manifest deterministic, and "cors" reads better than
+ * "anonymous" besides.
+ */
+export function namedMiddleware<T extends object>(name: string, fn: T): T {
+	Object.defineProperty(fn, "name", { configurable: true, value: name })
+	return fn
+}
 
 /** runtime type for stored middleware — erased generics, used internally */
 export type RuntimeMiddleware = (
 	ctx: Record<string, unknown>,
 	next: (additions?: Record<string, unknown>) => Promise<Response>,
-) => Promise<Response>;
+) => Promise<Response>
 
 /**
  * Create middleware with error keys constrained to a factory.
@@ -33,21 +45,38 @@ export function defineMiddleware<
 	TFactory extends Record<string, (...args: never[]) => unknown>,
 	TKeys extends keyof TFactory & string,
 >(opts: {
-	errors?: [TFactory, ...TKeys[]];
-	fn: MiddlewareFn<TReqs, TAdds>;
+	errors?: [TFactory, ...TKeys[]]
+	fn: MiddlewareFn<TReqs, TAdds>
+	meta?: Record<string, unknown>
 }): MiddlewareFn<TReqs, TAdds, TKeys> {
-	const fn = opts.fn as MiddlewareFn<TReqs, TAdds, TKeys>;
+	const fn = opts.fn as MiddlewareFn<TReqs, TAdds, TKeys>
 	if (opts.errors) {
-		const [, ...keys] = opts.errors;
-		Object.defineProperty(fn, "errors", { value: keys });
+		const [, ...keys] = opts.errors
+		Object.defineProperty(fn, "errors", { value: keys })
+	}
+	if (opts.meta) attachMiddlewareMeta(fn, opts.meta)
+	return fn
+}
+
+/**
+ * `internal` decides whether a route appears in generated artifacts at all. A middleware that
+ * set it would silently remove routes from the document, which is not noticeable by reading
+ * either the route or the middleware — so it is the one key middleware may not contribute.
+ */
+function attachMiddlewareMeta(fn: object, meta: Record<string, unknown>): void {
+	if ("internal" in meta) {
+		throw new Error(
+			'middleware meta cannot set "internal" — it controls whether routes appear in generated ' +
+				"artifacts; set it on the route with .meta({ internal: true })",
+		)
 	}
-	return fn;
+	Object.defineProperty(fn, "meta", { value: Object.freeze({ ...meta }) })
 }
 
 type NextFn = {
-	<T>(additions: T): Promise<MiddlewareResult<T>>;
-	(): Promise<MiddlewareResult<{}>>;
-};
+	<T>(additions: T): Promise<MiddlewareResult<T>>
+	(): Promise<MiddlewareResult<{}>>
+}
 
 /** Extract TAdds from callback return type — distributes over unions */
 type ExtractAdds<T> = T extends Promise<MiddlewareResult<infer A>> ? A : never
@@ -58,25 +87,38 @@ type ExtractAdds<T> = T extends Promise<MiddlewareResult<infer A>> ? A : never
  */
 export function createMiddleware<TReqs = {}, TRet extends Promise<Response> = Promise<MiddlewareResult<{}>>>(
 	fn: (ctx: TReqs, next: NextFn) => TRet,
+	opts?: { meta?: Record<string, unknown> },
 ): MiddlewareFn<TReqs, ExtractAdds<TRet>> {
+	if (opts?.meta) attachMiddlewareMeta(fn, opts.meta)
 	return fn as MiddlewareFn<TReqs, ExtractAdds<TRet>>
 }
 
+/**
+ * Merge meta contributed by a middleware chain, in mount order. Resolved once at route
+ * registration — never per request, because the precompiled route tree bakes `mt` as a literal
+ * and a lazily-derived value would diverge from it.
+ */
+export function collectMiddlewareMeta(
+	groups: ReadonlyArray<ReadonlyArray<RuntimeMiddleware>>,
+): Record<string, unknown> | null {
+	let out: Record<string, unknown> | undefined
+	for (const group of groups) {
+		for (const mw of group) {
+			const meta = (mw as { meta?: Readonly<Record<string, unknown>> }).meta
+			if (!meta) continue
+			if (out === undefined) out = {}
+			Object.assign(out, meta)
+		}
+	}
+	return out ?? null
+}
+
 /**
  * Context properties that middleware additions must not overwrite.
  * These are set by the framework during request construction.
  * TypeScript prevents this at compile time; this guard catches runtime bypasses.
  */
-const RESERVED_CTX_KEYS = new Set([
-	"background",
-	"cookies",
-	"env",
-	"headers",
-	"params",
-	"req",
-	"res",
-	"search",
-]);
+const RESERVED_CTX_KEYS = new Set(["background", "cookies", "env", "headers", "params", "req", "res", "search"])
 
 /**
  * Compile a middleware chain + handler into a single function at registration time.
@@ -89,66 +131,60 @@ export function compileChain(
 	if (middlewares.length === 0) {
 		/* sync fast path — avoids microtask overhead for sync handlers */
 		return (ctx) => {
-			const result = handler(ctx);
+			const result = handler(ctx)
 			if (result instanceof Promise) {
-				return result.then(validateResponse);
+				return result.then(validateResponse)
 			}
 			if (result === undefined || result === null) {
-				throw new Error(
-					"handler must return a Response — did you forget 'return ctx.res...()'?",
-				);
+				throw new Error("handler must return a Response — did you forget 'return ctx.res...()'?")
 			}
-			return result;
-		};
+			return result
+		}
 	}
 
 	if (middlewares.length === 1) {
-		const mw = middlewares[0];
+		const mw = middlewares[0]
 		if (!mw) {
-			throw new Error("middleware chain invariant violated");
+			throw new Error("middleware chain invariant violated")
 		}
 		return (ctx) => {
-			const mwCtx = ctx as Record<string, unknown>;
-			let called = false;
+			const mwCtx = ctx as Record<string, unknown>
+			let called = false
 			return Promise.resolve(
 				mw(mwCtx, (additions?: Record<string, unknown>) => {
-					if (called) throw new Error("next() called multiple times");
-					called = true;
-					if (additions) mergeAdditions(ctx, additions);
-					return Promise.resolve(handler(ctx)).then(validateResponse);
+					if (called) throw new Error("next() called multiple times")
+					called = true
+					if (additions) mergeAdditions(ctx, additions)
+					return Promise.resolve(handler(ctx)).then(validateResponse)
 				}),
-			).then(validateMiddlewareResponse);
-		};
+			).then(validateMiddlewareResponse)
+		}
 	}
 
 	/* general case — pre-bind middleware array, no per-request index tracking */
-	return (ctx) => executeChain(middlewares, ctx, handler);
+	return (ctx) => executeChain(middlewares, ctx, handler)
 }
 
 function mergeAdditions(ctx: object, additions: Record<string, unknown>): void {
 	for (const key in additions) {
 		if (!RESERVED_CTX_KEYS.has(key)) {
-			(ctx as Record<string, unknown>)[key] = additions[key];
+			;(ctx as Record<string, unknown>)[key] = additions[key]
 		}
 	}
 }
 
 function validateResponse(result: Response): Response {
 	if (result === undefined || result === null) {
-		throw new Error(
-			"handler must return a Response — did you forget 'return ctx.res...()'?",
-		);
+		throw new Error("handler must return a Response — did you forget 'return ctx.res...()'?")
 	}
-	return result;
+	return result
 }
 
 function validateMiddlewareResponse(result: Response): Response {
 	if (result === undefined || result === null) {
-		throw new Error(
-			"middleware must return a Response — did you forget 'return next(...)'?",
-		);
+		throw new Error("middleware must return a Response — did you forget 'return next(...)'?")
 	}
-	return result;
+	return result
 }
 
 export function executeChain(
@@ -156,44 +192,40 @@ export function executeChain(
 	ctx: object,
 	handler: (ctx: object) => Response | Promise<Response>,
 ): Promise<Response> {
-	let index = 0;
+	let index = 0
 	/* middleware runtime type uses Record<string, unknown> — object satisfies at runtime */
-	const mwCtx = ctx as Record<string, unknown>;
+	const mwCtx = ctx as Record<string, unknown>
 
 	function dispatch(): Promise<Response> {
 		if (index >= middlewares.length) {
 			return Promise.resolve(handler(ctx)).then((result) => {
 				if (result === undefined || result === null) {
-					throw new Error(
-						"handler must return a Response — did you forget 'return ctx.res...()'?",
-					);
+					throw new Error("handler must return a Response — did you forget 'return ctx.res...()'?")
 				}
-				return result;
-			});
+				return result
+			})
 		}
-		const mw = middlewares[index++];
+		const mw = middlewares[index++]
 		if (!mw) {
-			throw new Error("middleware chain invariant violated");
+			throw new Error("middleware chain invariant violated")
 		}
-		let called = false;
+		let called = false
 		return Promise.resolve(
 			mw(mwCtx, (additions?: Record<string, unknown>) => {
 				if (called) {
-					throw new Error("next() called multiple times");
+					throw new Error("next() called multiple times")
 				}
-				called = true;
-				if (additions) mergeAdditions(ctx, additions);
-				return dispatch();
+				called = true
+				if (additions) mergeAdditions(ctx, additions)
+				return dispatch()
 			}),
 		).then((result) => {
 			if (result === undefined || result === null) {
-				throw new Error(
-					"middleware must return a Response — did you forget 'return next(...)'?",
-				);
+				throw new Error("middleware must return a Response — did you forget 'return next(...)'?")
 			}
-			return result;
-		});
+			return result
+		})
 	}
 
-	return dispatch();
+	return dispatch()
 }

package/src/node-request.ts

@@ -121,7 +121,8 @@ export class NodeRequest {
 	get body(): ReadableStream<Uint8Array> | null {
 		if (!this.#hasBody) return null
 		if (this.#webBody === undefined) {
-			this.#webBody = Readable.toWeb(this.#incoming) as ReadableStream<Uint8Array>
+			// Node's web stream and the DOM/Bun ReadableStream brands do not overlap.
+			this.#webBody = Readable.toWeb(this.#incoming) as unknown as ReadableStream<Uint8Array>
 		}
 		return this.#webBody
 	}

package/src/node.ts

@@ -16,14 +16,16 @@ type ServeOptions<TEnv> = {
 const BUFFER_BODY_MAX = 256 * 1024
 const RAW_BODY = Symbol.for("honey.rawBody")
 
+// Node's `Readable.fromWeb` wants `node:stream/web` streams; DOM/Bun brands do not overlap.
+function asNodeWebStream(stream: ReadableStream<Uint8Array>): import("node:stream/web").ReadableStream {
+	return stream as unknown as import("node:stream/web").ReadableStream
+}
+
 function incomingToRequest(req: IncomingMessage): Request {
 	return incomingToNodeRequest(req)
 }
 
-function collectNodeHeaders(
-	response: Response,
-	extra?: Record<string, string>,
-): Record<string, string | string[]> {
+function collectNodeHeaders(response: Response, extra?: Record<string, string>): Record<string, string | string[]> {
 	const headerObj: Record<string, string | string[]> = {}
 	let hasSetCookie = false
 	response.headers.forEach((value, key) => {
@@ -79,7 +81,7 @@ async function responseToNode(response: Response, res: ServerResponse): Promise<
 		}
 		res.writeHead(response.status, response.plainHeaders)
 		try {
-			await pipeline(Readable.fromWeb(stream as import("node:stream/web").ReadableStream), res)
+			await pipeline(Readable.fromWeb(asNodeWebStream(stream)), res)
 		} catch {
 			if (!res.destroyed) res.destroy()
 		}
@@ -104,17 +106,14 @@ async function responseToNode(response: Response, res: ServerResponse): Promise<
 	if (shouldBufferBody(response)) {
 		const buf = Buffer.from(await response.arrayBuffer())
 		if (res.destroyed) return
-		res.writeHead(
-			response.status,
-			collectNodeHeaders(response, { "content-length": String(buf.byteLength) }),
-		)
+		res.writeHead(response.status, collectNodeHeaders(response, { "content-length": String(buf.byteLength) }))
 		res.end(buf)
 		return
 	}
 
 	res.writeHead(response.status, collectNodeHeaders(response))
 	try {
-		await pipeline(Readable.fromWeb(body as import("node:stream/web").ReadableStream), res)
+		await pipeline(Readable.fromWeb(asNodeWebStream(body)), res)
 	} catch {
 		if (!res.destroyed) res.destroy()
 	}

package/src/openapi/register.ts

@@ -6,8 +6,7 @@ import { registerOpenApiRuntime } from "./spec-factory.ts"
 
 export function enableOpenApi(): void {
 	registerOpenApiRuntime({
-		docsUi: (kind, specUrl) =>
-			kind === "swagger" ? swagger({ url: specUrl }) : scalar({ url: specUrl }),
+		docsUi: (kind, specUrl) => (kind === "swagger" ? swagger({ url: specUrl }) : scalar({ url: specUrl })),
 		generateManifest: (app) => Promise.resolve(generateManifest(app as never)),
 		generateOpenApi: (app, options) => generateOpenApi(app as never, options),
 		toYaml,

package/src/openapi/scalar.ts

@@ -1,17 +1,17 @@
 import type { TypedResponse } from "../response.ts"
 
 type ScalarOptions = {
-  url: string
-  [key: string]: unknown
+	url: string
+	[key: string]: unknown
 }
 
 export function scalar(
-  options: ScalarOptions,
+	options: ScalarOptions,
 ): (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => TypedResponse {
-  const { url, ...rest } = options
-  const config = JSON.stringify({ url, ...rest })
+	const { url, ...rest } = options
+	const config = JSON.stringify({ url, ...rest })
 
-  const html = `<!DOCTYPE html>
+	const html = `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="utf-8" />
@@ -27,7 +27,7 @@ export function scalar(
 </body>
 </html>`
 
-  const handler = (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => ctx.res.html("ok", html)
-  Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
-  return handler
+	const handler = (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => ctx.res.html("ok", html)
+	Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
+	return handler
 }

package/src/openapi/spec-factory.ts

@@ -5,6 +5,7 @@ export type OpenApiGenerate = (
 	options: {
 		filterRoutes?: (route: { meta: unknown; method: string; path: string }) => boolean
 		info: { description?: string; title: string; version: string }
+		profile?: string
 		securitySchemes?: Record<string, unknown>
 	},
 ) => Promise<unknown>
@@ -27,8 +28,7 @@ export type OpenApiRuntime = {
 	toYaml: YamlGenerate
 }
 
-const MISSING =
-	'Runtime OpenAPI/manifest generation requires `import "@lovrozagar/honey/openapi"` in the app entry.'
+const MISSING = 'Runtime OpenAPI/manifest generation requires `import "@lovrozagar/honey/openapi"` in the app entry.'
 
 let runtime: OpenApiRuntime | undefined
 

package/src/openapi/spec.ts

@@ -4,28 +4,35 @@ import type { DefaultMeta } from "../types.ts"
 import type { TypedResponse } from "../response.ts"
 
 type SpecOptions<TMeta = Record<string, unknown> | null> = {
-  description?: string
-  filterRoutes?: (route: OpenApiRouteInfo<DefaultMeta & TMeta>) => boolean
-  securitySchemes?: Record<string, unknown>
-  title: string
-  version: string
+	description?: string
+	filterRoutes?: (route: OpenApiRouteInfo<DefaultMeta & TMeta>) => boolean
+	/** Named metaSpec profile selecting which emitted keys this document carries */
+	profile?: string
+	securitySchemes?: Record<string, unknown>
+	title: string
+	version: string
 }
 
 export function spec<TMeta = Record<string, unknown> | null>(
-  options: SpecOptions<TMeta>,
+	options: SpecOptions<TMeta>,
 ): (ctx: { res: { json(sk: "ok", data: unknown): TypedResponse } }) => TypedResponse | Promise<TypedResponse> {
-  let cached: string | null = null
+	let cached: string | null = null
 
-  const handler = async (ctx: { res: { json(sk: "ok", data: unknown): TypedResponse } }) => {
-    if (cached === null) {
-      const desc = Object.getOwnPropertyDescriptor(handler, Symbol.for("honey.app"))
-      const openApiSpec = desc
-        ? await generateOpenApi(desc.value, { filterRoutes: options.filterRoutes, info: options, securitySchemes: options.securitySchemes })
-        : {}
-      cached = JSON.stringify(openApiSpec)
-    }
-    return ctx.res.json("ok", JSON.parse(cached))
-  }
-  Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
-  return handler
+	const handler = async (ctx: { res: { json(sk: "ok", data: unknown): TypedResponse } }) => {
+		if (cached === null) {
+			const desc = Object.getOwnPropertyDescriptor(handler, Symbol.for("honey.app"))
+			const openApiSpec = desc
+				? await generateOpenApi(desc.value, {
+						filterRoutes: options.filterRoutes,
+						info: options,
+						profile: options.profile,
+						securitySchemes: options.securitySchemes,
+					})
+				: {}
+			cached = JSON.stringify(openApiSpec)
+		}
+		return ctx.res.json("ok", JSON.parse(cached))
+	}
+	Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
+	return handler
 }

package/src/openapi/swagger.ts

@@ -1,17 +1,17 @@
 import type { TypedResponse } from "../response.ts"
 
 type SwaggerOptions = {
-  url: string
-  [key: string]: unknown
+	url: string
+	[key: string]: unknown
 }
 
 export function swagger(
-  options: SwaggerOptions,
+	options: SwaggerOptions,
 ): (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => TypedResponse {
-  const { url, ...rest } = options
-  const config = JSON.stringify({ dom_id: "#swagger-ui", url, ...rest })
+	const { url, ...rest } = options
+	const config = JSON.stringify({ dom_id: "#swagger-ui", url, ...rest })
 
-  const html = `<!DOCTYPE html>
+	const html = `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="utf-8" />
@@ -28,7 +28,7 @@ export function swagger(
 </body>
 </html>`
 
-  const handler = (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => ctx.res.html("ok", html)
-  Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
-  return handler
+	const handler = (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => ctx.res.html("ok", html)
+	Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
+	return handler
 }