@fresho/router 0.5.0 → 0.6.1

package/dist/docs-C77XQzF3.mjs

@@ -0,0 +1,738 @@
+import { n as runMiddleware } from "./middleware-B-_0PLA6.mjs";
+
+//#region src/schema.ts
+/** Valid base types for primitives and arrays. */
+const PRIMITIVE_TYPES = [
+	"string",
+	"number",
+	"boolean",
+	"unknown"
+];
+/** Checks if a schema field is a nested object (not a type string or [type, description] tuple). */
+function isNestedSchema(field) {
+	return typeof field === "object" && field !== null && !Array.isArray(field);
+}
+/** Unpacks a schema field into its type string and optional description. */
+function unpackField(field) {
+	return Array.isArray(field) ? [field[0], field[1]] : [field, void 0];
+}
+/**
+* Validates and coerces a single primitive value.
+* Returns [success, result, errorMessage].
+*/
+function validatePrimitive(value, baseType) {
+	switch (baseType) {
+		case "string":
+			if (typeof value !== "string") return [
+				false,
+				void 0,
+				"Expected string"
+			];
+			return [
+				true,
+				value,
+				null
+			];
+		case "number": {
+			if (typeof value !== "number" && typeof value !== "string" || typeof value === "string" && value.trim() === "") return [
+				false,
+				void 0,
+				"Expected number"
+			];
+			const num = Number(value);
+			if (!Number.isFinite(num)) return [
+				false,
+				void 0,
+				"Expected number"
+			];
+			return [
+				true,
+				num,
+				null
+			];
+		}
+		case "boolean":
+			if (value === "true" || value === "1" || value === true) return [
+				true,
+				true,
+				null
+			];
+			else if (value === "false" || value === "0" || value === false) return [
+				true,
+				false,
+				null
+			];
+			return [
+				false,
+				void 0,
+				"Expected boolean (true/false)"
+			];
+		case "unknown": return [
+			true,
+			value,
+			null
+		];
+		default: return [
+			false,
+			void 0,
+			`Unknown type: ${baseType}`
+		];
+	}
+}
+/**
+* Validates a schema field value (primitive, array, or nested object).
+* Returns [success, result, errors].
+*/
+function validateField(key, field, value, parentPath = "") {
+	const fieldPath = parentPath ? `${parentPath}.${key}` : key;
+	const errors = {};
+	if (isNestedSchema(field)) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) {
+			errors[fieldPath] = ["Expected object"];
+			return [
+				false,
+				void 0,
+				errors
+			];
+		}
+		const nestedResult = validateSchema(field, value, fieldPath);
+		return [
+			nestedResult.success,
+			nestedResult.data,
+			nestedResult.errors
+		];
+	}
+	const [typeStr] = unpackField(field);
+	const isOptional = typeStr.endsWith("?");
+	const isArray = typeStr.includes("[]");
+	let baseType = isOptional ? typeStr.slice(0, -1) : typeStr;
+	if (isArray) baseType = baseType.replace("[]", "");
+	if (value === void 0 || value === null || value === "") {
+		if (!isOptional) {
+			errors[fieldPath] = ["Required"];
+			return [
+				false,
+				void 0,
+				errors
+			];
+		}
+		return [
+			true,
+			void 0,
+			{}
+		];
+	}
+	if (isArray) {
+		if (!Array.isArray(value)) {
+			errors[fieldPath] = ["Expected array"];
+			return [
+				false,
+				void 0,
+				errors
+			];
+		}
+		const resultArray = [];
+		for (let i = 0; i < value.length; i++) {
+			const [success$1, coerced$1, errorMsg$1] = validatePrimitive(value[i], baseType);
+			if (!success$1) {
+				errors[`${fieldPath}[${i}]`] = [errorMsg$1];
+				return [
+					false,
+					void 0,
+					errors
+				];
+			}
+			resultArray.push(coerced$1);
+		}
+		return [
+			true,
+			resultArray,
+			{}
+		];
+	}
+	const [success, coerced, errorMsg] = validatePrimitive(value, baseType);
+	if (!success) {
+		errors[fieldPath] = [errorMsg];
+		return [
+			false,
+			void 0,
+			errors
+		];
+	}
+	return [
+		true,
+		coerced,
+		{}
+	];
+}
+/**
+* Validates a full schema against data.
+* Returns { success, data, errors }.
+*/
+function validateSchema(schema, data, parentPath = "") {
+	const result = {};
+	const allErrors = {};
+	const source = typeof data === "object" && data !== null && !Array.isArray(data) ? data : {};
+	for (const [key, field] of Object.entries(schema)) {
+		const [success, coerced, fieldErrors] = validateField(key, field, Object.hasOwn(source, key) ? source[key] : void 0, parentPath);
+		if (!success) Object.assign(allErrors, fieldErrors);
+		else if (coerced !== void 0) result[key] = coerced;
+	}
+	return {
+		success: Object.keys(allErrors).length === 0,
+		data: result,
+		errors: allErrors
+	};
+}
+/** Validates schema definition at compile time. */
+function validateSchemaDefinition(schema, path = "") {
+	for (const [key, field] of Object.entries(schema)) {
+		const fieldPath = path ? `${path}.${key}` : key;
+		if (isNestedSchema(field)) validateSchemaDefinition(field, fieldPath);
+		else {
+			if (Array.isArray(field) && (field.length !== 2 || typeof field[0] !== "string" || typeof field[1] !== "string")) throw new Error(`Invalid field definition at '${fieldPath}'`);
+			const [typeStr] = unpackField(field);
+			if (typeof typeStr !== "string") throw new Error(`Unknown type '${String(typeStr)}' at '${fieldPath}'`);
+			let baseType = typeStr.endsWith("?") ? typeStr.slice(0, -1) : typeStr;
+			baseType = baseType.replace("[]", "");
+			if (!PRIMITIVE_TYPES.includes(baseType)) throw new Error(`Unknown type '${typeStr}' at '${fieldPath}'`);
+		}
+	}
+}
+/**
+* Compiles a schema definition into a validator.
+*
+* Used internally by the router to validate query parameters and request bodies.
+* Provides a Zod-compatible `safeParse` API for consistency.
+*
+* @param schema - The schema definition object
+* @returns A compiled schema with `safeParse` method
+*
+* @example
+* ```typescript
+* const userSchema = compileSchema({
+*   name: 'string',
+*   age: 'number',
+*   email: 'string?',
+* });
+*
+* const result = userSchema.safeParse({ name: 'Alice', age: 30 });
+* if (result.success) {
+*   console.log(result.data.name); // 'Alice'
+* } else {
+*   console.log(result.error.flatten().fieldErrors);
+* }
+* ```
+*/
+function compileSchema(schema) {
+	validateSchemaDefinition(schema);
+	return { safeParse(data) {
+		const { success, data: result, errors } = validateSchema(schema, data);
+		if (!success) return {
+			success: false,
+			error: { flatten: () => ({ fieldErrors: errors }) }
+		};
+		return {
+			success: true,
+			data: result
+		};
+	} };
+}
+/**
+* Converts a schema definition to JSON Schema, recursing into nested objects.
+*/
+function toJsonSchema(schema) {
+	const properties = {};
+	const required = [];
+	for (const [key, field] of Object.entries(schema)) {
+		if (isNestedSchema(field)) {
+			properties[key] = toJsonSchema(field);
+			required.push(key);
+			continue;
+		}
+		const [typeStr, description] = unpackField(field);
+		const described = description === void 0 ? {} : { description };
+		const optional = typeStr.endsWith("?");
+		const base = optional ? typeStr.slice(0, -1) : typeStr;
+		const primitive = base.replace("[]", "");
+		const item = primitive === "unknown" ? {} : { type: primitive };
+		properties[key] = base.endsWith("[]") ? {
+			type: "array",
+			items: item,
+			...described
+		} : {
+			...item,
+			...described
+		};
+		if (!optional) required.push(key);
+	}
+	return {
+		type: "object",
+		properties,
+		...required.length > 0 && { required }
+	};
+}
+
+//#endregion
+//#region src/types.ts
+/** HTTP method property names. */
+const HTTP_METHODS = new Set([
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete",
+	"options",
+	"head"
+]);
+/** Symbol to mark an object as a route definition. */
+const ROUTE_MARKER = Symbol.for("@fresho/router:route");
+/** Symbol to mark an object as a router. */
+const ROUTER_MARKER = Symbol.for("@fresho/router:router");
+/** Checks if a value is a function. */
+function isFunction(value) {
+	return typeof value === "function";
+}
+/** Checks if entry is a Route (marked with ROUTE_MARKER). */
+function isRoute(entry) {
+	return typeof entry === "object" && entry !== null && ROUTE_MARKER in entry;
+}
+/** Checks if entry is a Router (marked with ROUTER_MARKER). */
+function isRouter(entry) {
+	return typeof entry === "object" && entry !== null && ROUTER_MARKER in entry;
+}
+
+//#endregion
+//#region src/handler.ts
+/**
+* Escapes special regex characters in a string.
+*/
+function escapeRegex(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Converts a path with :param segments to a regex pattern.
+*/
+function pathToRegex(path) {
+	const paramNames = [];
+	const parts = path.split(/:(\w+)/g);
+	let regexStr = "";
+	for (let i = 0; i < parts.length; i++) if (i % 2 === 0) regexStr += escapeRegex(parts[i]);
+	else {
+		paramNames.push(parts[i]);
+		regexStr += "([^/]+)";
+	}
+	return {
+		pattern: /* @__PURE__ */ new RegExp(`^${regexStr}$`),
+		paramNames
+	};
+}
+/**
+* Converts a property name to a path segment.
+* - `$param` becomes `:param`
+* - Other names become literal segments
+*/
+function propertyToSegment$1(prop) {
+	if (prop.startsWith("$")) return `:${prop.slice(1)}`;
+	return prop;
+}
+/** Collects and compiles all routes from a router tree. */
+function compileRoutes(routerDef, parentPath = "", parentMiddleware = []) {
+	const currentMiddleware = [...parentMiddleware, ...routerDef.middleware || []];
+	const compiled = [];
+	for (const [prop, entry] of Object.entries(routerDef.routes)) if (isRouter(entry)) {
+		const segment = propertyToSegment$1(prop);
+		const newPath = parentPath ? `${parentPath}/${segment}` : `/${segment}`;
+		compiled.push(...compileRoutes(entry, newPath, currentMiddleware));
+	} else if (HTTP_METHODS.has(prop)) {
+		const method = prop.toUpperCase();
+		const { pattern, paramNames } = pathToRegex(parentPath || "/");
+		if (isFunction(entry)) compiled.push({
+			method,
+			pattern,
+			paramNames,
+			handler: entry,
+			middleware: currentMiddleware
+		});
+		else if (isRoute(entry)) {
+			const routeDef = entry;
+			compiled.push({
+				method,
+				pattern,
+				paramNames,
+				handler: routeDef.handler,
+				middleware: currentMiddleware,
+				querySchema: routeDef.query ? compileSchema(routeDef.query) : void 0,
+				bodySchema: routeDef.body ? compileSchema(routeDef.body) : void 0
+			});
+		}
+	}
+	return compiled;
+}
+/**
+* Strips the body from a response for HEAD requests.
+*/
+function stripBodyForHead(response, isHead) {
+	if (!isHead) return response;
+	return new Response(null, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers
+	});
+}
+/**
+* Creates a fetch handler from a router definition.
+*
+* @example
+* ```typescript
+* const api = router({
+*   health: router({
+*     get: async () => ({ status: 'ok' }),
+*   }),
+*   users: router({
+*     get: async () => [...],
+*     $id: router({
+*       get: async (c) => ({ id: c.path.id }),
+*     }),
+*   }),
+* });
+*
+* export default { fetch: api.handler() };
+* ```
+*/
+function createHandler(routerDef) {
+	const compiledRoutes = compileRoutes(routerDef);
+	return async (request, env, ctx) => {
+		const url = new URL(request.url);
+		const method = request.method.toUpperCase();
+		const isHead = method === "HEAD";
+		for (const compiled of compiledRoutes) {
+			if (!(compiled.method === method || method === "OPTIONS" || method === "HEAD" && compiled.method === "GET")) continue;
+			const match = compiled.pattern.exec(url.pathname);
+			if (!match) continue;
+			const path = {};
+			for (let i = 0; i < compiled.paramNames.length; i++) path[compiled.paramNames[i]] = decodeURIComponent(match[i + 1]);
+			const context = {
+				request,
+				path,
+				query: {},
+				body: {},
+				env,
+				executionCtx: ctx
+			};
+			if (compiled.middleware.length > 0 || compiled.handler || compiled.querySchema || compiled.bodySchema) return stripBodyForHead(await runMiddleware(compiled.middleware, context, async () => {
+				const routeId = `${compiled.method} ${url.pathname}`;
+				let query = {};
+				if (compiled.querySchema) {
+					const raw = Object.fromEntries(url.searchParams);
+					const result = compiled.querySchema.safeParse(raw);
+					if (!result.success) return Response.json({
+						error: "Invalid query parameters",
+						route: routeId,
+						details: result.error.flatten()
+					}, { status: 400 });
+					query = result.data;
+				}
+				let body = {};
+				if (compiled.bodySchema && [
+					"POST",
+					"PUT",
+					"PATCH"
+				].includes(method)) {
+					const raw = await request.json().catch(() => ({}));
+					const result = compiled.bodySchema.safeParse(raw);
+					if (!result.success) return Response.json({
+						error: "Invalid request body",
+						route: routeId,
+						details: result.error.flatten()
+					}, { status: 400 });
+					body = result.data;
+				}
+				context.query = query;
+				context.body = body;
+				if (compiled.handler) {
+					const handlerContext = {
+						request,
+						path,
+						query,
+						body,
+						env,
+						executionCtx: ctx
+					};
+					for (const key of Object.keys(context)) if (![
+						"request",
+						"path",
+						"query",
+						"body",
+						"env",
+						"executionCtx"
+					].includes(key)) handlerContext[key] = context[key];
+					const result = await compiled.handler(handlerContext);
+					if (result instanceof Response) return result;
+					return Response.json(result);
+				}
+				return Response.json({});
+			}), isHead);
+			return stripBodyForHead(Response.json({}), isHead);
+		}
+		return Response.json({ error: "Not Found" }, { status: 404 });
+	};
+}
+
+//#endregion
+//#region src/core.ts
+/**
+* @fileoverview Core route and router creation functions.
+*
+* ## Path Convention
+* - Property names = URL path segments
+* - `$param` prefix = dynamic segment (`:param`)
+* - `get`, `post`, `put`, `patch`, `delete` = HTTP method handlers
+*
+* ## Typing Best Practices
+*
+* **Schemas** (`query`/`body`) provide runtime validation AND type inference.
+* Use them for any input that needs validation:
+* ```typescript
+* get: route({
+*   query: { limit: 'number?' },
+*   handler: async (c) => c.query.limit,  // limit: number | undefined
+* })
+* ```
+*
+* **Context** (`route.ctx<T>()`) provides types only (no validation).
+* Use it for path params, env bindings, and middleware-injected values:
+* ```typescript
+* interface MyContext {
+*   path: { id: string };
+*   env: { DB: Database };
+*   user: { name: string };  // from auth middleware
+* }
+* get: route.ctx<MyContext>()({
+*   handler: async (c) => ({ id: c.path.id, user: c.user.name }),
+* })
+* ```
+*
+* **Important:** Don't add explicit type annotations to handler parameters.
+* Let types flow from schemas and context:
+* ```typescript
+* // GOOD: types inferred from schema
+* handler: async (c) => c.query.limit
+*
+* // BAD: redundant type annotation
+* handler: async (c: { query: { limit?: number } }) => c.query.limit
+* ```
+*/
+/**
+* Creates a route with query/body validation schemas.
+*
+* Use `route()` when you need request validation. For simple handlers
+* without validation, you can use bare functions directly in the router.
+*
+* @example
+* ```typescript
+* // Route with query validation
+* get: route({
+*   query: { limit: 'number?', offset: 'number?' },
+*   handler: async (c) => {
+*     const items = await db.list(c.query.limit, c.query.offset);
+*     return { items };
+*   },
+* })
+*
+* // Route with body validation
+* post: route({
+*   body: { name: 'string', email: 'string' },
+*   handler: async (c) => {
+*     const user = await db.create(c.body);
+*     return user;
+*   },
+* })
+*
+* // Simple handler without validation (bare function)
+* get: async () => ({ status: 'ok' })
+* ```
+*/
+function route(definition) {
+	return {
+		...definition,
+		[ROUTE_MARKER]: true
+	};
+}
+/** Creates a chainable context builder. */
+function createCtxBuilder() {
+	const builder = (definition) => ({
+		...definition,
+		[ROUTE_MARKER]: true
+	});
+	builder.ctx = () => createCtxBuilder();
+	return builder;
+}
+/**
+* Creates a route with typed context for values not covered by schemas.
+*
+* Use `route.ctx<T>()` to type:
+* - **Path params**: `{ path: { id: string } }` for `$id` segments
+* - **Env bindings**: `{ env: { DB: Database } }` for runtime environment
+* - **Middleware values**: `{ user: User }` for auth middleware, etc.
+*
+* Context provides types only, not runtime validation. For validated inputs,
+* use `query` and `body` schemas instead.
+*
+* @example
+* ```typescript
+* interface AppContext {
+*   path: { id: string };
+*   env: { DB: D1Database };
+*   user: { id: string };  // injected by auth middleware
+* }
+*
+* $id: router({
+*   get: route.ctx<AppContext>()({
+*     query: { include: 'string?' },  // schema for validation
+*     handler: async (c) => {
+*       // c.path.id, c.env.DB, c.user.id - from context
+*       // c.query.include - from schema
+*       return c.env.DB.get(c.path.id);
+*     },
+*   }),
+* })
+* ```
+*/
+route.ctx = () => createCtxBuilder();
+/**
+* Creates a router that groups paths and applies middleware.
+*
+* @example
+* ```typescript
+* const api = router({
+*   health: router({
+*     get: async () => ({ status: 'ok' }),
+*   }),
+*
+*   users: router({
+*     // GET /users - list users
+*     get: route({
+*       query: { limit: 'number?' },
+*       handler: async (c) => db.users.list(c.query.limit),
+*     }),
+*
+*     // POST /users - create user
+*     post: route({
+*       body: { name: 'string', email: 'string' },
+*       handler: async (c) => db.users.create(c.body),
+*     }),
+*
+*     // /users/:id
+*     $id: router({
+*       get: async (c) => db.users.get(c.path.id),
+*       delete: async (c) => db.users.delete(c.path.id),
+*     }),
+*   }),
+* });
+*
+* export default { fetch: api.handler() };
+* ```
+*/
+function router(routes, ...middleware) {
+	const self = {
+		routes,
+		middleware: middleware.length > 0 ? middleware : void 0,
+		handler() {
+			return createHandler(self);
+		}
+	};
+	self[ROUTER_MARKER] = true;
+	return self;
+}
+
+//#endregion
+//#region src/docs.ts
+/**
+* @fileoverview OpenAPI documentation generation.
+*
+* Generates OpenAPI 3.0 documentation from router definitions.
+*
+* **Path Convention:**
+* - Property names = URL path segments
+* - `$param` prefix = dynamic segment (`{param}` in OpenAPI)
+* - `get`, `post`, `put`, `patch`, `delete` = HTTP method handlers
+*/
+/** Converts property name to path segment, handling $param convention. */
+function propertyToSegment(prop) {
+	if (prop.startsWith("$")) return `{${prop.slice(1)}}`;
+	return prop;
+}
+/** Collects all routes from a router tree, with `{param}` path segments. */
+function collectRoutes(routerDef, parentPath = "") {
+	const collectedRoutes = [];
+	for (const [prop, entry] of Object.entries(routerDef.routes)) if (HTTP_METHODS.has(prop)) {
+		const path = parentPath || "/";
+		if (isFunction(entry)) collectedRoutes.push({
+			path,
+			method: prop,
+			route: null
+		});
+		else if (isRoute(entry)) collectedRoutes.push({
+			path,
+			method: prop,
+			route: entry
+		});
+	} else if (isRouter(entry)) {
+		const segment = propertyToSegment(prop);
+		const newPath = parentPath ? `${parentPath}/${segment}` : `/${segment}`;
+		collectedRoutes.push(...collectRoutes(entry, newPath));
+	}
+	return collectedRoutes;
+}
+/** Generates OpenAPI documentation from a router. */
+function generateDocs(config) {
+	const paths = {};
+	const allRoutes = collectRoutes(config.router);
+	for (const { path, method, route: route$1 } of allRoutes) {
+		if (!paths[path]) paths[path] = {};
+		const operation = {
+			operationId: route$1?.operationId,
+			description: route$1?.description,
+			responses: {
+				200: { description: "Successful response" },
+				400: { description: "Validation error" }
+			}
+		};
+		if (route$1?.query) {
+			const querySchema = route$1.query;
+			operation.parameters = Object.entries(querySchema).filter(([, field]) => !isNestedSchema(field)).map(([name, field]) => {
+				const [type, description] = unpackField(field);
+				return {
+					name,
+					in: "query",
+					required: !type.endsWith("?"),
+					description,
+					schema: { type: type.replace("?", "").replace("[]", "") }
+				};
+			});
+		}
+		if (route$1?.body && [
+			"post",
+			"put",
+			"patch"
+		].includes(method)) operation.requestBody = {
+			required: true,
+			content: { "application/json": { schema: toJsonSchema(route$1.body) } }
+		};
+		paths[path][method] = operation;
+	}
+	return {
+		openapi: "3.0.0",
+		info: {
+			title: config.title,
+			version: config.version,
+			description: config.description
+		},
+		paths
+	};
+}
+
+//#endregion
+export { isFunction as a, compileSchema as c, unpackField as d, router as i, isNestedSchema as l, generateDocs as n, isRoute as o, route as r, isRouter as s, collectRoutes as t, toJsonSchema as u };
+//# sourceMappingURL=docs-C77XQzF3.mjs.map