@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/src/init.ts

@@ -1,161 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { basename, dirname, join } from "node:path"
-import { fileURLToPath } from "node:url"
-import type { InitFlags } from "./cli-args.ts"
-
-export type { InitFlags } from "./cli-args.ts"
-export { parseInitFlags } from "./cli-args.ts"
-
-type PackageJson = {
-	dependencies?: Record<string, string>
-	name?: string
-	private?: boolean
-	scripts?: Record<string, string>
-	type?: string
-}
-
-const APP_TS = `import { honey } from "@lovrozagar/honey"
-
-export const app = honey()
-	.get("/health")
-	.handler((ctx) => ctx.res.text("ok", "ok"))
-	.openapi({ docs: "scalar", title: "Honey", version: "0.0.1" })
-`
-
-const SERVER_TS = `import { app } from "./app.ts"
-
-const port = Number(process.env.PORT ?? 3000)
-await app.serve({ port })
-`
-
-const VITE_CONFIG_TS = `import { honey } from "@lovrozagar/honey/plugin"
-
-export default {
-	plugins: [
-		honey({
-			app: "src/app.ts",
-		}),
-	],
-}
-`
-
-const WORKER_TS = `import { cfWebSocket } from "@lovrozagar/honey/ws/cloudflare"
-import { app } from "./app.ts"
-
-app.wsAdapter(cfWebSocket())
-
-export default {
-	fetch: (req: Request, env: Record<string, unknown>, ctx: unknown) => app.fetch(req, env, ctx),
-}
-`
-
-export function runInit(cwd: string, flags: InitFlags): void {
-	const files: Record<string, string> = {
-		"src/app.ts": APP_TS,
-		"src/server.ts": SERVER_TS,
-		"vite.config.ts": VITE_CONFIG_TS,
-	}
-	if (flags.cf) {
-		files["src/worker.ts"] = WORKER_TS
-		files["wrangler.jsonc"] = wranglerJsonc(packageNameFromDir(cwd))
-	}
-
-	const collisions = Object.keys(files).filter((rel) => existsSync(join(cwd, rel)))
-	if (collisions.length > 0 && !flags.force) {
-		throw new Error(`${collisions[0]} already exists. Use --force to overwrite.`)
-	}
-
-	for (const [rel, contents] of Object.entries(files)) {
-		writeText(join(cwd, rel), contents)
-	}
-	writePackageJson(cwd, flags.force)
-	console.log("honey: initialized")
-}
-
-function wranglerJsonc(name: string): string {
-	return `{
-	"compatibility_date": "2026-01-20",
-	"compatibility_flags": ["nodejs_compat"],
-	"main": "src/worker.ts",
-	"name": ${JSON.stringify(name)},
-	"workers_dev": true
-}
-`
-}
-
-const PACKAGE_NAME = "@lovrozagar/honey"
-
-const SCRIPTS: Record<string, string> = {
-	dev: "bun --watch src/server.ts",
-	generate: "honey generate",
-}
-
-/**
- * Creates package.json, or adds what is missing to an existing one. Existing scripts, `type` and
- * dependency ranges are kept unless `force` is set; each kept value is reported.
- */
-function writePackageJson(cwd: string, force: boolean): void {
-	const path = join(cwd, "package.json")
-	const exists = existsSync(path)
-	const existing = exists ? readPackageJson(path) : {}
-	const notes: string[] = []
-
-	const scripts = { ...existing.scripts }
-	for (const [name, command] of Object.entries(SCRIPTS)) {
-		const current = scripts[name]
-		if (current === undefined || current === command || force) scripts[name] = command
-		else notes.push(`kept scripts.${name} ("${current}"); honey expects "${command}"`)
-	}
-
-	const dependencies = { ...existing.dependencies }
-	if (dependencies[PACKAGE_NAME] === undefined || force) dependencies[PACKAGE_NAME] = `^${honeyVersion()}`
-
-	const next: PackageJson = { ...existing, dependencies, scripts }
-	if (!exists) {
-		next.name = packageNameFromDir(cwd)
-		next.private = true
-	}
-	if (existing.type === undefined) {
-		if (!exists || force) next.type = "module"
-		else notes.push('package.json has no "type"; the scaffold is ESM, so set "type": "module" or rerun with --force')
-	}
-
-	writeText(path, `${JSON.stringify(next, null, "\t")}\n`)
-	for (const note of notes) console.log(`honey: ${note}`)
-}
-
-function readPackageJson(path: string): PackageJson {
-	let parsed: unknown
-	try {
-		parsed = JSON.parse(readFileSync(path, "utf-8"))
-	} catch {
-		throw new Error(`package.json is not valid JSON`)
-	}
-	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-		throw new Error("package.json must be an object")
-	}
-	return parsed as PackageJson
-}
-
-function writeText(path: string, contents: string): void {
-	mkdirSync(dirname(path), { recursive: true })
-	writeFileSync(path, contents.endsWith("\n") ? contents : `${contents}\n`, "utf-8")
-}
-
-function packageNameFromDir(dir: string): string {
-	const base = basename(dir)
-		.toLowerCase()
-		.replace(/[^a-z0-9._-]+/g, "-")
-		.replace(/^[-.]+|[-.]+$/g, "")
-	return base || "honey-app"
-}
-
-function honeyVersion(): string {
-	try {
-		const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json")
-		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string }
-		return typeof pkg.version === "string" ? pkg.version : "0.0.1"
-	} catch {
-		return "0.0.1"
-	}
-}

