semola 0.5.0 → 0.5.2

package/README.md

@@ -18,15 +18,18 @@ Type-safe APIs, Redis queues, pub/sub, i18n, caching & auth with tree-shakeable
 
 ## ✨ Features
 
-| Module               | Description                                            | Import          |
-| -------------------- | ------------------------------------------------------ | --------------- |
-| **🚀 API Framework** | Type-safe REST API with OpenAPI & Bun-native routing   | `semola/api`    |
-| **📬 Queue**         | Redis-backed job queue with timeouts & concurrency     | `semola/queue`  |
-| **📡 PubSub**        | Type-safe Redis pub/sub for real-time messaging        | `semola/pubsub` |
-| **🔐 Policy**        | Policy-based authorization with type-safe guards       | `semola/policy` |
-| **🌍 i18n**          | Compile-time validated internationalization            | `semola/i18n`   |
-| **💾 Cache**         | Redis cache wrapper with TTL & automatic serialization | `semola/cache`  |
-| **⚠️ Errors**        | Result-based error handling without try/catch          | `semola/errors` |
+| Module               | Description                                            | Import           |
+| -------------------- | ------------------------------------------------------ | ---------------- |
+| **🚀 API Framework** | Type-safe REST API with OpenAPI & Bun-native routing   | `semola/api`     |
+| **📬 Queue**         | Redis-backed job queue with timeouts & concurrency     | `semola/queue`   |
+| **📡 PubSub**        | Type-safe Redis pub/sub for real-time messaging        | `semola/pubsub`  |
+| **🔐 Policy**        | Policy-based authorization with type-safe guards       | `semola/policy`  |
+| **🌍 i18n**          | Compile-time validated internationalization            | `semola/i18n`    |
+| **💾 Cache**         | Redis cache wrapper with TTL & automatic serialization | `semola/cache`   |
+| **⏰ Cron**          | In-memory cron scheduler for periodic task execution   | `semola/cron`    |
+| **⚠️ Errors**        | Result-based error handling without try/catch          | `semola/errors`  |
+| **📃 Logging**       | A simple logging utility                               | `semola/logging` |
+| **⌨️ Prompts**       | Interactive zero-dependency CLI prompts                | `semola/prompts` |
 
 ---
 
@@ -135,24 +138,49 @@ const [error, user] = await cache.get("user:123");
 if (!error) console.log(user);
 ```
 
+### Schedule Recurring Tasks
+
+```typescript
+import { Cron } from "semola/cron";
+
+const cleanup = new Cron({
+  name: "daily-cleanup",
+  schedule: "0 0 * * *", // Daily at midnight
+  handler: async () => {
+    await deleteOldLogs();
+    await archiveInactiveUsers();
+  },
+});
+
+cleanup.start();
+```
+
 ### Check Permissions
 
 ```typescript
-import { Policy } from "semola/policy";
+import { Policy, eq, has } from "semola/policy";
+
+type User = { id: number; role: string; permissions: string[] };
 
-const policy = new Policy();
+const policy = new Policy<User>();
+
+// Allow admins full access
+policy.allow({
+  action: ["create", "update", "delete"],
+  conditions: { role: eq("admin") },
+  reason: "Admins have full access",
+});
 
-// Allow admins to edit any post
+// Allow users with a specific permission
 policy.allow({
-  action: "update",
-  entity: "post",
-  conditions: { role: "admin" },
-  reason: "Admins can edit any post",
+  action: "read",
+  conditions: { permissions: has("posts:read") },
 });
 
-// Check if user can edit
-const result = policy.can("update", "post", { role: user.role });
-console.log(result.allowed); // true or false
+// Check if user can perform an action
+const user: User = { id: 1, role: "admin", permissions: [] };
+const result = policy.can("update", user);
+console.log(result.allowed); // true
 ```
 
 ### Internationalize Your App
@@ -171,6 +199,15 @@ const i18n = new I18n({
 console.log(i18n.translate("greeting", { name: "World" }));
 ```
 
+### Log your messages
+
+```typescript
+import { ConsoleProvider, Logger } from "semola/logging";
+
+const logger = new Logger("database", [new ConsoleProvider()]);
+logger.info("Hello!");
+```
+
 ---
 
 ## 📦 Installation
@@ -202,6 +239,21 @@ Stop piecing together half-baked solutions from npm. Stop wrestling with type de
 | **Tree-Shakeable**    |   ✅   |   ❌    |   ❌    |  ✅  |   ✅   |
 | **Standard Schema**   |   ✅   |   ❌    |   ❌    |  ⚠️  |   ✅   |
 
