@bunary/http 0.0.2 → 0.0.4

package/README.md

@@ -11,6 +11,10 @@ Part of the [Bunary](https://github.com/bunary-dev) ecosystem - a Bun-first back
 - 🔒 **Type-safe** - Full TypeScript support with strict types
 - ⚡ **Fast** - Minimal overhead, direct routing
 - 🧩 **Simple API** - Chainable route registration with automatic JSON serialization
+- 📂 **Route Groups** - Organize routes with shared prefixes, middleware, and name prefixes
+- 🏷️ **Named Routes** - URL generation with route names
+- ✅ **Route Constraints** - Validate parameters with regex patterns
+- ❓ **Optional Parameters** - Flexible routes with optional path segments
 
 ## Installation
 
@@ -215,9 +219,163 @@ app.use(async (ctx, next) => {
 });
 ```
 
+## Route Groups
+
+Group routes together with shared prefixes, middleware, and name prefixes.
+
+### Basic Groups
+
+```typescript
+// Simple prefix
+app.group('/api', (router) => {
+  router.get('/users', () => ({ users: [] }));     // /api/users
+  router.get('/posts', () => ({ posts: [] }));     // /api/posts
+});
+```
+
+### Groups with Options
+
+```typescript
+// Auth middleware for protected routes
+const authMiddleware = async (ctx, next) => {
+  const token = ctx.request.headers.get('Authorization');
+  if (!token) return new Response('Unauthorized', { status: 401 });
+  return await next();
+};
+
+app.group({
+  prefix: '/admin',
+  middleware: [authMiddleware],
+  name: 'admin.'
+}, (router) => {
+  router.get('/dashboard', () => ({})).name('dashboard');  // name: admin.dashboard
+  router.get('/users', () => ({})).name('users');          // name: admin.users
+});
+```
+
+### Nested Groups
+
+```typescript
+app.group('/api', (api) => {
+  api.group('/v1', (v1) => {
+    v1.get('/users', () => ({}));  // /api/v1/users
+  });
+  api.group('/v2', (v2) => {
+    v2.get('/users', () => ({}));  // /api/v2/users
+  });
+});
+```
+
+## Named Routes
+
+Assign names to routes for URL generation.
+
+### Naming Routes
+
+```typescript
+app.get('/users/:id', (ctx) => ({})).name('users.show');
+app.get('/posts/:slug', (ctx) => ({})).name('posts.show');
+```
+
+### Generating URLs
+
+```typescript
+// Basic URL generation
+const url = app.route('users.show', { id: 42 });
+// "/users/42"
+
+// With query string
+const searchUrl = app.route('users.show', { id: 42, tab: 'profile' });
+// "/users/42?tab=profile"
+
+// Check if route exists
+if (app.hasRoute('users.show')) {
+  // ...
+}
+
+// List all routes
+const routes = app.getRoutes();
+// [{ name: 'users.show', method: 'GET', path: '/users/:id' }, ...]
+```
+
+## Route Constraints
+
+Add regex constraints to validate route parameters.
+
+### Basic Constraints
+
+```typescript
+// Only match if :id is numeric
+app.get('/users/:id', (ctx) => ({}))
+  .where('id', /^\d+$/);
+
+// Using string pattern
+app.get('/posts/:slug', (ctx) => ({}))
+  .where('slug', '^[a-z0-9-]+$');
+
+// Multiple constraints
+app.get('/users/:id/posts/:postId', (ctx) => ({}))
+  .where({ id: /^\d+$/, postId: /^\d+$/ });
+```
+
+### Helper Methods
+
+```typescript
+// whereNumber - digits only
+app.get('/users/:id', () => ({})).whereNumber('id');
+
+// whereAlpha - letters only (a-zA-Z)
+app.get('/categories/:name', () => ({})).whereAlpha('name');
+
+// whereAlphaNumeric - letters and digits
+app.get('/codes/:code', () => ({})).whereAlphaNumeric('code');
+
+// whereUuid - UUID format
+app.get('/items/:uuid', () => ({})).whereUuid('uuid');
+
+// whereUlid - ULID format
+app.get('/records/:ulid', () => ({})).whereUlid('ulid');
+
+// whereIn - specific allowed values
+app.get('/status/:status', () => ({})).whereIn('status', ['active', 'pending', 'archived']);
+```
+
+### Chaining Constraints
+
+```typescript
+app.get('/users/:id/posts/:slug', (ctx) => ({}))
+  .whereNumber('id')
+  .whereAlpha('slug')
+  .name('users.posts');
+```
+
+## Optional Parameters
+
+Use `?` to mark route parameters as optional.
+
+```typescript
+// :id is optional
+app.get('/users/:id?', (ctx) => {
+  if (ctx.params.id) {
+    return { user: ctx.params.id };
+  }
+  return { users: [] };
+});
+
+// Multiple optional params
+app.get('/archive/:year?/:month?', (ctx) => {
+  const { year, month } = ctx.params;
+  // year and month may be undefined
+  return { year, month };
+});
+
+// Constraints work with optional params
+app.get('/posts/:id?', (ctx) => ({})).whereNumber('id');
+```
+
 ## Error Handling
 
-Uncaught errors in handlers return a 500 response:
+Uncaught errors in handlers return a 500 response with the error message:
 
 ```typescript
 app.get('/error', () => {
@@ -225,7 +383,7 @@ app.get('/error', () => {
 });
 
 // Returns: 500 Internal Server Error
-// Body: { error: "Internal Server Error" }
+// Body: { error: "Something went wrong" }
 ```
 
 ## Types
@@ -238,7 +396,12 @@ import type {
   BunaryServer,
   RequestContext, 
   RouteHandler,
-  Middleware 
+  Middleware,
+  RouteBuilder,
+  GroupOptions,
+  GroupRouter,
+  GroupCallback,
+  RouteInfo
 } from '@bunary/http';
 ```
 

package/dist/app.d.ts

@@ -1,21 +1,4 @@
-/**
- * Create a new Bunary HTTP application instance.
- *
- * @returns BunaryApp instance with routing and middleware support
- *
- * @example
- * ```ts
- * import { createApp } from "@bunary/http";
- *
- * const app = createApp();
- *
- * app.get("/", () => ({ message: "Hello!" }));
- * app.get("/users/:id", (ctx) => ({ id: ctx.params.id }));
- *
- * app.listen(3000);
- * ```
- */
-import type { BunaryApp } from "./types.js";
+import type { BunaryApp } from "./types/index.js";
 /**
  * Create a new Bunary HTTP application instance.
  *
@@ -38,15 +21,14 @@ import type { BunaryApp } from "./types.js";
  *   return { id: ctx.params.id };
  * });
  *
- * // Query parameters
- * app.get("/search", (ctx) => {
- *   return { query: ctx.query.get("q") };
+ * // Route groups
+ * app.group("/api", (router) => {
+ *   router.get("/users", () => ({ users: [] }));
  * });
  *
- * // Custom Response
- * app.get("/custom", () => {
- *   return new Response("Custom", { status: 201 });
- * });
+ * // Named routes
+ * app.get("/users/:id", (ctx) => ({ id: ctx.params.id })).name("users.show");
+ * const url = app.route("users.show", { id: 123 });
  *
  * app.listen(3000);
  * ```

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EACX,SAAS,EAQT,MAAM,YAAY,CAAC;AA0FpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAuOrC"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACX,SAAS,EAYT,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAmOrC"}

package/dist/index.d.ts

@@ -18,6 +18,6 @@
  *
  * @packageDocumentation
  */
-export type { AppOptions, BunaryApp, BunaryServer, HandlerResponse, HttpMethod, Middleware, PathParams, QueryParams, RequestContext, Route, RouteHandler, } from "./types.js";
+export type { AppOptions, BunaryApp, BunaryServer, GroupCallback, GroupOptions, GroupRouter, HandlerResponse, HttpMethod, Middleware, PathParams, QueryParams, RequestContext, Route, RouteBuilder, RouteHandler, RouteInfo, } from "./types/index.js";
 export { createApp } from "./app.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,YAAY,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,KAAK,EACL,YAAY,GACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,YAAY,EACX,UAAU,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,eAAe,EACf,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,GACT,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -1,26 +1,5 @@
 // @bun
-// src/app.ts
-function compilePath(path) {
-  const paramNames = [];
-  const regexString = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_match, paramName) => {
-    paramNames.push(paramName);
-    return "([^/]+)";
-  });
-  return {
-    pattern: new RegExp(`^${regexString}$`),
-    paramNames
-  };
-}
-function extractParams(path, route) {
-  const match = path.match(route.pattern);
-  if (!match)
-    return {};
-  const params = {};
-  for (let i = 0;i < route.paramNames.length; i++) {
-    params[route.paramNames[i]] = match[i + 1];
-  }
-  return params;
-}
+// src/response.ts
 function toResponse(result) {
   if (result instanceof Response) {
     return result;
@@ -45,34 +24,296 @@ function toResponse(result) {
     headers: { "Content-Type": "application/json" }
   });
 }
+
+// src/router.ts
+function compilePath(path) {
+  const paramNames = [];
+  const optionalParams = [];
+  let regexString = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  regexString = regexString.replace(/\/:([a-zA-Z_][a-zA-Z0-9_]*)(\\\?)?/g, (_match, paramName, isOptional) => {
+    if (paramNames.includes(paramName)) {
+      throw new Error(`Duplicate parameter name ":${paramName}" in route pattern "${path}". Each parameter name must be unique within a route.`);
+    }
+    paramNames.push(paramName);
+    if (isOptional) {
+      optionalParams.push(paramName);
+      return "(?:/([^/]+))?";
+    }
+    return "/([^/]+)";
+  });
+  regexString += "/?";
+  return {
+    pattern: new RegExp(`^${regexString}$`),
+    paramNames,
+    optionalParams
+  };
+}
+function extractParams(path, route) {
+  const match = path.match(route.pattern);
+  if (!match)
+    return {};
+  const params = {};
+  for (let i = 0;i < route.paramNames.length; i++) {
+    const value = match[i + 1];
+    if (value !== undefined && value !== "") {
+      params[route.paramNames[i]] = value;
+    }
+  }
+  return params;
+}
+function checkConstraints(params, constraints) {
+  if (!constraints)
+    return true;
+  for (const [param, pattern] of Object.entries(constraints)) {
+    const value = params[param];
+    if (value === undefined)
+      continue;
+    if (!pattern.test(value))
+      return false;
+  }
+  return true;
+}
+
+// src/routes/builder.ts
+function compilePattern(pattern, param) {
+  try {
+    return new RegExp(pattern);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid pattern";
+    throw new Error(`Invalid regex pattern for parameter "${param}": ${message}`);
+  }
+}
+function createRouteBuilder(route, namedRoutes, app) {
+  function addConstraint(param, pattern) {
+    if (!route.constraints) {
+      route.constraints = {};
+    }
+    route.constraints[param] = pattern;
+  }
+  const builder = {
+    get get() {
+      return app.get;
+    },
+    get post() {
+      return app.post;
+    },
+    get put() {
+      return app.put;
+    },
+    get delete() {
+      return app.delete;
+    },
+    get patch() {
+      return app.patch;
+    },
+    get use() {
+      return app.use;
+    },
+    get group() {
+      return app.group;
+    },
+    get route() {
+      return app.route;
+    },
+    get hasRoute() {
+      return app.hasRoute;
+    },
+    get getRoutes() {
+      return app.getRoutes;
+    },
+    get listen() {
+      return app.listen;
+    },
+    get fetch() {
+      return app.fetch;
+    },
+    name: (name) => {
+      if (namedRoutes.has(name)) {
+        throw new Error(`Route name "${name}" is already defined`);
+      }
+      route.name = name;
+      namedRoutes.set(name, route);
+      return builder;
+    },
+    where: (paramOrConstraints, pattern) => {
+      if (typeof paramOrConstraints === "string") {
+        if (!pattern) {
+          throw new Error(`Pattern is required for constraint on "${paramOrConstraints}"`);
+        }
+        const regex = typeof pattern === "string" ? compilePattern(pattern, paramOrConstraints) : pattern;
+        addConstraint(paramOrConstraints, regex);
+      } else {
+        for (const [param, pat] of Object.entries(paramOrConstraints)) {
+          const regex = typeof pat === "string" ? compilePattern(pat, param) : pat;
+          addConstraint(param, regex);
+        }
+      }
+      return builder;
+    },
+    whereNumber: (param) => {
+      addConstraint(param, /^\d+$/);
+      return builder;
+    },
+    whereAlpha: (param) => {
+      addConstraint(param, /^[a-zA-Z]+$/);
+      return builder;
+    },
+    whereAlphaNumeric: (param) => {
+      addConstraint(param, /^[a-zA-Z0-9]+$/);
+      return builder;
+    },
+    whereUuid: (param) => {
+      addConstraint(param, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+      return builder;
+    },
+    whereUlid: (param) => {
+      addConstraint(param, /^[0-9A-HJKMNP-TV-Z]{26}$/);
+      return builder;
+    },
+    whereIn: (param, values) => {
+      if (values.length === 0) {
+        throw new Error(`whereIn requires at least one value for parameter "${param}"`);
+      }
+      const escaped = values.map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+      addConstraint(param, new RegExp(`^(${escaped.join("|")})$`));
+      return builder;
+    }
+  };
+  return builder;
+}
+function wrapBuilderWithNamePrefix(builder, namePrefix) {
+  if (!namePrefix)
+    return builder;
+  return new Proxy(builder, {
+    get(target, prop) {
+      if (prop === "name") {
+        return (name) => {
+          return target.name(namePrefix + name);
+        };
+      }
+      return target[prop];
+    }
+  });
+}
+// src/routes/find.ts
+function findRoute(routes, method, path) {
+  for (const route of routes) {
+    if (route.pattern.test(path)) {
+      if (route.method === method) {
+        const params = extractParams(path, route);
+        if (!checkConstraints(params, route.constraints)) {
+          continue;
+        }
+        return { route, params };
+      }
+    }
+  }
+  return null;
+}
+function hasMatchingPath(routes, path) {
+  return routes.some((route) => {
+    if (!route.pattern.test(path))
+      return false;
+    const params = extractParams(path, route);
+    return checkConstraints(params, route.constraints);
+  });
+}
+// src/pathUtils.ts
+function normalizePrefix(prefix) {
+  let normalized = prefix;
+  if (!normalized.startsWith("/")) {
+    normalized = `/${normalized}`;
+  }
+  if (normalized.endsWith("/") && normalized.length > 1) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+function joinPaths(prefix, path) {
+  const normalizedPrefix = normalizePrefix(prefix);
+  let normalizedPath = path;
+  if (!normalizedPath.startsWith("/") && normalizedPath !== "") {
+    normalizedPath = `/${normalizedPath}`;
+  }
+  if (normalizedPath === "/") {
+    return normalizedPrefix;
+  }
+  return normalizedPrefix + normalizedPath;
+}
+
+// src/routes/group.ts
+function createGroupRouter(prefix, groupMiddleware, namePrefix, addRoute) {
+  const router = {
+    get: (path, handler) => {
+      const fullPath = joinPaths(prefix, path);
+      const builder = addRoute("GET", fullPath, handler, groupMiddleware);
+      return wrapBuilderWithNamePrefix(builder, namePrefix);
+    },
+    post: (path, handler) => {
+      const fullPath = joinPaths(prefix, path);
+      return wrapBuilderWithNamePrefix(addRoute("POST", fullPath, handler, groupMiddleware), namePrefix);
+    },
+    put: (path, handler) => {
+      const fullPath = joinPaths(prefix, path);
+      return wrapBuilderWithNamePrefix(addRoute("PUT", fullPath, handler, groupMiddleware), namePrefix);
+    },
+    delete: (path, handler) => {
+      const fullPath = joinPaths(prefix, path);
+      return wrapBuilderWithNamePrefix(addRoute("DELETE", fullPath, handler, groupMiddleware), namePrefix);
+    },
+    patch: (path, handler) => {
+      const fullPath = joinPaths(prefix, path);
+      return wrapBuilderWithNamePrefix(addRoute("PATCH", fullPath, handler, groupMiddleware), namePrefix);
+    },
+    group: (prefixOrOptions, callback) => {
+      const opts = typeof prefixOrOptions === "string" ? { prefix: prefixOrOptions } : prefixOrOptions;
+      const nestedPrefix = joinPaths(prefix, opts.prefix);
+      const nestedMiddleware = [...groupMiddleware, ...opts.middleware ?? []];
+      const nestedNamePrefix = namePrefix + (opts.name ?? "");
+      const nestedRouter = createGroupRouter(nestedPrefix, nestedMiddleware, nestedNamePrefix, addRoute);
+      callback(nestedRouter);
+      return router;
+    }
+  };
+  return router;
+}
+// src/app.ts
 function createApp() {
   const routes = [];
   const middlewares = [];
-  function addRoute(method, path, handler) {
-    const { pattern, paramNames } = compilePath(path);
-    routes.push({ method, path, pattern, paramNames, handler });
-    return app;
-  }
-  function findRoute(method, path) {
-    for (const route of routes) {
-      if (route.pattern.test(path)) {
-        if (route.method === method) {
-          return { route, params: extractParams(path, route) };
-        }
-      }
+  const namedRoutes = new Map;
+  let globalMiddlewareVersion = 0;
+  const middlewareCache = new WeakMap;
+  function getMiddlewareChain(route) {
+    const cached = middlewareCache.get(route);
+    if (cached && cached.version === globalMiddlewareVersion) {
+      return cached.chain;
     }
-    return null;
+    const chain = route.middleware ? [...middlewares, ...route.middleware] : middlewares.length > 0 ? [...middlewares] : [];
+    middlewareCache.set(route, { version: globalMiddlewareVersion, chain });
+    return chain;
   }
-  function hasMatchingPath(path) {
-    return routes.some((route) => route.pattern.test(path));
+  function addRoute(method, path, handler, groupMiddleware = []) {
+    const { pattern, paramNames, optionalParams } = compilePath(path);
+    const route = {
+      method,
+      path,
+      pattern,
+      paramNames,
+      handler,
+      optionalParams: optionalParams.length > 0 ? optionalParams : undefined,
+      middleware: groupMiddleware.length > 0 ? [...groupMiddleware] : undefined
+    };
+    routes.push(route);
+    return createRouteBuilder(route, namedRoutes, app);
   }
   async function handleRequest(request) {
     const url = new URL(request.url);
     const path = url.pathname;
     const method = request.method;
-    const match = findRoute(method, path);
+    const match = findRoute(routes, method, path);
     if (!match) {
-      if (hasMatchingPath(path)) {
+      if (hasMatchingPath(routes, path)) {
         return new Response(JSON.stringify({ error: "Method not allowed" }), {
           status: 405,
           headers: { "Content-Type": "application/json" }
@@ -89,10 +330,11 @@ function createApp() {
       query: url.searchParams
     };
     try {
+      const allMiddleware = getMiddlewareChain(match.route);
       let index = 0;
       const next = async () => {
-        if (index < middlewares.length) {
-          const middleware = middlewares[index++];
+        if (index < allMiddleware.length) {
+          const middleware = allMiddleware[index++];
           return await middleware(ctx, next);
         }
         return await match.route.handler(ctx);
@@ -115,8 +357,67 @@ function createApp() {
     patch: (path, handler) => addRoute("PATCH", path, handler),
     use: (middleware) => {
       middlewares.push(middleware);
+      globalMiddlewareVersion++;
+      return app;
+    },
+    group: (prefixOrOptions, callback) => {
+      const opts = typeof prefixOrOptions === "string" ? { prefix: prefixOrOptions } : prefixOrOptions;
+      const groupRouter = createGroupRouter(opts.prefix, opts.middleware ?? [], opts.name ?? "", addRoute);
+      callback(groupRouter);
       return app;
     },
+    route: (name, params) => {
+      const route = namedRoutes.get(name);
+      if (!route) {
+        throw new Error(`Route "${name}" not found`);
+      }
+      if (params) {
+        for (const [key, value] of Object.entries(params)) {
+          const strValue = String(value);
+          if (strValue.includes("\r") || strValue.includes(`
+`) || strValue.includes("\x00")) {
+            throw new Error(`Invalid character in parameter "${key}": control characters are not allowed`);
+          }
+        }
+      }
+      let url = route.path;
+      const queryParams = {};
+      const usedParams = new Set;
+      for (const paramName of route.paramNames) {
+        const isOptional = route.optionalParams?.includes(paramName);
+        const value = params?.[paramName];
+        if (value !== undefined) {
+          url = url.replace(new RegExp(`:${paramName}\\??`), encodeURIComponent(String(value)));
+          usedParams.add(paramName);
+        } else if (isOptional) {
+          url = url.replace(new RegExp(`/:${paramName}\\?`), "");
+        } else {
+          throw new Error(`Missing required param "${paramName}" for route "${name}"`);
+        }
+      }
+      if (params) {
+        for (const [key, value] of Object.entries(params)) {
+          if (!usedParams.has(key)) {
+            queryParams[key] = String(value);
+          }
+        }
+      }
+      if (Object.keys(queryParams).length > 0) {
+        const qs = new URLSearchParams(queryParams).toString();
+        url += `?${qs}`;
+      }
+      return url;
+    },
+    hasRoute: (name) => {
+      return namedRoutes.has(name);
+    },
+    getRoutes: () => {
+      return routes.map((route) => ({
+        name: route.name ?? null,
+        method: route.method,
+        path: route.path
+      }));
+    },
     listen: (port = 3000, hostname = "localhost") => {
       const server = Bun.serve({
         port,