package/src/input.ts

@@ -1,8 +0,0 @@
-export type ReadableStreamSchema<T> = {
-	readonly _tag: "readableStream"
-	readonly schema: T
-}
-
-export function readableStream<T>(schema: T): ReadableStreamSchema<T> {
-	return { _tag: "readableStream", schema }
-}

package/src/invalidate-check.ts

@@ -1,205 +0,0 @@
-/**
- * Codegen-time check: mutations that declare no `invalidate`.
- *
- * This is a correctness signal, not a documentation one. `x-invalidate` drives generated SDK
- * behavior — the Rust and Go clients expand it into an invalidation post-flight and the Python
- * client reads it — so a mutation with no `invalidate` produces clients that refresh nothing
- * after the call. Create a row and the caller's cached collection still shows the old list.
- * Silent, and one per undeclared mutation.
- *
- * It warns and never blocks by default, because plenty of mutations correctly invalidate
- * nothing (login, logout, webhook receipt, a fire-and-forget job) and plenty of honey users
- * never generate an SDK. A rule that fails the build teaches people to paste the shortest token
- * that makes it pass, and then the annotation means "shut up" instead of "I considered this".
- */
-
-/** How a missing `invalidate` is reported. Default `"warn"` */
-export type InvalidateCheckLevel = "error" | "off" | "warn"
-
-export type InvalidateCheckConfig =
-	| {
-			/**
-			 * Operation extension identifying the entity an operation touches — e.g. `"x-entity"`
-			 * if the app's metaSpec maps a publisher descriptor onto that key. When both a mutation
-			 * and a read carry the same value under this key, that is a sharper signal than path
-			 * shape. honey does not own the key's name; the app says which one it uses.
-			 */
-			entityKey?: string
-			level?: InvalidateCheckLevel
-	  }
-	| InvalidateCheckLevel
-
-export type InvalidateCheckOperation = {
-	/** Lowercased HTTP method */
-	method: string
-	/** Route meta as authored, needed to tell "absent" from a deliberate "nothing" */
-	meta: Record<string, unknown> | null
-	/** The emitted operation object */
-	operation: Record<string, unknown>
-	/** OpenAPI-style path */
-	path: string
-}
-
-const MUTATION_METHODS = new Set(["delete", "patch", "post", "put"])
-const MAX_LISTED = 20
-
-function resolveConfig(config: InvalidateCheckConfig | undefined): { entityKey?: string; level: InvalidateCheckLevel } {
-	if (config === undefined) return { level: "warn" }
-	if (typeof config === "string") return { level: config }
-	return { entityKey: config.entityKey, level: config.level ?? "warn" }
-}
-
-/**
- * Did the author record a decision? `null` and `[]` both say "this mutation refreshes nothing",
- * which is a statement; absent says nothing at all, which is what this check is looking for.
- *
- * Neither reaches the document — `x-invalidate` is emitted only for a non-empty array — so this
- * costs a consumer nothing and changes no output.
- */
-function declaredNothing(meta: Record<string, unknown> | null): boolean {
-	if (!meta || !Object.hasOwn(meta, "invalidate")) return false
-	const value = meta.invalidate
-	return value === null || (Array.isArray(value) && value.length === 0)
-}
-
-/**
- * Did the author declare targets? Read from the meta, not the emitted operation: a profile
- * that leaves `x-invalidate` out of its document must not make every declared mutation look
- * undeclared.
- */
-function alreadyInvalidates(entry: InvalidateCheckOperation): boolean {
-	const declared = entry.meta?.invalidate
-	if (Array.isArray(declared) && declared.length > 0) return true
-	const emitted = entry.operation["x-invalidate"]
-	return Array.isArray(emitted) && emitted.length > 0
-}
-
-/**
- * Paths a mutation plausibly affects: its own, and its collection when the mutation targets an
- * item. `DELETE /tables/{id}` affects `GET /tables/{id}` and `GET /tables`; `POST /auth/logout`
- * affects neither `GET /auth/logout` nor `GET /auth`, and so is never mentioned.
- */
-function pathFamily(path: string): string[] {
-	const family = [path]
-	const segments = path.split("/")
-	const last = segments[segments.length - 1]
-	if (last !== undefined && last.startsWith("{") && last.endsWith("}") && segments.length > 2) {
-		family.push(segments.slice(0, -1).join("/"))
-	}
-	return family
-}
-
-export type InvalidateFinding = {
-	/** Read operations that make this mutation look like an oversight */
-	affects: string[]
-	method: string
-	path: string
-}
-
-/** Mutations with no `invalidate` that the document suggests should have one. */
-export function findMissingInvalidate(
-	operations: readonly InvalidateCheckOperation[],
-	entityKey: string | undefined,
-): InvalidateFinding[] {
-	const readPaths = new Set<string>()
-	const readsByEntity = new Map<string, string[]>()
-
-	for (const entry of operations) {
-		if (entry.method !== "get") continue
-		readPaths.add(entry.path)
-		if (entityKey === undefined) continue
-		const entity = entry.operation[entityKey]
-		if (entity === undefined || entity === null) continue
-		const id = JSON.stringify(entity)
-		const list = readsByEntity.get(id)
-		if (list) list.push(`GET ${entry.path}`)
-		else readsByEntity.set(id, [`GET ${entry.path}`])
-	}
-
-	const findings: InvalidateFinding[] = []
-	for (const entry of operations) {
-		if (!MUTATION_METHODS.has(entry.method)) continue
-		if (alreadyInvalidates(entry)) continue
-		if (declaredNothing(entry.meta)) continue
-
-		let affects: string[] = []
-		const entity = entityKey === undefined ? undefined : entry.operation[entityKey]
-		if (entity !== undefined && entity !== null) {
-			/* sharper than path shape: the same entity is read somewhere else in the document */
-			affects = readsByEntity.get(JSON.stringify(entity)) ?? []
-		}
-		if (affects.length === 0) {
-			/* no reader is tagged with the entity — path shape is still a signal, not silence */
-			affects = pathFamily(entry.path)
-				.filter((candidate) => readPaths.has(candidate))
-				.map((candidate) => `GET ${candidate}`)
-		}
-
-		if (affects.length > 0) {
-			findings.push({ affects, method: entry.method.toUpperCase(), path: entry.path })
-		}
-	}
-	return findings
-}
-
-function formatReport(findings: readonly InvalidateFinding[]): string {
-	const width = Math.max(...findings.map((f) => f.method.length))
-	const shown = findings
-		.slice(0, MAX_LISTED)
-		.map((f) => `  ${f.method.padEnd(width)} ${f.path} → ${f.affects.join(", ")}`)
-	const more = findings.length > shown.length ? `\n  … and ${findings.length - shown.length} more` : ""
-	return (
-		`[honey:invalidate] ${findings.length} mutation(s) declare no \`invalidate\`, but the document has ` +
-		`read routes they plausibly affect.\nGenerated SDK clients refresh nothing after these calls.\n` +
-		`${shown.join("\n")}${more}\n` +
-		"Declare the routes each one refreshes, or `invalidate: null` to record that it refreshes nothing."
-	)
-}
-
-/**
- * Report mutations with no `invalidate`. One summary, never one line per operation — a warning
- * that fires 53 times gets filtered out of the log; one that fires once and lists 10 gets read.
- */
-export function reportMissingInvalidate(
-	operations: readonly InvalidateCheckOperation[],
-	config: InvalidateCheckConfig | undefined,
-): void {
-	const { entityKey, level } = resolveConfig(config)
-	if (level === "off") return
-
-	const findings = findMissingInvalidate(operations, entityKey)
-	if (findings.length === 0) return
-
-	const report = formatReport(findings)
-	if (level === "error") throw new Error(report)
-	console.warn(report)
-}
-
-/**
- * `invalidate` selectors that name no route. A selector is `"<METHOD> <pattern>"`, exactly as
- * the generated `RouteSelector` union spells it; anything else invalidates nothing at runtime.
- */
-export function findInvalidSelectors(
-	operations: readonly InvalidateCheckOperation[],
-	inventory: ReadonlySet<string>,
-): Array<{ method: string; path: string; selector: unknown }> {
-	const out: Array<{ method: string; path: string; selector: unknown }> = []
-	const seen = new Set<string>()
-	for (const entry of operations) {
-		const declared = entry.meta?.invalidate
-		if (!Array.isArray(declared)) continue
-		for (const selector of declared) {
-			if (typeof selector === "string" && inventory.has(selector)) continue
-			const key = `${entry.method} ${entry.path} ${String(selector)}`
-			if (seen.has(key)) continue
-			seen.add(key)
-			out.push({ method: entry.method.toUpperCase(), path: entry.path, selector })
-		}
-	}
-	return out
-}
-
-/** The level an `invalidate` config reports at. */
-export function invalidateLevel(config: InvalidateCheckConfig | undefined): InvalidateCheckLevel {
-	return resolveConfig(config).level
-}

