@fresho/router 0.4.0 → 0.6.0

package/dist/index.mjs

@@ -1,683 +1,6 @@
-import { n as runMiddleware } from "./middleware-XMbIevSv.mjs";
+import { n as runMiddleware } from "./middleware-B-_0PLA6.mjs";
+import { a as isFunction, c as compileSchema, i as router, n as generateDocs, o as isRoute, r as route, s as isRouter } from "./docs-B1IFBS_w.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
-		};
-	} };
-}
-
-//#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
-/** 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. */
-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 = {
-			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("?"),
-				schema: { type: type.replace("?", "").replace("[]", "") }
-			}));
-		}
-		if (route$1?.body && [
-			"post",
-			"put",
-			"patch"
-		].includes(method)) {
-			const bodySchema = route$1.body;
-			operation.requestBody = {
-				required: true,
-				content: { "application/json": { schema: {
-					type: "object",
-					properties: Object.fromEntries(Object.entries(bodySchema).map(([name, type]) => {
-						if (typeof type === "string") return [name, { type: type.replace("?", "").replace("[]", "") }];
-						return [name, { type: "object" }];
-					})),
-					required: Object.entries(bodySchema).filter(([, type]) => typeof type === "string" && !type.endsWith("?")).map(([name]) => name)
-				} } }
-			};
-		}
-		paths[path][method] = operation;
-	}
-	return {
-		openapi: "3.0.0",
-		info: {
-			title: config.title,
-			version: config.version,
-			description: config.description
-		},
-		paths
-	};
-}
-
-//#endregion
 //#region src/client-proxy.ts
 const PREFIXED_HTTP_METHODS = new Set([
 	"$get",
@@ -721,6 +44,22 @@ function createRecursiveProxy(config, segments = []) {
 	});
 }
 
+//#endregion
+//#region src/client-response.ts
+const STREAMING_CONTENT_TYPES = new Set([
+	"text/event-stream",
+	"application/x-ndjson",
+	"application/ndjson"
+]);
+/**
+* Parses ordinary client responses as JSON while preserving streaming bodies.
+*/
+async function parseClientResponse(response, raw = false) {
+	const contentType = response.headers.get("Content-Type")?.split(";", 1)[0].trim().toLowerCase();
+	if (raw || contentType && STREAMING_CONTENT_TYPES.has(contentType)) return response;
+	return response.json();
+}
+
 //#endregion
 //#region src/http-client.ts
 /**
@@ -796,6 +135,18 @@ const BODY_METHODS = new Set([
 * // GET /api/get
 * await client.api.get.$get();
 * ```
+*
+* @example Router built by a dependency-injected factory:
+* ```typescript
+* import type { createServer } from './server';
+* import { createHttpClient } from '@fresho/router';
+*
+* type Api = ReturnType<typeof createServer>['api'];
+*
+* const client = createHttpClient<Api>({
+*   baseUrl: 'https://api.example.com',
+* });
+* ```
 */
 function createHttpClient(config = {}) {
 	const sharedConfig = { current: { ...config } };
@@ -865,8 +216,7 @@ async function executeRequest(sharedConfig, segments, method, options) {
 	const fetchUrl = buildUrl(config, segments, options);
 	const response = await (config.fetch || fetch)(fetchUrl, init);
 	if (!response.ok) throw new Error(await response.text() || response.statusText);
-	if (options?.raw) return response;
-	return response.json();
+	return parseClientResponse(response, options?.raw);
 }
 
 //#endregion
@@ -1023,7 +373,7 @@ async function invokeHandler(sharedConfig, routerDef, segments, method, options)
 		executionCtx: options?.ctx ?? config.ctx
 	};
 	const result = await routeInfo.handler(context);
-	if (result instanceof Response) return result.json();
+	if (result instanceof Response) return parseClientResponse(result);
 	return result;
 }
 
@@ -1046,10 +396,14 @@ function formatSSEMessage(message) {
 *
 * @example
 * ```typescript
+* interface CounterEvents {
+*   tick: { count: number };
+* }
+*
 * const handler = async (c) => {
-*   return sseResponse(async (send, close) => {
+*   return sseResponse<CounterEvents>(async (send, close) => {
 *     for (let i = 0; i < 5; i++) {
-*       await send({ data: { count: i } });
+*       send({ event: 'tick', data: { count: i } });
 *       await new Promise(r => setTimeout(r, 1000));
 *     }
 *     close();