+### Performance Benchmarks
+
+Semola API is the **fastest API framework** for Bun.
+
+| Framework  | Avg Req/Sec | Latency Avg (ms) |  vs Semola   |
+| :--------- | ----------: | ---------------: | :----------: |
+| **Semola** |  **40,050** |         **1.88** | **baseline** |
+| Elysia     |      37,185 |             2.13 | 1.1x slower  |
+| Hono       |      34,611 |             2.31 | 1.2x slower  |
+| Fastify    |      26,330 |             3.70 | 1.5x slower  |
+| Express    |      20,031 |             5.02 |  2x slower   |
+| NestJS     |      16,118 |             6.21 | 2.5x slower  |
+
+_Higher is better for req/sec, lower is better for latency._
+
 ### What Makes Semola Different
 
 - 🎯 **Bun-first**: Engineered specifically for Bun's performance. No Node.js baggage.
@@ -219,10 +271,13 @@ Stop piecing together half-baked solutions from npm. Stop wrestling with type de
 - [API Framework](./docs/api.md) - Type-safe REST API framework with OpenAPI
 - [Queue](./docs/queue.md) - Redis-backed job queue with timeouts & concurrency
 - [PubSub](./docs/pubsub.md) - Type-safe Redis pub/sub
+- [Cron](./docs/cron.md) - In-memory cron scheduler for periodic task execution
 - [Policy](./docs/policy.md) - Policy-based authorization
 - [i18n](./docs/i18n.md) - Type-safe internationalization
 - [Cache](./docs/cache.md) - Redis cache wrapper with TTL
 - [Errors](./docs/errors.md) - Result-based error handling
+- [Logging](./docs/logging.md) - Logging utility
+- [Prompts](./docs/prompts.md) - Interactive CLI prompts
 
 ---
 
@@ -248,6 +303,6 @@ bun check
 
 This package uses GitHub Actions for automated publishing. To release:
 
-1. Bump version: `bun version <major|minor|patch>`
+1. Bump version: `bun pm version <major|minor|patch>`
 2. Create a GitHub release with a new tag (e.g., `v0.4.0`)
 3. The GitHub Action automatically publishes to npm with provenance

package/dist/api/core/index.cjs