package/src/invoke-user.ts

@@ -1,95 +0,0 @@
-/**
- * Containment for user callbacks the framework calls outside a request's middleware chain
- * (WebSocket and realtime events, adapter hooks). A sync throw or a rejection never escapes
- * into the runtime, where it would be an uncaught exception or an unhandled rejection and,
- * on Node, end the process.
- */
-
-/** The error side of a structured logger (`error(obj, msg)`), e.g. honey/logger. */
-export type InvokeLogger = {
-	error?: (obj: Record<string, unknown>, msg?: string) => void
-}
-
-export type InvokeOptions = {
-	/** Where the callback's error goes. When it throws or rejects itself, that is logged and it is not called again for its own error. */
-	onError?: ((err: unknown) => unknown) | null
-	/** The app logger; `console.error` when absent. */
-	log?: InvokeLogger | null
-	/** A label for the log line (`"open"`, `"message"`, …). */
-	phase: string
-	/** Extra fields for the log line. */
-	fields?: Record<string, unknown>
-}
-
-function logFailure(err: unknown, opts: InvokeOptions, phase: string): void {
-	const fields = { ...opts.fields, err, phase }
-	try {
-		if (opts.log?.error) {
-			opts.log.error(fields, "callback failed")
-			return
-		}
-	} catch {
-		/* a broken logger must not take the callback's place as the thing that escapes */
-	}
-	console.error("honey: callback failed", fields)
-}
-
-function isThenable(value: unknown): value is PromiseLike<unknown> {
-	return value !== null && typeof value === "object" && typeof (value as { then?: unknown }).then === "function"
-}
-
-/** Report `err` through `onError`, or log it. Never throws, never rejects. */
-export function reportUserError(err: unknown, opts: InvokeOptions): void {
-	const onError = opts.onError
-	if (!onError) {
-		logFailure(err, opts, opts.phase)
-		return
-	}
-	try {
-		const r = onError(err)
-		if (isThenable(r)) r.then(undefined, (e: unknown) => logFailure(e, opts, "onError"))
-	} catch (e) {
-		logFailure(e, opts, "onError")
-	}
-}
-
-/**
- * Call `fn` and resolve once it settles. Resolves `true` when it succeeded and `false` when it
- * threw or rejected (the error went to `onError` or the logger). Never rejects.
- */
-export function invokeUser(fn: () => unknown, opts: InvokeOptions): Promise<boolean> {
-	try {
-		const r = fn()
-		if (isThenable(r)) {
-			return Promise.resolve(r).then(
-				() => true,
-				(e: unknown) => {
-					reportUserError(e, opts)
-					return false
-				},
-			)
-		}
-		return Promise.resolve(true)
-	} catch (e) {
-		reportUserError(e, opts)
-		return Promise.resolve(false)
-	}
-}
-
-/**
- * One ordered event queue: each task starts after the previous one settled, and a failing task
- * never stops the ones after it.
- */
-export function createEventQueue(): { push(task: () => Promise<unknown>): Promise<void> } {
-	let tail: Promise<void> = Promise.resolve()
-	return {
-		push(task) {
-			const next = tail.then(task).then(
-				() => undefined,
-				() => undefined,
-			)
-			tail = next
-			return next
-		},
-	}
-}

