@kichu12348/bunify 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# Bunify
+
+A fast, lightweight, and strictly-typed web framework built specifically for [Bun](https://bun.sh/). 
+
+**Bunify** offers a developer-friendly API heavily inspired by proven web frameworks like Fastify, but optimized for the modern Bun ecosystem. It features robust typing, lifecycle hooks, powerful routing, and middleware support right out of the box.
+
+## Installation
+
+Since Bunify relies on native Bun features, ensure you have [Bun installed](https://bun.sh/).
+
+```bash
+bun add bunify
+```
+
+## Quick Start
+
+```typescript
+import { Bunify } from "bunify";
+
+const app = new Bunify({ logger: true });
+
+app.get("/hello", (request, reply) => {
+  return { message: "Hello, World!" };
+});
+
+app.listen(3000, (address) => {
+  console.log(`Server is running at http://${address}`);
+});
+```
+
+## Features
+
+### Type-Safe Routing
+Bunify enforces strict typing on your `return` statements and incoming requests using `RouteSchema` definition.
+
+```typescript
+type GreetRoute = {
+  Body: { name: string };
+  Query: { formal?: string };
+  Params: { id: string };
+  Reply: { greeting: string };
+};
+
+app.post<GreetRoute>("/greet/:id", async (request, reply) => {
+  const body = await request.json(); // Strongly typed to { name: string }
+  const formal = request.query.formal;
+  const id = request.params.id; // Strongly typed to string
+
+  return { greeting: `Hello ${body.name}, your id is ${id}` };
+});
+```
+
+### Middleware (`use`)
+You can use middleware to intercept incoming requests and process them before they hit your routes. Note that you MUST call `next()` to proceed.
+
+```typescript
+app.use(async (request, reply, next) => {
+  console.log(`Incoming request: ${request.method} ${request.url}`);
+  await next();
+});
+```
+
+### Lifecycle Hooks
+Tap into requests at specific lifecycles. Available hooks are `onRequest`, `preHandler`, and `onResponse`.
+
+```typescript
+app.addHook("onRequest", async (request, reply, next) => {
+  // Logic here
+  await next();
+});
+```
+
+### Routing & Chaining Middlewares
+You can apply middleware locally per-route by chaining them before the final handler.
+
+```typescript
+app.get(
+  "/protected",
+  async (request, reply, next) => {
+    if (!request.headers.get("Authorization")) {
+      return reply.status(401).json({ error: "Unauthorized" });
+    }
+    await next();
+  },
+  (request, reply) => {
+    return { data: "Top Secret" };
+  }
+);
+```
+
+### Decorators
+Easily attach custom utilities, instances, or metadata to your `Bunify` application context and requests.
+
+```typescript
+// Define expected decorators
+type AppDecorators = { db: any };
+
+const app = new Bunify<AppDecorators>();
+
+app.decorate("db", { getDocs: () => [{ id: 1 }] });
+
+app.get("/docs", (request, reply) => {
+  // request.db is available and correctly typed
+  return request.db.getDocs();
+});
+```
+
+### Plugins / Sub-Routers
+Divide your application into logical modules combining prefixes, scoped dependencies, and decorators securely using `.register()`.
+
+```typescript
+app.register(
+  (adminApp) => {
+    adminApp.get("/dashboard", (request, reply) => {
+      reply.html("<h1>Admin Dashboard</h1>");
+    });
+  },
+  { prefix: "/admin" } // accessible at /admin/dashboard
+);
+```
+
+## Reply Methods
+
+The `reply` object gives you fine-grained control to shape responses gracefully.
+
+- `reply.status(code)` / `reply.code(code)`: Set the HTTP status code
+- `reply.headers(key, value)`: Insert a new Header
+- `reply.json(data)`: Automatically sends a JSON response
+- `reply.html(content)`: Easily serve HTML tags
+- `reply.redirect(url)`: Responds with a 302 redirect
+- `reply.send(content)`: Generic send handler
+- Return directly from `handler` instead of returning `reply.send()` (See Quick Start).
+
+## License
+
+[MIT](./LICENSE)

package/benchmarks/bun-raw.ts

@@ -0,0 +1,54 @@
+const server = Bun.serve({
+  port: 3001,
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    // 1. Simulate Middleware (headers added to all routes)
+    const headers = new Headers();
+    headers.set("X-Benchmark-Time", Date.now().toString());
+
+    if (req.method === "GET") {
+      // 2. Simple GET
+      if (url.pathname === "/") {
+        headers.set("Content-Type", "application/json");
+        return new Response(JSON.stringify({ message: "Hello, World!" }), {
+          headers,
+        });
+      }
+
+      // 3. Query params map handler
+      if (url.pathname === "/search") {
+        headers.set("Content-Type", "application/json");
+        const q = url.searchParams.get("q") || "none";
+        return new Response(JSON.stringify({ results: q }), { headers });
+      }
+
+      // 4. Larger JSON Payload
+      if (url.pathname === "/data") {
+        headers.set("Content-Type", "application/json");
+        return new Response(
+          JSON.stringify({
+            items: [
+              { id: 1, name: "Item A" },
+              { id: 2, name: "Item B" },
+              { id: 3, name: "Item C" },
+            ],
+            status: "ok",
+          }),
+          { headers },
+        );
+      }
+    }
+
+    // 5. POST body JSON
+    if (req.method === "POST" && url.pathname === "/echo") {
+      const body = await req.json();
+      headers.set("Content-Type", "application/json");
+      return new Response(JSON.stringify(body), { status: 201, headers });
+    }
+
+    return new Response("Not Found", { status: 404 });
+  },
+});
+
+console.log(`Raw Bun server listening on ${server.hostname}:${server.port}`);

package/benchmarks/bunify.ts

@@ -0,0 +1,43 @@
+import { Bunify } from "../src/core";
+
+const app = new Bunify();
+
+// 1. App-level Middleware
+app.use(async (req, reply, next) => {
+  reply.headers("X-Benchmark-Time", Date.now().toString());
+  return next();
+});
+
+// 2. Simple GET
+app.get("/", () => {
+  return { message: "Hello, World!" };
+});
+
+// 3. Query params map handler
+app.get("/search", (req) => {
+  return {
+    results: req.query.q || "none",
+  };
+});
+
+// 4. Larger JSON Payload
+app.get("/data", () => {
+  return {
+    items: [
+      { id: 1, name: "Item A" },
+      { id: 2, name: "Item B" },
+      { id: 3, name: "Item C" },
+    ],
+    status: "ok",
+  };
+});
+
+// 5. POST body JSON
+app.post("/echo", async (req, reply) => {
+  const body = await req.json();
+  return reply.status(201).json(body);
+});
+
+app.listen(3000, (url) => {
+  console.log(`Bunify listening on ${url}`);
+});

package/bun.lock

@@ -0,0 +1,26 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "bunify",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/node": ["@types/node@25.5.2", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg=="],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+  }
+}

package/example.ts

@@ -0,0 +1,11 @@
+import { Bunify } from "./src/core";
+
+const app = new Bunify();
+
+app.get("/hello", (req, res) => {
+  return { message: "Hello, World!" };
+});
+
+app.listen(3000, (address) => {
+  console.log(`Server is running at http://${address}`);
+});