@@ -0,0 +1,206 @@
+const require_lib_errors_index = require("../../lib/errors/index.cjs");
+const require_index = require("../openapi/index.cjs");
+const require_index$1 = require("../validation/index.cjs");
+//#region src/lib/api/core/index.ts
+const defaultValidated = Object.freeze({
+	body: void 0,
+	query: void 0,
+	headers: void 0,
+	cookies: void 0,
+	params: void 0
+});
+const responseHelpers = {
+	json: (status, data) => Response.json(data, { status }),
+	text: (status, text) => new Response(text, { status }),
+	html: (status, html) => new Response(html, {
+		status,
+		headers: { "Content-Type": "text/html" }
+	}),
+	redirect: (status, url) => Response.redirect(url, status)
+};
+const noopGet = () => void 0;
+const stripTrailingSlash = (path) => {
+	if (path !== "/" && path.endsWith("/")) return path.slice(0, -1);
+	return path;
+};
+const hasSchemas = (schema) => schema && (schema.body || schema.query || schema.headers || schema.cookies || schema.params);
+const needsBodyCache = (schema) => schema?.body !== void 0;
+const shouldCreateBodyCache = (hasMiddlewares, allMiddlewares, request) => {
+	if (needsBodyCache(request)) return true;
+	if (!hasMiddlewares) return false;
+	return allMiddlewares.some((mw) => needsBodyCache(mw.options.request));
+};
+const resolveValidation = (v) => {
+	if (v === void 0 || v === true) return {
+		input: true,
+		output: true
+	};
+	if (v === false) return {
+		input: false,
+		output: false
+	};
+	return {
+		input: v.input !== false,
+		output: v.output !== false
+	};
+};
+var Api = class {
+	options;
+	routes = [];
+	constructor(options = {}) {
+		this.options = options;
+	}
+	getFullPath(path) {
+		const normalizedPath = stripTrailingSlash(path) || "/";
+		if (!this.options.prefix) return normalizedPath;
+		const normalizedPrefix = stripTrailingSlash(this.options.prefix);
+		if (normalizedPrefix === "/") return normalizedPath;
+		if (normalizedPath === "/") return normalizedPrefix;
+		return normalizedPrefix + normalizedPath;
+	}
+	async validateRequestSchema(req, schema, bodyCache) {
+		if (!schema) return {
+			success: true,
+			data: {}
+		};
+		const v = {};
+		if (schema.body) {
+			const [err, val] = await require_index$1.validateBody(req, schema.body, bodyCache);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.body = val;
+		}
+		if (schema.query) {
+			const [err, val] = await require_index$1.validateQuery(req, schema.query);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.query = val;
+		}
+		if (schema.headers) {
+			const [err, val] = await require_index$1.validateHeaders(req, schema.headers);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.headers = val;
+		}
+		if (schema.cookies) {
+			const [err, val] = await require_index$1.validateCookies(req, schema.cookies);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.cookies = val;
+		}
+		if (schema.params) {
+			const [err, val] = await require_index$1.validateParams(req, schema.params);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.params = val;
+		}
+		return {
+			success: true,
+			data: v
+		};
+	}
+	createContext(req, validated, extensions) {
+		return {
+			raw: req,
+			req: validated,
+			...responseHelpers,
+			get: (key) => extensions[key]
+		};
+	}
+	async validateResponseBody(response, schema) {
+		if (!schema) return response;
+		const statusSchema = schema[response.status];
+		if (!statusSchema) return response;
+		if (!(response.headers.get("content-type") ?? "").includes("application/json")) return response;
+		const [parseError, body] = await require_lib_errors_index.mightThrow(response.clone().json());
+		if (parseError) return responseHelpers.json(400, { message: "Invalid response body" });
+		const [validationError] = await require_index$1.validateSchema(statusSchema, body);
+		if (validationError) return responseHelpers.json(400, { message: validationError.message });
+		return response;
+	}
+	buildBunRoutes() {
+		const bunRoutes = {};
+		const validationConfig = resolveValidation(this.options.validation);
+		for (const route of this.routes) {
+			const { path, method, handler, request, response, middlewares } = route;
+			const fullPath = this.getFullPath(path);
+			if (!bunRoutes[fullPath]) bunRoutes[fullPath] = {};
+			const allMiddlewares = [...this.options.middlewares ?? [], ...middlewares ?? []];
+			const hasMiddlewares = allMiddlewares.length > 0;
+			const hasRouteSchemas = hasSchemas(request);
+			const effectiveOutputValidation = validationConfig.output && !!response;
+			if (!hasMiddlewares && !(validationConfig.input && hasRouteSchemas) && !effectiveOutputValidation) bunRoutes[fullPath][method] = (req) => {
+				const context = Object.create(responseHelpers);
+				context.raw = req;
+				context.req = defaultValidated;
+				context.get = noopGet;
+				return handler(context);
+			};
+			else bunRoutes[fullPath][method] = async (req) => {
+				const extensions = {};
+				const bodyCache = validationConfig.input && shouldCreateBodyCache(hasMiddlewares, allMiddlewares, request) ? {
+					parsed: false,
+					value: void 0
+				} : void 0;
+				for (const mw of allMiddlewares) {
+					const { request: reqSchema, handler: mwHandler } = mw.options;
+					let validated = defaultValidated;
+					if (validationConfig.input && hasSchemas(reqSchema)) {
+						const result = await this.validateRequestSchema(req, reqSchema, bodyCache);
+						if (!result.success) return responseHelpers.json(400, { message: result.error?.message });
+						validated = result.data;
+					}
+					const mwResult = await mwHandler(this.createContext(req, validated, extensions));
+					if (mwResult instanceof Response) return mwResult;
+					if (mwResult) Object.assign(extensions, mwResult);
+				}
+				let routeValidated = defaultValidated;
+				if (validationConfig.input && hasRouteSchemas) {
+					const result = await this.validateRequestSchema(req, request, bodyCache);
+					if (!result.success) return responseHelpers.json(400, { message: result.error?.message });
+					routeValidated = result.data;
+				}
+				const handlerResponse = await handler(this.createContext(req, routeValidated, extensions));
+				if (effectiveOutputValidation) return this.validateResponseBody(handlerResponse, response);
+				return handlerResponse;
+			};
+		}
+		return bunRoutes;
+	}
+	defineRoute(config) {
+		this.routes.push(config);
+	}
+	getOpenApiSpec() {
+		return require_index.generateOpenApiSpec({
+			title: this.options.openapi?.title ?? "API",
+			description: this.options.openapi?.description,
+			version: this.options.openapi?.version ?? "1.0.0",
+			prefix: this.options.prefix,
+			servers: this.options.openapi?.servers,
+			securitySchemes: this.options.openapi?.securitySchemes,
+			routes: this.routes,
+			globalMiddlewares: this.options.middlewares
+		});
+	}
+	serve(port, callback) {
+		const bunRoutes = this.buildBunRoutes();
+		const server = Bun.serve({
+			port,
+			routes: bunRoutes,
+			fetch: () => new Response("Not found", { status: 404 })
+		});
+		if (callback) callback(server);
+	}
+};
+//#endregion
+exports.Api = Api;

