@fresho/router 0.4.0 → 0.6.0

package/dist/docs-B1IFBS_w.mjs

@@ -0,0 +1,724 @@
+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). */
+function isNestedSchema(field) {
+	return typeof field === "object" && field !== null;
+}
+/**
+* Validates and coerces a single primitive value.
+* Returns [success, result, errorMessage].
+*/
+function validatePrimitive(value, baseType) {
+	switch (baseType) {
+		case "string": return [
+			true,
+			String(value),
+			null
+		];
+		case "number": {
+			const num = Number(value);
+			if (Number.isNaN(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 = 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 === "") {
+		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 = {};
+	for (const [key, field] of Object.entries(schema)) {
+		const value = data[key];
+		const [success, coerced, fieldErrors] = validateField(key, field, value, 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 {
+			const typeStr = field;
+			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.
+*
+* @param descriptions - Field descriptions keyed by name, dotted for nested fields
+* @param prefix - Dotted path of `schema` within the root, for nested lookups
+*/
+function toJsonSchema(schema, descriptions = {}, prefix = "") {
+	const properties = {};
+	const required = [];
+	for (const [key, field] of Object.entries(schema)) {
+		const description = descriptions[`${prefix}${key}`];
+		const described = description === void 0 ? {} : { description };
+		if (isNestedSchema(field)) {
+			properties[key] = {
+				...toJsonSchema(field, descriptions, `${prefix}${key}.`),
+				...described
+			};
+			required.push(key);
+			continue;
+		}
+		const optional = field.endsWith("?");
+		const base = optional ? field.slice(0, -1) : field;
+		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(([, type]) => typeof type === "string").map(([name, type]) => ({
+				name,
+				in: "query",
+				required: !type.endsWith("?"),
+				description: route$1.descriptions?.[name],
+				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, route$1.descriptions) } }
+		};
+		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, router as i, toJsonSchema as l, generateDocs as n, isRoute as o, route as r, isRouter as s, collectRoutes as t };
+//# sourceMappingURL=docs-B1IFBS_w.mjs.map