@aura-stack/router 0.1.0 → 0.3.0

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { ZodObject, z } from 'zod';
+import { RouterError } from './error.js';
 
 /**
  * Route pattern must start with a slash and can contain parameters prefixed with a colon.
@@ -6,15 +7,16 @@ import { ZodObject, z } from 'zod';
  * const getUser:RoutePattern = "/users/:userId"
  * const getPostsComments:RoutePattern = "/posts/:postId/comments/:commentId"
  */
-type RoutePattern = `/${string}`;
+type RoutePattern = `/${string}` | `/${string}/:${string}`;
 /**
- * HTTP methods supported by the router.
+ * HTTP methods defined in HTTP/1.1 specification.
+ * @see https://datatracker.ietf.org/doc/html/rfc7231#section-4.3
  */
-type HTTPMethod = "GET" | "POST" | "DELETE" | "PUT" | "PATCH";
+type HTTPMethod = "GET" | "POST" | "DELETE" | "PUT" | "PATCH" | "OPTIONS" | "HEAD" | "TRACE" | "CONNECT";
 /**
  * Content types supported by the router.
  */
-type ContentType = "application/json" | "application/x-www-form-urlencoded" | "text/plain";
+type ContentType = "application/json" | "application/x-www-form-urlencoded" | "text/plain" | "multipart/form-data" | "application/xml" | "application/octet-stream" | `text/${string}` | `image/${string}` | `video/${string}` | `audio/${string}` | "application/pdf";
 type Prettify<Obj extends object> = {
     [Key in keyof Obj]: Obj[Key];
 } & {};