package/dist/api/core/index.d.cts

@@ -0,0 +1,21 @@
+import { OpenApiSpec } from "../openapi/types.cjs";
+import { ApiOptions, RequestSchema, ResponseSchema, RouteConfig } from "./types.cjs";
+import { Middleware } from "../middleware/index.cjs";
+
+//#region src/lib/api/core/index.d.ts
+declare class Api<TMiddlewares extends readonly Middleware[] = readonly []> {
+  private options;
+  private routes;
+  constructor(options?: ApiOptions<TMiddlewares>);
+  private getFullPath;
+  private validateRequestSchema;
+  private createContext;
+  private validateResponseBody;
+  private buildBunRoutes;
+  defineRoute<TReq extends RequestSchema = RequestSchema, TRes extends ResponseSchema = ResponseSchema, TRouteMiddlewares extends readonly Middleware[] = readonly []>(config: RouteConfig<TReq, TRes, TMiddlewares, TRouteMiddlewares>): void;
+  getOpenApiSpec(): Promise<OpenApiSpec>;
+  serve(port: number, callback?: (server: Bun.Server<unknown>) => void): void;
+}
+//#endregion
+export { Api };
+//# sourceMappingURL=index.d.cts.map

package/dist/api/core/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../../src/lib/api/core/index.ts"],"mappings":";;;;;cA4Ea,GAAA,+BAAkC,UAAA;EAAA,QACrC,OAAA;EAAA,QACA,MAAA;cAOW,OAAA,GAAS,UAAA,CAAW,YAAA;EAAA,QAI/B,WAAA;EAAA,QAaM,qBAAA;EAAA,QA+EN,aAAA;EAAA,QAaM,oBAAA;EAAA,QA6BN,cAAA;EAuHD,WAAA,cACQ,aAAA,GAAgB,aAAA,eAChB,cAAA,GAAiB,cAAA,qCACK,UAAA,iBAAA,CACnC,MAAA,EAAQ,WAAA,CAAY,IAAA,EAAM,IAAA,EAAM,YAAA,EAAc,iBAAA;EAWzC,cAAA,CAAA,GAAc,OAAA,CAXA,WAAA;EAwBd,KAAA,CAAM,IAAA,UAAc,QAAA,IAAY,MAAA,EAAQ,GAAA,CAAI,MAAA;AAAA"}

package/dist/api/core/index.d.mts

@@ -0,0 +1,21 @@
+import { OpenApiSpec } from "../openapi/types.mjs";
+import { ApiOptions, RequestSchema, ResponseSchema, RouteConfig } from "./types.mjs";
+import { Middleware } from "../middleware/index.mjs";
+
+//#region src/lib/api/core/index.d.ts
+declare class Api<TMiddlewares extends readonly Middleware[] = readonly []> {
+  private options;
+  private routes;
+  constructor(options?: ApiOptions<TMiddlewares>);
+  private getFullPath;
+  private validateRequestSchema;
+  private createContext;
+  private validateResponseBody;
+  private buildBunRoutes;
+  defineRoute<TReq extends RequestSchema = RequestSchema, TRes extends ResponseSchema = ResponseSchema, TRouteMiddlewares extends readonly Middleware[] = readonly []>(config: RouteConfig<TReq, TRes, TMiddlewares, TRouteMiddlewares>): void;
+  getOpenApiSpec(): Promise<OpenApiSpec>;
+  serve(port: number, callback?: (server: Bun.Server<unknown>) => void): void;
+}
+//#endregion
+export { Api };
+//# sourceMappingURL=index.d.mts.map

package/dist/api/core/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../src/lib/api/core/index.ts"],"mappings":";;;;;cA4Ea,GAAA,+BAAkC,UAAA;EAAA,QACrC,OAAA;EAAA,QACA,MAAA;cAOW,OAAA,GAAS,UAAA,CAAW,YAAA;EAAA,QAI/B,WAAA;EAAA,QAaM,qBAAA;EAAA,QA+EN,aAAA;EAAA,QAaM,oBAAA;EAAA,QA6BN,cAAA;EAuHD,WAAA,cACQ,aAAA,GAAgB,aAAA,eAChB,cAAA,GAAiB,cAAA,qCACK,UAAA,iBAAA,CACnC,MAAA,EAAQ,WAAA,CAAY,IAAA,EAAM,IAAA,EAAM,YAAA,EAAc,iBAAA;EAWzC,cAAA,CAAA,GAAc,OAAA,CAXA,WAAA;EAwBd,KAAA,CAAM,IAAA,UAAc,QAAA,IAAY,MAAA,EAAQ,GAAA,CAAI,MAAA;AAAA"}