package/index.ts

@@ -0,0 +1,4 @@
+export { Bunify } from "./src/core";
+
+// Re-export any interfaces or types that users might need
+export type { BunifyInstance, BunifyRequest, BunifyReply } from "./src/core";

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@kichu12348/bunify",
+  "version": "1.0.0",
+  "author": "Kichu",
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./index.ts",
+      "types": "./index.ts"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/core.ts

@@ -0,0 +1,377 @@
+type Method = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+
+type RouteSchema = {
+  Query?: Record<string, any>;
+  Params?: Record<string, any>;
+  Body?: any;
+  Reply?: any;
+};
+
+export type BunifyRequest<T extends RouteSchema = RouteSchema, D = {}> = {
+  raw: Bun.BunRequest;
+  query: Record<string, string> & (T["Query"] extends object ? T["Query"] : {});
+  params: T["Params"] extends infer U
+    ? Record<string, string> & U
+    : Record<string, string>;
+  json: () => Promise<T["Body"]>;
+  text: () => Promise<string>;
+  headers: Headers;
+  method: string;
+  url: string;
+} & D;
+
+type Reply = ReturnType<typeof createReply>;
+
+export type BunifyReply<T extends RouteSchema = RouteSchema> = Reply & {
+  send: (content: T["Reply"] | Response) => Response;
+  json: (data: T["Reply"]) => Response;
+};
+
+export type Handler<T extends RouteSchema = RouteSchema, D = {}> = (
+  request: BunifyRequest<T, D>,
+  reply: BunifyReply<T>,
+) => T["Reply"] | Response | Promise<T["Reply"] | Response>;
+
+export type Middleware<T extends RouteSchema = RouteSchema, D = {}> = (
+  request: BunifyRequest<T, D>,
+  reply: BunifyReply<T>,
+  next: () => Promise<any>,
+) => any;
+
+type HookType = "onRequest" | "preHandler" | "onResponse";
+
+export interface BunifyInstance {
+  get<T extends RouteSchema = RouteSchema>(
+    path: string,
+    handler: Handler<T>,
+  ): void;
+  post<T extends RouteSchema = RouteSchema>(
+    path: string,
+    handler: Handler<T>,
+  ): void;
+  put<T extends RouteSchema = RouteSchema>(
+    path: string,
+    handler: Handler<T>,
+  ): void;
+  delete<T extends RouteSchema = RouteSchema>(
+    path: string,
+    handler: Handler<T>,
+  ): void;
+  patch<T extends RouteSchema = RouteSchema>(
+    path: string,
+    handler: Handler<T>,
+  ): void;
+  listen(port: number, callback?: (address: string) => void): void;
+}
+
+interface RegisterOptions {
+  prefix?: string;
+}
+
+function createReply() {
+  let status = 200;
+  const headers = new Headers();
+  let body: any = null;
+  let sent = false;
+
+  return {
+    get sent() {
+      return sent;
+    },
+
+    status(code: number) {
+      status = code;
+      return this;
+    },
+    code(code: number) {
+      return this.status(code);
+    },
+    headers(key: string, value: string) {
+      headers.set(key, value);
+      return this;
+    },
+    json(data: any) {
+      return this.headers("Content-Type", "application/json").send(data);
+    },
+    redirect(url: string) {
+      return this.status(302).headers("Location", url).send(null);
+    },
+    html(content: string) {
+      return this.headers("Content-Type", "text/html").send(content);
+    },
+    send(content: any) {
+      if (sent) {
+        throw new Error("Reply has already been sent.");
+      }
+      sent = true;
+      if (content instanceof Response) return content;
+
+      if (typeof content === "object") {
+        headers.set("Content-Type", "application/json");
+        content = JSON.stringify(content);
+      }
+
+      body = content;
+      return this.build();
+    },
+
+    build() {
+      if (body instanceof Response) return body;
+
+      return new Response(body, { status, headers });
+    },
+  };
+}
+
+export class Bunify<Decorators extends Record<string, any> = {}> {
+  private logger: boolean;
+  private prefix: string = "";
+  private routes: { [key: string]: any };
+  private middlewares: Middleware<any, Decorators>[] = [];
+  private hooks: Record<HookType, Middleware<any, Decorators>[]> = {
+    onRequest: [],
+    preHandler: [],
+    onResponse: [],
+  };
+
+  private decorators: Decorators = {} as Decorators;
+
+  constructor(options?: { logger?: boolean }) {
+    this.logger = options?.logger ?? false;
+    this.routes = {};
+  }
+
+  private joinPaths(base: string, path: string) {
+    return (base + path).replace(/\/+/g, "/");
+  }
+
+  private addRoute<T extends RouteSchema = RouteSchema>(
+    method: Method,
+    path: string,
+    handlers: (Handler<T, Decorators> | Middleware<T, Decorators>)[],
+  ) {
+    const { handler, middlewares } = this.parseHandlers<T>(handlers);
+    const composedHandler = this.compose<T>(
+      [...this.middlewares, ...middlewares] as Middleware<T, Decorators>[],
+      handler,
+    );
+    const wrappedHandler = async (req: Bun.BunRequest) => {
+      const url = new URL(req.url);
+
+      const request: BunifyRequest<T, Decorators> = {
+        raw: req,
+        query: Object.fromEntries(url.searchParams.entries()) as BunifyRequest<
+          T,
+          Decorators
+        >["query"],
+        params: (req.params || {}) as BunifyRequest<T, Decorators>["params"],
+        json: () => req.json(),
+        text: () => req.text(),
+        headers: req.headers,
+        method: req.method,
+        url: req.url,
+        ...(this.decorators as Decorators),
+      };
+
+      const reply = createReply() as BunifyReply<T>;
+
+      try {
+        const res = await this.runPipeline(request, reply, composedHandler);
+        if (!reply.sent && res !== undefined) {
+          return reply.send(res);
+        }
+        return reply.build();
+      } catch (err) {
+        if (this.logger) {
+          console.error(`Error in [${method} ${path}]:`, err);
+        }
+        return new Response("Internal Server Error", { status: 500 });
+      }
+    };
+
+    const fullPath = this.joinPaths(this.prefix, path);
+
+    const route = this.routes[fullPath];
+    if (!route) {
+      this.routes[fullPath] = { [method]: wrappedHandler };
+    } else {
+      this.routes[fullPath][method] = wrappedHandler;
+    }
+  }
+
+  private compose<T extends RouteSchema>(
+    middlewares: Middleware<T, Decorators>[],
+    handler: Handler<T, Decorators>,
+  ) {
+    return async (
+      request: BunifyRequest<T, Decorators>,
+      reply: BunifyReply<T>,
+    ) => {
+      let index = -1;
+      const next = async (i: number): Promise<any> => {
+        if (i <= index) {
+          throw new Error("next() called multiple times");
+        }
+        index = i;
+
+        if (i === middlewares.length) {
+          return handler(request, reply);
+        }
+
+        const mw = middlewares[i];
+        if (mw) {
+          return mw(request, reply, () => next(i + 1));
+        }
+      };
+      return next(0);
+    };
+  }
+
+  private parseHandlers<T extends RouteSchema = RouteSchema>(
+    handlers: (Handler<T, Decorators> | Middleware<T, Decorators>)[],
+  ) {
+    const flat = handlers.flat();
+    const handler = flat[flat.length - 1] as Handler<T, Decorators>;
+    const middlewares = flat.slice(0, -1) as Middleware<T, Decorators>[];
+    return { handler, middlewares };
+  }
+
+  private runHooks<T extends RouteSchema>(
+    hooks: Middleware<T, Decorators>[],
+    request: BunifyRequest<T, Decorators>,
+    reply: BunifyReply<T>,
+  ) {
+    let index = -1;
+
+    const next = async (i: number): Promise<any> => {
+      if (i <= index) {
+        throw new Error("next() called multiple times in hooks");
+      }
+      index = i;
+
+      const fn = hooks[i];
+      if (!fn) return;
+
+      return fn(request, reply, () => next(i + 1));
+    };
+    return next(0);
+  }
+
+  private async runPipeline<T extends RouteSchema>(
+    request: BunifyRequest<T, Decorators>,
+    reply: BunifyReply<T>,
+    handler: Handler<T, Decorators>,
+  ) {
+    let res = await this.runHooks(
+      this.hooks.onRequest as Middleware<T, Decorators>[],
+      request,
+      reply,
+    );
+    if (reply.sent) return;
+
+    res = await this.runHooks(
+      this.hooks.preHandler as Middleware<T, Decorators>[],
+      request,
+      reply,
+    );
+    if (reply.sent) return;
+
+    res = await handler(request, reply);
+    if (reply.sent) return res;
+
+    await this.runHooks(
+      this.hooks.onResponse as Middleware<T, Decorators>[],
+      request,
+      reply,
+    );
+
+    return res;
+  }
+
+  decorate<K extends string, V>(name: K, value: V) {
+    if ((this.decorators as any)[name]) {
+      throw new Error(`Decorator '${name}' already exists.`);
+    }
+    (this.decorators as any)[name] = value;
+
+    return this as any;
+  }
+
+  register(
+    fn: (app: Bunify<Decorators>) => void,
+    { prefix = "" }: RegisterOptions,
+  ) {
+    const child = new Bunify<Decorators>({ logger: this.logger });
+    child.routes = this.routes; // Share routes
+    child.prefix = this.joinPaths(this.prefix, prefix);
+
+    child.hooks = {
+      onRequest: [...this.hooks.onRequest],
+      preHandler: [...this.hooks.preHandler],
+      onResponse: [...this.hooks.onResponse],
+    };
+
+    child.decorators = { ...this.decorators };
+
+    child.middlewares = [...(this.middlewares || [])];
+    fn(child);
+  }
+
+  use(fn: Middleware<any, Decorators>) {
+    this.middlewares.push(fn);
+  }
+
+  addHook(type: HookType, fn: Middleware<any, Decorators>) {
+    this.hooks[type].push(fn);
+  }
+
+  get<T extends RouteSchema = RouteSchema>(
+    path: string,
+    ...handlers: [...Middleware<T, Decorators>[], Handler<T, Decorators>]
+  ) {
+    this.addRoute("GET", path, handlers);
+  }
+
+  post<T extends RouteSchema = RouteSchema>(
+    path: string,
+    ...handlers: [...Middleware<T, Decorators>[], Handler<T, Decorators>]
+  ) {
+    this.addRoute("POST", path, handlers);
+  }
+
+  put<T extends RouteSchema = RouteSchema>(
+    path: string,
+    ...handlers: [...Middleware<T, Decorators>[], Handler<T, Decorators>]
+  ) {
+    this.addRoute("PUT", path, handlers);
+  }
+
+  delete<T extends RouteSchema = RouteSchema>(
+    path: string,
+    ...handlers: [...Middleware<T, Decorators>[], Handler<T, Decorators>]
+  ) {
+    this.addRoute("DELETE", path, handlers);
+  }
+
+  patch<T extends RouteSchema = RouteSchema>(
+    path: string,
+    ...handlers: [...Middleware<T, Decorators>[], Handler<T, Decorators>]
+  ) {
+    this.addRoute("PATCH", path, handlers);
+  }
+
+  listen(port: number, callback?: (address: string) => void) {
+    const server = Bun.serve({
+      port: port,
+      routes: this.routes,
+      fetch: async () => {
+        return new Response("Not Found", { status: 404 });
+      },
+    });
+    if (callback) {
+      callback(server.hostname + ":" + server.port);
+    }
+
+    return server;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "types": ["bun"],
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}