@@ -33,20 +35,20 @@ type Prettify<Obj extends object> = {
  * // Expected: {}
  * type NoParams = Params<"/about">;
  */
-type Params<Route extends RoutePattern> = Route extends `/${string}/:${infer Param}/${infer Str}` ? Prettify<{
+type GetRouteParams<Route extends RoutePattern> = Route extends `/${string}/:${infer Param}/${infer Str}` ? Prettify<{
     [K in Param]: string;
-} & Params<`/${Str}`>> : Route extends `/${string}/:${infer Param}` ? Prettify<{
+} & GetRouteParams<`/${Str}`>> : Route extends `/${string}/:${infer Param}` ? Prettify<{
     [K in Param]: string;
 }> : Route extends `/:${infer Param}` ? Prettify<{
     [K in Param]: string;
 }> : {};
-type GetRouteParams<T extends RoutePattern> = Params<T>;
 /**
  * Available schemas validation for an endpoint. It can include body and searchParams schemas.
  */
 interface EndpointSchemas {
     body?: ZodObject<any>;
     searchParams?: ZodObject<any>;
+    params?: ZodObject<any>;
 }
 /**
  * Configuration for an endpoint, including optional schemas for request validation and middlewares.
@@ -77,12 +79,22 @@ type ContextBody<Schemas extends EndpointConfig["schemas"]> = Schemas extends {
 } : {
     body: undefined;
 };
+/**
+ * Infer the type of route parameters from the provided value in the `EndpointConfig`.
+ */
+type ContextParams<Schemas extends EndpointConfig["schemas"], Default = Record<string, string>> = Schemas extends {
+    params: ZodObject;
+} ? {
+    params: z.infer<Schemas["params"]>;
+} : {
+    params: Default;
+};
 /**
  * Context object passed to route handlers and middlewares defined in the
  * `createEndpoint/createEndpointConfig` function or globally in the `createRouter` function.
  */
 interface RequestContext<RouteParams = Record<string, string>, Config extends EndpointConfig = EndpointConfig> {
-    params: RouteParams;
+    params: ContextParams<Config["schemas"], RouteParams>["params"];
     headers: Headers;
     body: ContextBody<Config["schemas"]>["body"];
     searchParams: ContextSearchParams<Config["schemas"]>["searchParams"];
@@ -101,7 +113,7 @@ type MiddlewareFunction<RouteParams = Record<string, string>, Config extends End
  * The handler receives the request object and a context containing route parameters, headers,
  * and optionally validated body and search parameters based on the endpoint configuration.
  */
-type RouteHandler<Route extends RoutePattern, Config extends EndpointConfig> = (request: Request, ctx: Prettify<RequestContext<GetRouteParams<Route>, Config>>) => Promise<Response>;
+type RouteHandler<Route extends RoutePattern, Config extends EndpointConfig> = (request: Request, ctx: Prettify<RequestContext<GetRouteParams<Route>, Config>>) => Response | Promise<Response>;
 /**
  * Represents a route endpoint definition, specifying the HTTP method, route pattern,
  * handler function with inferred context types, and associated configuration.
@@ -121,14 +133,59 @@ type InferMethod<Endpoints extends RouteEndpoint[]> = Endpoints extends unknown[
  * Each method is a function that takes a request and context, returning a promise of a response.
  */
 type GetHttpHandlers<Endpoints extends RouteEndpoint[]> = {
-    [Method in InferMethod<Endpoints>]: (req: Request, ctx: RequestContext) => Promise<Response>;
+    [Method in InferMethod<Endpoints>]: (req: Request) => Response | Promise<Response>;
 };
 /**
  * Configuration options for `createRouter` function.
  */
 interface RouterConfig {
+    /**
+     * Prefix path for all routes/endpoints defined in the router.
+     *
+     * @example
+     * basePath: "/api/v1"
+     *
+     * // will match the "/users" endpoint.
+     * new Request("https://example.com/api/v1/users")
+     *
+     * // will NOT match the "/users" endpoint.
+     * new Request("https://example.com/users")
+     */
     basePath?: RoutePattern;
+    /**
+     * Global middlewares that run before route matching for all endpoints in the router.
+     * You can use this to modify the request or return a response early.
+     *
+     * @example
+     * middlewares: [
+     *   async (request) => {
+     *     if(request.headers.get("Authorization")?.startsWith("Bearer ")) {
+     *       return Response.json({ message: "Unauthorized" }, { status: 401 })
+     *     }
+     *     return request
+     *   }
+     * ]
+     */
     middlewares?: GlobalMiddleware[];
+    /**
+     * Error handler function that runs when an error is thrown in a router handler or middleware.
+     * It can be used to customize the default error response provided by the router. If is an internal
+     * error the error is from the `RouterError` class, otherwise the error is a generic
+     * `Error` instance which was caused by a handler or middleware, for how to distinguish them you can use
+     * the `isRouterError` function from the `assert` module.
+     *
+     * @param error - The error thrown in the router
+     * @param request - The original request that caused the error
+     * @returns A response to be sent back to the client
+     * @example
+     * onError: (error, request) => {
+     *   if(isRouterError(error)) {
+     *     return Response.json({ message: error.message }, { status: error.statusCode })
+     *   }
+     *   return Response.json({ message: "Internal Server Error" }, { status: 500 })
+     * }
+     */
+    onError?: (error: Error | RouterError, request: Request) => Response | Promise<Response>;
 }
 
-export type { ContentType, ContextBody, ContextSearchParams, EndpointConfig, EndpointSchemas, GetHttpHandlers, GetRouteParams, GlobalMiddleware, HTTPMethod, InferMethod, MiddlewareFunction, Params, Prettify, RequestContext, RouteEndpoint, RouteHandler, RoutePattern, RouterConfig };
+export type { ContentType, ContextBody, ContextParams, ContextSearchParams, EndpointConfig, EndpointSchemas, GetHttpHandlers, GetRouteParams, GlobalMiddleware, HTTPMethod, InferMethod, MiddlewareFunction, Prettify, RequestContext, RouteEndpoint, RouteHandler, RoutePattern, RouterConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aura-stack/router",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A lightweight TypeScript library for building, managing, and validating API routes and endpoints in Node.js applications.",
   "files": [
@@ -22,6 +22,11 @@
       "import": "./dist/endpoint.js",
       "require": "./dist/endpoint.cjs"
     },
+    "./error": {
+      "types": "./dist/error.d.ts",
+      "import": "./dist/error.js",
+      "require": "./dist/error.cjs"
+    },
     "./types": "./dist/types.d.ts"
   },
   "keywords": [
@@ -44,12 +49,15 @@
   },
   "scripts": {
     "dev": "tsup --watch",
+    "dev:docs": "pnpm --filter docs dev",
     "build": "tsup",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "vitest --run",
     "test:watch": "vitest",
+    "test:bench": "vitest --run bench",
     "type-check": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "clean:cts": "rm -rf dist/*.cts"
   }
 }

package/dist/chunk-6UBPSXKR.js

@@ -1,36 +0,0 @@
-import {
-  isSupportedMethod,
-  isValidHandler,
-  isValidRoute
-} from "./chunk-ENOBC3XN.js";
-import {
-  AuraStackRouterError
-} from "./chunk-RFYOPPMW.js";
-
-// src/endpoint.ts
-var createRoutePattern = (route) => {
-  const pattern = route.replace(/:[^/]+/g, "([^/]+)").replace(/\//g, "\\/");
-  return new RegExp(`^${pattern}$`);
-};
-var createEndpoint = (method, route, handler, config = {}) => {
-  if (!isSupportedMethod(method)) {
-    throw new AuraStackRouterError("METHOD_NOT_ALLOWED", `Unsupported HTTP method: ${method}`);
-  }
-  if (!isValidRoute(route)) {
-    throw new AuraStackRouterError("BAD_REQUEST", `Invalid route format: ${route}`);
-  }
-  if (!isValidHandler(handler)) {
-    throw new AuraStackRouterError("BAD_REQUEST", "Handler must be a function");
-  }
-  return { method, route, handler, config };
-};
-function createEndpointConfig(...args) {
-  if (typeof args[0] === "string") return args[1];
-  return args[0];
-}
-
-export {
-  createRoutePattern,
-  createEndpoint,
-  createEndpointConfig
-};

package/dist/chunk-ENOBC3XN.js

@@ -1,23 +0,0 @@
-// src/assert.ts
-var supportedMethods = ["GET", "POST", "DELETE", "PUT", "PATCH"];
-var supportedBodyMethods = ["POST", "PUT", "PATCH"];
-var isSupportedMethod = (method) => {
-  return supportedMethods.includes(method);
-};
-var isSupportedBodyMethod = (method) => {
-  return supportedBodyMethods.includes(method);
-};
-var isValidRoute = (route) => {
-  const routePattern = /^\/[a-zA-Z0-9/_:-]*$/;
-  return routePattern.test(route);
-};
-var isValidHandler = (handler) => {
-  return typeof handler === "function";
-};
-
-export {
-  isSupportedMethod,
-  isSupportedBodyMethod,
-  isValidRoute,
-  isValidHandler
-};

package/dist/chunk-NNCUFWPI.js

@@ -1,78 +0,0 @@
-import {
-  createRoutePattern
-} from "./chunk-6UBPSXKR.js";
-import {
-  isSupportedBodyMethod
-} from "./chunk-ENOBC3XN.js";
-import {
-  AuraStackRouterError
-} from "./chunk-RFYOPPMW.js";
-
-// src/context.ts
-var getRouteParams = (route, path) => {
-  const routeRegex = createRoutePattern(route);
-  if (!routeRegex.test(path)) {
-    throw new AuraStackRouterError("BAD_REQUEST", `Missing required route params for route: ${route}`);
-  }
-  const params = routeRegex.exec(route)?.slice(1).map((seg) => seg.replace(":", ""));
-  if (!params) return {};
-  const values = routeRegex.exec(path)?.slice(1);
-  return params.reduce(
-    (previous, now, idx) => ({
-      ...previous,
-      [now]: decodeURIComponent(values?.[idx] ?? "")
-    }),
-    {}
-  );
-};
-var getSearchParams = (url, config) => {
-  const route = new URL(url);
-  if (config.schemas?.searchParams) {
-    const parsed = config.schemas.searchParams.safeParse(Object.fromEntries(route.searchParams.entries()));
-    if (!parsed.success) {
-      throw new AuraStackRouterError("UNPROCESSABLE_ENTITY", "Invalid search parameters");
-    }
-    return parsed.data;
-  }
-  return new URLSearchParams(route.searchParams.toString());
-};
-var getHeaders = (request) => {
-  return new Headers(request.headers);
-};
-var getBody = async (request, config) => {
-  if (!isSupportedBodyMethod(request.method)) {
-    return void 0;
-  }
-  const contentType = request.headers.get("Content-Type") ?? "";
-  if (contentType.includes("application/json")) {
-    const json = await request.json();
-    if (config.schemas?.body) {
-      const parsed = config.schemas.body.safeParse(json);
-      if (!parsed.success) {
-        throw new AuraStackRouterError("UNPROCESSABLE_ENTITY", "Invalid request body");
-      }
-      return parsed.data;
-    }
-    return json;
-  }
-  if (contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data")) {
-    return await request.formData();
-  }
-  if (contentType.includes("text/")) {
-    return await request.text();
-  }
-  if (contentType.includes("application/octet-stream")) {
-    return await request.arrayBuffer();
-  }
-  if (contentType.includes("image/") || contentType.includes("video/") || contentType.includes("audio/")) {
-    return await request.blob();
-  }
-  return null;
-};
-
-export {
-  getRouteParams,
-  getSearchParams,
-  getHeaders,
-  getBody
-};

package/dist/chunk-VBI7H3AK.js

@@ -1,75 +0,0 @@
-import {
-  getBody,
-  getHeaders,
-  getRouteParams,
-  getSearchParams
-} from "./chunk-NNCUFWPI.js";
-import {
-  createRoutePattern
-} from "./chunk-6UBPSXKR.js";
-import {
-  executeGlobalMiddlewares,
-  executeMiddlewares
-} from "./chunk-RVJ2F7OL.js";
-import {
-  AuraStackRouterError
-} from "./chunk-RFYOPPMW.js";
-
-// src/router.ts
-var createRouter = (endpoints, config = {}) => {
-  const server = {};
-  const groups = {
-    GET: [],
-    POST: [],
-    DELETE: [],
-    PUT: [],
-    PATCH: []
-  };
-  endpoints.forEach((endpoint) => groups[endpoint.method].push(endpoint));
-  for (const method in groups) {
-    server[method] = async (request, ctx) => {
-      try {
-        const globalRequest = await executeGlobalMiddlewares(request, config.middlewares);
-        if (globalRequest instanceof Response) {
-          return globalRequest;
-        }
-        const url = new URL(globalRequest.url);
-        const pathname = url.pathname;
-        const endpoint = groups[method].find((endpoint2) => {
-          const withBasePath = config.basePath ? `${config.basePath}${endpoint2.route}` : endpoint2.route;
-          const regex = createRoutePattern(withBasePath);
-          return regex.test(pathname);
-        });
-        if (endpoint) {
-          const withBasePath = config.basePath ? `${config.basePath}${endpoint.route}` : endpoint.route;
-          const body = await getBody(globalRequest, endpoint.config);
-          const params = getRouteParams(withBasePath, pathname);
-          const searchParams = getSearchParams(globalRequest.url, endpoint.config);
-          const headers = getHeaders(globalRequest);
-          const context = {
-            ...ctx,
-            params,
-            searchParams,
-            headers,
-            body
-          };
-          await executeMiddlewares(globalRequest, context, endpoint.config.middlewares);
-          return endpoint.handler(globalRequest, context);
-        }
-        return Response.json({ message: "Not Found" }, { status: 404 });
-      } catch (error) {
-        if (error instanceof AuraStackRouterError) {
-          const { message, status, statusText } = error;
-          console.log("StatusText: ", statusText);
-          return Response.json({ message }, { status, statusText });
-        }
-        return Response.json({ message: "Internal Server Error" }, { status: 500 });
-      }
-    };
-  }
-  return server;
-};
-
-export {
-  createRouter
-};