package/dist/api/core/index.mjs

@@ -0,0 +1,208 @@
+import { mightThrow } from "../../lib/errors/index.mjs";
+import { generateOpenApiSpec } from "../openapi/index.mjs";
+import { validateBody, validateCookies, validateHeaders, validateParams, validateQuery, validateSchema } from "../validation/index.mjs";
+//#region src/lib/api/core/index.ts
+const defaultValidated = Object.freeze({
+	body: void 0,
+	query: void 0,
+	headers: void 0,
+	cookies: void 0,
+	params: void 0
+});
+const responseHelpers = {
+	json: (status, data) => Response.json(data, { status }),
+	text: (status, text) => new Response(text, { status }),
+	html: (status, html) => new Response(html, {
+		status,
+		headers: { "Content-Type": "text/html" }
+	}),
+	redirect: (status, url) => Response.redirect(url, status)
+};
+const noopGet = () => void 0;
+const stripTrailingSlash = (path) => {
+	if (path !== "/" && path.endsWith("/")) return path.slice(0, -1);
+	return path;
+};
+const hasSchemas = (schema) => schema && (schema.body || schema.query || schema.headers || schema.cookies || schema.params);
+const needsBodyCache = (schema) => schema?.body !== void 0;
+const shouldCreateBodyCache = (hasMiddlewares, allMiddlewares, request) => {
+	if (needsBodyCache(request)) return true;
+	if (!hasMiddlewares) return false;
+	return allMiddlewares.some((mw) => needsBodyCache(mw.options.request));
+};
+const resolveValidation = (v) => {
+	if (v === void 0 || v === true) return {
+		input: true,
+		output: true
+	};
+	if (v === false) return {
+		input: false,
+		output: false
+	};
+	return {
+		input: v.input !== false,
+		output: v.output !== false
+	};
+};
+var Api = class {
+	options;
+	routes = [];
+	constructor(options = {}) {
+		this.options = options;
+	}
+	getFullPath(path) {
+		const normalizedPath = stripTrailingSlash(path) || "/";
+		if (!this.options.prefix) return normalizedPath;
+		const normalizedPrefix = stripTrailingSlash(this.options.prefix);
+		if (normalizedPrefix === "/") return normalizedPath;
+		if (normalizedPath === "/") return normalizedPrefix;
+		return normalizedPrefix + normalizedPath;
+	}
+	async validateRequestSchema(req, schema, bodyCache) {
+		if (!schema) return {
+			success: true,
+			data: {}
+		};
+		const v = {};
+		if (schema.body) {
+			const [err, val] = await validateBody(req, schema.body, bodyCache);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.body = val;
+		}
+		if (schema.query) {
+			const [err, val] = await validateQuery(req, schema.query);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.query = val;
+		}
+		if (schema.headers) {
+			const [err, val] = await validateHeaders(req, schema.headers);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.headers = val;
+		}
+		if (schema.cookies) {
+			const [err, val] = await validateCookies(req, schema.cookies);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.cookies = val;
+		}
+		if (schema.params) {
+			const [err, val] = await validateParams(req, schema.params);
+			if (err) return {
+				success: false,
+				error: err
+			};
+			v.params = val;
+		}
+		return {
+			success: true,
+			data: v
+		};
+	}
+	createContext(req, validated, extensions) {
+		return {
+			raw: req,
+			req: validated,
+			...responseHelpers,
+			get: (key) => extensions[key]
+		};
+	}
+	async validateResponseBody(response, schema) {
+		if (!schema) return response;
+		const statusSchema = schema[response.status];
+		if (!statusSchema) return response;
+		if (!(response.headers.get("content-type") ?? "").includes("application/json")) return response;
+		const [parseError, body] = await mightThrow(response.clone().json());
+		if (parseError) return responseHelpers.json(400, { message: "Invalid response body" });
+		const [validationError] = await validateSchema(statusSchema, body);
+		if (validationError) return responseHelpers.json(400, { message: validationError.message });
+		return response;
+	}
+	buildBunRoutes() {
+		const bunRoutes = {};
+		const validationConfig = resolveValidation(this.options.validation);
+		for (const route of this.routes) {
+			const { path, method, handler, request, response, middlewares } = route;
+			const fullPath = this.getFullPath(path);
+			if (!bunRoutes[fullPath]) bunRoutes[fullPath] = {};
+			const allMiddlewares = [...this.options.middlewares ?? [], ...middlewares ?? []];
+			const hasMiddlewares = allMiddlewares.length > 0;
+			const hasRouteSchemas = hasSchemas(request);
+			const effectiveOutputValidation = validationConfig.output && !!response;
+			if (!hasMiddlewares && !(validationConfig.input && hasRouteSchemas) && !effectiveOutputValidation) bunRoutes[fullPath][method] = (req) => {
+				const context = Object.create(responseHelpers);
+				context.raw = req;
+				context.req = defaultValidated;
+				context.get = noopGet;
+				return handler(context);
+			};
+			else bunRoutes[fullPath][method] = async (req) => {
+				const extensions = {};
+				const bodyCache = validationConfig.input && shouldCreateBodyCache(hasMiddlewares, allMiddlewares, request) ? {
+					parsed: false,
+					value: void 0
+				} : void 0;
+				for (const mw of allMiddlewares) {
+					const { request: reqSchema, handler: mwHandler } = mw.options;
+					let validated = defaultValidated;
+					if (validationConfig.input && hasSchemas(reqSchema)) {
+						const result = await this.validateRequestSchema(req, reqSchema, bodyCache);
+						if (!result.success) return responseHelpers.json(400, { message: result.error?.message });
+						validated = result.data;
+					}
+					const mwResult = await mwHandler(this.createContext(req, validated, extensions));
+					if (mwResult instanceof Response) return mwResult;
+					if (mwResult) Object.assign(extensions, mwResult);
+				}
+				let routeValidated = defaultValidated;
+				if (validationConfig.input && hasRouteSchemas) {
+					const result = await this.validateRequestSchema(req, request, bodyCache);
+					if (!result.success) return responseHelpers.json(400, { message: result.error?.message });
+					routeValidated = result.data;
+				}
+				const handlerResponse = await handler(this.createContext(req, routeValidated, extensions));
+				if (effectiveOutputValidation) return this.validateResponseBody(handlerResponse, response);
+				return handlerResponse;
+			};
+		}
+		return bunRoutes;
+	}
+	defineRoute(config) {
+		this.routes.push(config);
+	}
+	getOpenApiSpec() {
+		return generateOpenApiSpec({
+			title: this.options.openapi?.title ?? "API",
+			description: this.options.openapi?.description,
+			version: this.options.openapi?.version ?? "1.0.0",
+			prefix: this.options.prefix,
+			servers: this.options.openapi?.servers,
+			securitySchemes: this.options.openapi?.securitySchemes,
+			routes: this.routes,
+			globalMiddlewares: this.options.middlewares
+		});
+	}
+	serve(port, callback) {
+		const bunRoutes = this.buildBunRoutes();
+		const server = Bun.serve({
+			port,
+			routes: bunRoutes,
+			fetch: () => new Response("Not found", { status: 404 })
+		});
+		if (callback) callback(server);
+	}
+};
+//#endregion
+export { Api };
+
+//# sourceMappingURL=index.mjs.map