package/src/ip-restrict.ts

@@ -1,79 +0,0 @@
-import { namedMiddleware } from "./middleware.ts"
-import { HoneyError } from "./error.ts"
-import { ipInRange, parseIp, parseIpRange, type IpRange } from "./ip.ts"
-import type { MiddlewareFn } from "./middleware.ts"
-import { EK, SK } from "./types.ts"
-
-type IpRestrictOptions = {
-	/** Addresses and CIDR ranges allowed through. When set, everything else is rejected. */
-	allowList?: string[]
-	/** Addresses and CIDR ranges rejected. Checked before `allowList`. */
-	denyList?: string[]
-	/**
-	 * Returns the client address, replacing `ctx.ip`. Leave it out to use `ctx.ip`, which the
-	 * app's `trustProxy()` setting decides — the same address every other feature sees.
-	 */
-	getIp?: (req: Request) => string | null
-}
-
-function parseRules(list: readonly string[] | undefined, name: string): IpRange[] {
-	if (list === undefined) return []
-	return list.map((rule) => {
-		const range = typeof rule === "string" ? parseIpRange(rule) : null
-		if (range === null)
-			throw new Error(`ipRestrict: ${name} entry ${JSON.stringify(rule)} is not an IP address or CIDR range`)
-		return range
-	})
-}
-
-function throwForbidden(): never {
-	throw new HoneyError({
-		errorKey: EK.forbidden,
-		status: SK.forbidden,
-	})
-}
-
-/**
- * Allows or rejects requests by client address. Rules and addresses are compared in canonical
- * numeric form, so `::ffff:203.0.113.7`, `203.0.113.7` and `203.0.113.7:51234` are one address.
- *
- * Fails closed: a request whose address is unknown or unparseable is rejected with 403, under
- * a deny list as much as under an allow list.
- */
-export function ipRestrict(opts: IpRestrictOptions): MiddlewareFn<{ req: Request }, {}> {
-	const legacy = opts as { trustCloudflare?: unknown; trustProxy?: unknown }
-	if (legacy.trustProxy !== undefined || legacy.trustCloudflare !== undefined) {
-		throw new Error(
-			"ipRestrict: `trustProxy` and `trustCloudflare` moved to the app. Call `app.trustProxy(1)` " +
-				"(one reverse proxy) or `app.trustProxy([...proxy ranges])`; on Cloudflare Workers `ctx.ip` " +
-				"already reads CF-Connecting-IP.",
-		)
-	}
-	if (opts.allowList !== undefined && opts.allowList.length === 0) {
-		throw new Error("ipRestrict: `allowList: []` would reject every request. Remove the middleware or list addresses.")
-	}
-	const denyRules = parseRules(opts.denyList, "denyList")
-	const allowRules = parseRules(opts.allowList, "allowList")
-	if (denyRules.length === 0 && allowRules.length === 0) {
-		throw new Error("ipRestrict: pass a non-empty `allowList` or `denyList`")
-	}
-	const getIp = opts.getIp
-
-	const mw: MiddlewareFn<{ req: Request }, {}> = (ctx, next) => {
-		const raw = getIp ? getIp(ctx.req) : ((ctx as { ip?: string | null }).ip ?? null)
-		const addr = raw === null || raw === "" ? null : parseIp(raw)
-
-		/* fail closed: an unknown address can match neither list */
-		if (addr === null) throwForbidden()
-
-		for (const rule of denyRules) {
-			if (ipInRange(addr, rule)) throwForbidden()
-		}
-
-		if (allowRules.length > 0 && !allowRules.some((rule) => ipInRange(addr, rule))) throwForbidden()
-
-		return next()
-	}
-
-	return namedMiddleware("ipRestrict", mw)
-}