package/dist/api/core/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/lib/api/core/index.ts"],"sourcesContent":["import { mightThrow } from \"../../errors/index.js\";\nimport type { Middleware } from \"../middleware/index.js\";\nimport { generateOpenApiSpec } from \"../openapi/index.js\";\nimport {\n  type BodyCache,\n  validateBody,\n  validateCookies,\n  validateHeaders,\n  validateParams,\n  validateQuery,\n  validateSchema,\n} from \"../validation/index.js\";\nimport type {\n  ApiOptions,\n  MethodRoutes,\n  RequestSchema,\n  ResponseSchema,\n  RouteConfig,\n  ValidatedRequest,\n  ValidationOptions,\n} from \"./types.js\";\n\n// Shared defaults reused across requests to avoid per-request allocations\nconst defaultValidated: ValidatedRequest = Object.freeze({\n  body: undefined,\n  query: undefined,\n  headers: undefined,\n  cookies: undefined,\n  params: undefined,\n});\n\nconst responseHelpers = {\n  json: (status: number, data: unknown) => Response.json(data, { status }),\n  text: (status: number, text: string) => new Response(text, { status }),\n  html: (status: number, html: string) =>\n    new Response(html, { status, headers: { \"Content-Type\": \"text/html\" } }),\n  redirect: (status: number, url: string) => Response.redirect(url, status),\n} as const;\n\nconst noopGet = () => undefined;\n\nconst stripTrailingSlash = (path: string) => {\n  if (path !== \"/\" && path.endsWith(\"/\")) {\n    return path.slice(0, -1);\n  }\n\n  return path;\n};\n\nconst hasSchemas = (schema?: RequestSchema) =>\n  schema &&\n  (schema.body ||\n    schema.query ||\n    schema.headers ||\n    schema.cookies ||\n    schema.params);\n\nconst needsBodyCache = (schema?: RequestSchema) => schema?.body !== undefined;\n\nconst shouldCreateBodyCache = (\n  hasMiddlewares: boolean,\n  allMiddlewares: Middleware[],\n  request?: RequestSchema,\n) => {\n  if (needsBodyCache(request)) return true;\n  if (!hasMiddlewares) return false;\n\n  return allMiddlewares.some((mw) => needsBodyCache(mw.options.request));\n};\n\nconst resolveValidation = (v?: ValidationOptions) => {\n  if (v === undefined || v === true) return { input: true, output: true };\n  if (v === false) return { input: false, output: false };\n  return { input: v.input !== false, output: v.output !== false };\n};\n\nexport class Api<TMiddlewares extends readonly Middleware[] = readonly []> {\n  private options: ApiOptions<TMiddlewares>;\n  private routes: RouteConfig<\n    RequestSchema,\n    ResponseSchema,\n    TMiddlewares,\n    readonly Middleware[]\n  >[] = [];\n\n  public constructor(options: ApiOptions<TMiddlewares> = {}) {\n    this.options = options;\n  }\n\n  private getFullPath(path: string) {\n    const normalizedPath = stripTrailingSlash(path) || \"/\";\n\n    if (!this.options.prefix) return normalizedPath;\n\n    const normalizedPrefix = stripTrailingSlash(this.options.prefix);\n\n    if (normalizedPrefix === \"/\") return normalizedPath;\n    if (normalizedPath === \"/\") return normalizedPrefix;\n\n    return normalizedPrefix + normalizedPath;\n  }\n\n  private async validateRequestSchema(\n    req: Bun.BunRequest,\n    schema: RequestSchema | undefined,\n    bodyCache?: BodyCache,\n  ) {\n    if (!schema) {\n      return { success: true, data: {} };\n    }\n\n    const v: Record<string, unknown> = {};\n\n    if (schema.body) {\n      const [err, val] = await validateBody(req, schema.body, bodyCache);\n\n      if (err) {\n        return {\n          success: false,\n          error: err,\n        };\n      }\n\n      v.body = val;\n    }\n\n    if (schema.query) {\n      const [err, val] = await validateQuery(req, schema.query);\n\n      if (err) {\n        return {\n          success: false,\n          error: err,\n        };\n      }\n\n      v.query = val;\n    }\n\n    if (schema.headers) {\n      const [err, val] = await validateHeaders(req, schema.headers);\n\n      if (err) {\n        return {\n          success: false,\n          error: err,\n        };\n      }\n\n      v.headers = val;\n    }\n\n    if (schema.cookies) {\n      const [err, val] = await validateCookies(req, schema.cookies);\n\n      if (err) {\n        return {\n          success: false,\n          error: err,\n        };\n      }\n\n      v.cookies = val;\n    }\n\n    if (schema.params) {\n      const [err, val] = await validateParams(req, schema.params);\n\n      if (err) {\n        return {\n          success: false,\n          error: err,\n        };\n      }\n\n      v.params = val;\n    }\n\n    return { success: true, data: v };\n  }\n\n  private createContext(\n    req: Bun.BunRequest,\n    validated: ValidatedRequest,\n    extensions: Record<string, unknown>,\n  ) {\n    return {\n      raw: req,\n      req: validated,\n      ...responseHelpers,\n      get: (key: string) => extensions[key],\n    };\n  }\n\n  private async validateResponseBody(\n    response: Response,\n    schema: ResponseSchema | undefined,\n  ) {\n    if (!schema) return response;\n\n    const statusSchema = schema[response.status];\n\n    if (!statusSchema) return response;\n\n    const contentType = response.headers.get(\"content-type\") ?? \"\";\n\n    if (!contentType.includes(\"application/json\")) return response;\n\n    const [parseError, body] = await mightThrow(response.clone().json());\n\n    if (parseError) {\n      return responseHelpers.json(400, { message: \"Invalid response body\" });\n    }\n\n    const [validationError] = await validateSchema(statusSchema, body);\n\n    if (validationError) {\n      return responseHelpers.json(400, { message: validationError.message });\n    }\n\n    return response;\n  }\n\n  private buildBunRoutes() {\n    const bunRoutes: MethodRoutes = {};\n    const validationConfig = resolveValidation(this.options.validation);\n\n    for (const route of this.routes) {\n      const { path, method, handler, request, response, middlewares } = route;\n\n      const fullPath = this.getFullPath(path);\n\n      if (!bunRoutes[fullPath]) {\n        bunRoutes[fullPath] = {};\n      }\n\n      const allMiddlewares = [\n        ...(this.options.middlewares ?? []),\n        ...(middlewares ?? []),\n      ];\n\n      const hasMiddlewares = allMiddlewares.length > 0;\n      const hasRouteSchemas = hasSchemas(request);\n      const effectiveOutputValidation = validationConfig.output && !!response;\n\n      if (\n        !hasMiddlewares &&\n        !(validationConfig.input && hasRouteSchemas) &&\n        !effectiveOutputValidation\n      ) {\n        // Zero-allocation path for simple routes using prototype chain\n        // Avoids object spread overhead by inheriting response helpers via prototype\n        bunRoutes[fullPath][method] = (req: Bun.BunRequest) => {\n          // Create fresh per-request context to avoid cross-request contamination\n          const context = Object.create(responseHelpers);\n          context.raw = req;\n          context.req = defaultValidated;\n          context.get = noopGet;\n\n          return handler(context as unknown as Parameters<typeof handler>[0]);\n        };\n      } else {\n        bunRoutes[fullPath][method] = async (req: Bun.BunRequest) => {\n          const extensions: Record<string, unknown> = {};\n\n          // Only create bodyCache if input validation is enabled and any schema has body validation\n          const bodyCache: BodyCache | undefined =\n            validationConfig.input &&\n            shouldCreateBodyCache(hasMiddlewares, allMiddlewares, request)\n              ? { parsed: false, value: undefined }\n              : undefined;\n\n          for (const mw of allMiddlewares) {\n            const { request: reqSchema, handler: mwHandler } = mw.options;\n\n            let validated = defaultValidated;\n\n            if (validationConfig.input && hasSchemas(reqSchema)) {\n              const result = await this.validateRequestSchema(\n                req,\n                reqSchema,\n                bodyCache,\n              );\n\n              if (!result.success) {\n                return responseHelpers.json(400, {\n                  message: result.error?.message,\n                });\n              }\n\n              validated = result.data as ValidatedRequest;\n            }\n\n            const context = this.createContext(req, validated, extensions);\n            const mwResult = await mwHandler(\n              context as Parameters<typeof mwHandler>[0],\n            );\n\n            if (mwResult instanceof Response) {\n              return mwResult;\n            }\n\n            if (mwResult) {\n              Object.assign(extensions, mwResult);\n            }\n          }\n\n          let routeValidated = defaultValidated;\n\n          if (validationConfig.input && hasRouteSchemas) {\n            const result = await this.validateRequestSchema(\n              req,\n              request,\n              bodyCache,\n            );\n\n            if (!result.success) {\n              return responseHelpers.json(400, {\n                message: result.error?.message,\n              });\n            }\n\n            routeValidated = result.data as ValidatedRequest;\n          }\n\n          const context = this.createContext(req, routeValidated, extensions);\n          const handlerResponse = await handler(\n            context as Parameters<typeof handler>[0],\n          );\n\n          if (effectiveOutputValidation) {\n            return this.validateResponseBody(handlerResponse, response);\n          }\n\n          return handlerResponse;\n        };\n      }\n    }\n\n    return bunRoutes;\n  }\n\n  public defineRoute<\n    TReq extends RequestSchema = RequestSchema,\n    TRes extends ResponseSchema = ResponseSchema,\n    TRouteMiddlewares extends readonly Middleware[] = readonly [],\n  >(config: RouteConfig<TReq, TRes, TMiddlewares, TRouteMiddlewares>) {\n    this.routes.push(\n      config as RouteConfig<\n        RequestSchema,\n        ResponseSchema,\n        TMiddlewares,\n        readonly Middleware[]\n      >,\n    );\n  }\n\n  public getOpenApiSpec() {\n    return generateOpenApiSpec({\n      title: this.options.openapi?.title ?? \"API\",\n      description: this.options.openapi?.description,\n      version: this.options.openapi?.version ?? \"1.0.0\",\n      prefix: this.options.prefix,\n      servers: this.options.openapi?.servers,\n      securitySchemes: this.options.openapi?.securitySchemes,\n      routes: this.routes,\n      globalMiddlewares: this.options.middlewares,\n    });\n  }\n\n  public serve(port: number, callback?: (server: Bun.Server<unknown>) => void) {\n    const bunRoutes = this.buildBunRoutes();\n\n    const server = Bun.serve({\n      port,\n      routes: bunRoutes,\n      fetch: () => new Response(\"Not found\", { status: 404 }),\n    });\n\n    if (callback) {\n      callback(server);\n    }\n  }\n}\n"],"mappings":"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"}