@aura-stack/router 0.2.0 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
-# `@aura-stack/router`
-
 <div align="center">
 
+<h1>Aura Router</h1>
+
 **A modern, TypeScript-first router and endpoint definition library**
 
 Build fully-typed APIs with declarative endpoints, automatic parameter inference, and first-class middleware support — all returning native `Response` objects.

package/dist/assert.cjs

@@ -20,14 +20,67 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/assert.ts
 var assert_exports = {};
 __export(assert_exports, {
+  isRouterError: () => isRouterError,
   isSupportedBodyMethod: () => isSupportedBodyMethod,
   isSupportedMethod: () => isSupportedMethod,
   isValidHandler: () => isValidHandler,
-  isValidRoute: () => isValidRoute
+  isValidRoute: () => isValidRoute,
+  supportedProtocols: () => supportedProtocols
 });
 module.exports = __toCommonJS(assert_exports);
-var supportedMethods = /* @__PURE__ */ new Set(["GET", "POST", "DELETE", "PUT", "PATCH"]);
+
+// src/error.ts
+var statusCode = {
+  OK: 200,
+  CREATED: 201,
+  ACCEPTED: 202,
+  NO_CONTENT: 204,
+  MULTIPLE_CHOICES: 300,
+  MOVED_PERMANENTLY: 301,
+  FOUND: 302,
+  SEE_OTHER: 303,
+  NOT_MODIFIED: 304,
+  TEMPORARY_REDIRECT: 307,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  PAYMENT_REQUIRED: 402,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  NOT_ACCEPTABLE: 406,
+  PROXY_AUTHENTICATION_REQUIRED: 407,
+  UNPROCESSABLE_ENTITY: 422,
+  INTERNAL_SERVER_ERROR: 500,
+  NOT_IMPLEMENTED: 501,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  HTTP_VERSION_NOT_SUPPORTED: 505
+};
+var statusText = Object.keys(statusCode).reduce(
+  (previous, status) => {
+    return { ...previous, [status]: status };
+  },
+  {}
+);
+var AuraStackRouterError = class extends Error {
+  constructor(type, message, name) {
+    super(message);
+    this.name = name ?? "RouterError";
+    this.status = statusCode[type];
+    this.statusText = statusText[type];
+  }
+};
+var RouterError = class extends AuraStackRouterError {
+  constructor(type, message, name) {
+    super(type, message, name);
+    this.name = name ?? "RouterError";
+  }
+};
+
+// src/assert.ts
+var supportedMethods = /* @__PURE__ */ new Set(["GET", "POST", "DELETE", "PUT", "PATCH", "OPTIONS", "HEAD", "TRACE", "CONNECT"]);
 var supportedBodyMethods = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+var supportedProtocols = /* @__PURE__ */ new Set(["http:", "https:"]);
 var isSupportedMethod = (method) => {
   return supportedMethods.has(method);
 };
@@ -41,10 +94,15 @@ var isValidRoute = (route) => {
 var isValidHandler = (handler) => {
   return typeof handler === "function";
 };
+var isRouterError = (error) => {
+  return error instanceof RouterError;
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  isRouterError,
   isSupportedBodyMethod,
   isSupportedMethod,
   isValidHandler,
-  isValidRoute
+  isValidRoute,
+  supportedProtocols
 });

package/dist/assert.d.ts

@@ -1,6 +1,8 @@
+import { RouterError } from './error.js';
 import { HTTPMethod, RoutePattern, RouteHandler } from './types.js';
 import 'zod';
 
+declare const supportedProtocols: Set<string>;
 /**
  * Checks if the provided method is a supported HTTP method.
  *
@@ -28,5 +30,23 @@ declare const isValidRoute: (route: string) => route is RoutePattern;
  * @returns True if the handler is valid, false otherwise.
  */
 declare const isValidHandler: (handler: unknown) => handler is RouteHandler<any, any>;
+/**
+ * Asserts that the error is an instance of RouterError. It is useful if you want
+ * to check if the error thrown by the router is an RouterError or by other sources.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an instance of RouterError, false otherwise.
+ * @example
+ * import { isRouterError } from "aura-stack/router";
+ *
+ * try {
+ *   // Some router operation that may throw an error
+ * } catch (error) {
+ *  if (isRouterError(error)) {
+ *    // Handle RouterError
+ *  }
+ * }
+ */
+declare const isRouterError: (error: unknown) => error is RouterError;
 
-export { isSupportedBodyMethod, isSupportedMethod, isValidHandler, isValidRoute };
+export { isRouterError, isSupportedBodyMethod, isSupportedMethod, isValidHandler, isValidRoute, supportedProtocols };

package/dist/assert.js

@@ -1,12 +1,17 @@
 import {
+  isRouterError,
   isSupportedBodyMethod,
   isSupportedMethod,
   isValidHandler,
-  isValidRoute
-} from "./chunk-JRJKKBSH.js";
+  isValidRoute,
+  supportedProtocols
+} from "./chunk-JNMXLKDG.js";
+import "./chunk-GJC3ODME.js";
 export {
+  isRouterError,
   isSupportedBodyMethod,
   isSupportedMethod,
   isValidHandler,
-  isValidRoute
+  isValidRoute,
+  supportedProtocols
 };

package/dist/chunk-6PZEXNTS.js

@@ -0,0 +1,31 @@
+import {
+  isSupportedMethod,
+  isValidHandler,
+  isValidRoute
+} from "./chunk-JNMXLKDG.js";
+import {
+  RouterError
+} from "./chunk-GJC3ODME.js";
+
+// src/endpoint.ts
+var createEndpoint = (method, route, handler, config = {}) => {
+  if (!isSupportedMethod(method)) {
+    throw new RouterError("METHOD_NOT_ALLOWED", `Unsupported HTTP method: ${method}`);
+  }
+  if (!isValidRoute(route)) {
+    throw new RouterError("BAD_REQUEST", `Invalid route format: ${route}`);
+  }
+  if (!isValidHandler(handler)) {
+    throw new RouterError("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 {
+  createEndpoint,
+  createEndpointConfig
+};

package/dist/chunk-CFAIW6YL.js

@@ -0,0 +1,41 @@
+import {
+  RouterError
+} from "./chunk-GJC3ODME.js";
+
+// src/middlewares.ts
+var executeGlobalMiddlewares = async (context, middlewares) => {
+  if (!middlewares) return context;
+  for (const middleware of middlewares) {
+    if (typeof middleware !== "function") {
+      throw new RouterError("BAD_REQUEST", "Global middlewares must be functions");
+    }
+    const executed = await middleware(context);
+    if (executed instanceof Response) {
+      return executed;
+    }
+    context = executed;
+  }
+  if (!context || !(context.request instanceof Request)) {
+    throw new RouterError("BAD_REQUEST", "Global middleware must return a Request or Response object");
+  }
+  return context;
+};
+var executeMiddlewares = async (context, middlewares = []) => {
+  try {
+    let ctx = context;
+    for (const middleware of middlewares) {
+      if (typeof middleware !== "function") {
+        throw new RouterError("BAD_REQUEST", "Middleware must be a function");
+      }
+      ctx = await middleware(ctx);
+    }
+    return ctx;
+  } catch {
+    throw new RouterError("BAD_REQUEST", "Handler threw an error");
+  }
+};
+
+export {
+  executeGlobalMiddlewares,
+  executeMiddlewares
+};

package/dist/chunk-CL5D7UJU.js

@@ -0,0 +1,149 @@
+import {
+  getBody,
+  getHeaders,
+  getRouteParams,
+  getSearchParams
+} from "./chunk-PT4GU6PH.js";
+import {
+  isRouterError,
+  isSupportedMethod
+} from "./chunk-JNMXLKDG.js";
+import {
+  executeGlobalMiddlewares,
+  executeMiddlewares
+} from "./chunk-CFAIW6YL.js";
+import {
+  RouterError,
+  statusText
+} from "./chunk-GJC3ODME.js";
+
+// src/router.ts
+var createNode = () => ({
+  statics: /* @__PURE__ */ new Map(),
+  endpoints: /* @__PURE__ */ new Map()
+});
+var insert = (root, endpoint) => {
+  if (!root || !endpoint) return;
+  let node = root;
+  const segments = endpoint.route === "/" ? [] : endpoint.route.split("/").filter(Boolean);
+  for (const segment of segments) {
+    if (segment.startsWith(":")) {
+      const name = segment.slice(1);
+      if (!node.param) {
+        node.param = { name, node: createNode() };
+      } else if (node.param.name !== name) {
+        throw new RouterError(
+          "BAD_REQUEST",
+          `Conflicting in the route by the dynamic segment "${node.param.name}" and "${name}"`
+        );
+      }
+      node = node.param.node;
+    } else {
+      if (!node.statics.has(segment)) {
+        node.statics.set(segment, createNode());
+      }
+      node = node.statics.get(segment);
+    }
+  }
+  if (node.endpoints.has(endpoint.method)) {
+    throw new RouterError("BAD_REQUEST", `Duplicate endpoint for ${endpoint?.method} ${endpoint?.route}`);
+  }
+  node.endpoints.set(endpoint.method, endpoint);
+};
+var search = (method, root, pathname) => {
+  let node = root;
+  const params = {};
+  const segments = pathname === "/" ? [] : pathname.split("/").filter(Boolean);
+  for (const segment of segments) {
+    if (node?.statics.has(segment)) {
+      node = node.statics.get(segment);
+    } else if (node?.param) {
+      params[node.param.name] = decodeURIComponent(segment);
+      node = node.param.node;
+    } else {
+      throw new RouterError("NOT_FOUND", `No route found for path: ${pathname}`);
+    }
+  }
+  if (!node.endpoints.has(method)) {
+    throw new RouterError("NOT_FOUND", `No route found for path: ${pathname}`);
+  }
+  return { endpoint: node.endpoints.get(method), params };
+};
+var handleError = async (error, request, config) => {
+  if (config.onError) {
+    try {
+      const response = await config.onError(error, request);
+      return response;
+    } catch {
+      return Response.json(
+        { message: "A critical failure occurred during error handling" },
+        { status: 500, statusText: statusText.INTERNAL_SERVER_ERROR }
+      );
+    }
+  }
+  if (isRouterError(error)) {
+    const { message, status, statusText: statusText2 } = error;
+    return Response.json({ message }, { status, statusText: statusText2 });
+  }
+  return Response.json({ message: "Internal Server Error" }, { status: 500, statusText: statusText.INTERNAL_SERVER_ERROR });
+};
+var handleRequest = async (method, request, config, root) => {
+  try {
+    if (!isSupportedMethod(request.method)) {
+      throw new RouterError("METHOD_NOT_ALLOWED", `The HTTP method '${request.method}' is not supported`);
+    }
+    const globalContext = { request, context: config.context ?? {} };
+    const globalRequestContext = await executeGlobalMiddlewares(globalContext, config.middlewares);
+    if (globalRequestContext instanceof Response) return globalRequestContext;
+    const url = new URL(globalRequestContext.request.url);
+    const pathnameWithBase = url.pathname;
+    if (globalRequestContext.request.method !== method) {
+      throw new RouterError("METHOD_NOT_ALLOWED", `The HTTP method '${globalRequestContext.request.method}' is not allowed`);
+    }
+    const { endpoint, params } = search(method, root, pathnameWithBase);
+    if (endpoint.method !== globalRequestContext.request.method) {
+      throw new RouterError("METHOD_NOT_ALLOWED", `The HTTP method '${globalRequestContext.request.method}' is not allowed`);
+    }
+    const dynamicParams = getRouteParams(params, endpoint.config);
+    const body = await getBody(globalRequestContext.request, endpoint.config);
+    const searchParams = getSearchParams(globalRequestContext.request.url, endpoint.config);
+    const headers = getHeaders(globalRequestContext.request);
+    let context = {
+      params: dynamicParams,
+      searchParams,
+      headers,
+      body,
+      request: globalRequestContext.request,
+      url,
+      method: globalRequestContext.request.method,
+      route: endpoint.route,
+      context: config.context ?? {}
+    };
+    context = await executeMiddlewares(context, endpoint.config.middlewares);
+    const response = await endpoint.handler(context);
+    return response;
+  } catch (error) {
+    return handleError(error, request, config);
+  }
+};
+var createRouter = (endpoints, config = {}) => {
+  const root = createNode();
+  const server = {};
+  const methods = /* @__PURE__ */ new Set();
+  for (const endpoint of endpoints) {
+    const withBasePath = config.basePath ? `${config.basePath}${endpoint.route}` : endpoint.route;
+    insert(root, { ...endpoint, route: withBasePath });
+    methods.add(endpoint.method);
+  }
+  for (const method of methods) {
+    server[method] = (request) => handleRequest(method, request, config, root);
+  }
+  return server;
+};
+
+export {
+  createNode,
+  insert,
+  search,
+  createRouter
+};

package/dist/{chunk-RFYOPPMW.js → chunk-GJC3ODME.js}

@@ -25,21 +25,30 @@ var statusCode = {
   SERVICE_UNAVAILABLE: 503,
   HTTP_VERSION_NOT_SUPPORTED: 505
 };
-var statusText = Object.entries(statusCode).reduce(
-  (previous, [status, code]) => {
-    return { ...previous, [code]: status };
+var statusText = Object.keys(statusCode).reduce(
+  (previous, status) => {
+    return { ...previous, [status]: status };
   },
   {}
 );
 var AuraStackRouterError = class extends Error {
   constructor(type, message, name) {
     super(message);
-    this.name = name ?? "AuraStackRouterError";
+    this.name = name ?? "RouterError";
     this.status = statusCode[type];
-    this.statusText = statusText[this.status];
+    this.statusText = statusText[type];
+  }
+};
+var RouterError = class extends AuraStackRouterError {
+  constructor(type, message, name) {
+    super(type, message, name);
+    this.name = name ?? "RouterError";
   }
 };
 
 export {
-  AuraStackRouterError
+  statusCode,
+  statusText,
+  AuraStackRouterError,
+  RouterError
 };

package/dist/{chunk-JRJKKBSH.js → chunk-JNMXLKDG.js}

@@ -1,6 +1,11 @@
+import {
+  RouterError
+} from "./chunk-GJC3ODME.js";
+
 // src/assert.ts
-var supportedMethods = /* @__PURE__ */ new Set(["GET", "POST", "DELETE", "PUT", "PATCH"]);
+var supportedMethods = /* @__PURE__ */ new Set(["GET", "POST", "DELETE", "PUT", "PATCH", "OPTIONS", "HEAD", "TRACE", "CONNECT"]);
 var supportedBodyMethods = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+var supportedProtocols = /* @__PURE__ */ new Set(["http:", "https:"]);
 var isSupportedMethod = (method) => {
   return supportedMethods.has(method);
 };
@@ -14,10 +19,15 @@ var isValidRoute = (route) => {
 var isValidHandler = (handler) => {
   return typeof handler === "function";
 };
+var isRouterError = (error) => {
+  return error instanceof RouterError;
+};
 
 export {
+  supportedProtocols,
   isSupportedMethod,
   isSupportedBodyMethod,
   isValidRoute,
-  isValidHandler
+  isValidHandler,
+  isRouterError
 };

package/dist/chunk-PT4GU6PH.js

@@ -0,0 +1,78 @@
+import {
+  isSupportedBodyMethod
+} from "./chunk-JNMXLKDG.js";
+import {
+  RouterError
+} from "./chunk-GJC3ODME.js";
+
+// src/context.ts
+var getRouteParams = (params, config) => {
+  if (config.schemas?.params) {
+    const parsed = config.schemas.params.safeParse(params);
+    if (!parsed.success) {
+      throw new RouterError("UNPROCESSABLE_ENTITY", "Invalid route parameters");
+    }
+    return parsed.data;
+  }
+  return params;
+};
+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 RouterError("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 null;
+  }
+  const clone = request.clone();
+  const contentType = clone.headers.get("Content-Type") ?? "";
+  if (contentType.includes("application/json") || config.schemas?.body) {
+    const json = await clone.json();
+    if (config.schemas?.body) {
+      const parsed = config.schemas.body.safeParse(json);
+      if (!parsed.success) {
+        throw new RouterError("UNPROCESSABLE_ENTITY", "Invalid request body");
+      }
+      return parsed.data;
+    }
+    return json;
+  }
+  try {
+    if (createContentTypeRegex(["application/x-www-form-urlencoded", "multipart/form-data"], contentType)) {
+      return await clone.formData();
+    }
+    if (createContentTypeRegex(["text/", "application/xml"], contentType)) {
+      return await clone.text();
+    }
+    if (createContentTypeRegex(["application/octet-stream"], contentType)) {
+      return await clone.arrayBuffer();
+    }
+    if (createContentTypeRegex(["image/", "video/", "audio/", "application/pdf"], contentType)) {
+      return await clone.blob();
+    }
+    return null;
+  } catch {
+    throw new RouterError("UNPROCESSABLE_ENTITY", "Invalid request body, the content-type does not match the body format");
+  }
+};
+var createContentTypeRegex = (contentTypes, contenType) => {
+  const regex = new RegExp(`${contentTypes.join("|")}`);
+  return regex.test(contenType);
+};
+
+export {
+  getRouteParams,
+  getSearchParams,
+  getHeaders,
+  getBody
+};

package/dist/context.cjs

@@ -27,12 +27,6 @@ __export(context_exports, {
 });
 module.exports = __toCommonJS(context_exports);
 
-// src/assert.ts
-var supportedBodyMethods = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
-var isSupportedBodyMethod = (method) => {
-  return supportedBodyMethods.has(method);
-};
-
 // src/error.ts
 var statusCode = {
   OK: 200,
@@ -60,50 +54,50 @@ var statusCode = {
   SERVICE_UNAVAILABLE: 503,
   HTTP_VERSION_NOT_SUPPORTED: 505
 };
-var statusText = Object.entries(statusCode).reduce(
-  (previous, [status, code]) => {
-    return { ...previous, [code]: status };
+var statusText = Object.keys(statusCode).reduce(
+  (previous, status) => {
+    return { ...previous, [status]: status };
   },
   {}
 );
 var AuraStackRouterError = class extends Error {
   constructor(type, message, name) {
     super(message);
-    this.name = name ?? "AuraStackRouterError";
+    this.name = name ?? "RouterError";
     this.status = statusCode[type];
-    this.statusText = statusText[this.status];
+    this.statusText = statusText[type];
+  }
+};
+var RouterError = class extends AuraStackRouterError {
+  constructor(type, message, name) {
+    super(type, message, name);
+    this.name = name ?? "RouterError";
   }
 };
 
-// src/endpoint.ts
-var createRoutePattern = (route) => {
-  const pattern = route.replace(/:[^/]+/g, "([^/]+)").replace(/\//g, "\\/");
-  return new RegExp(`^${pattern}$`);
+// src/assert.ts
+var supportedBodyMethods = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+var isSupportedBodyMethod = (method) => {
+  return supportedBodyMethods.has(method);
 };
 
 // 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}`);
+var getRouteParams = (params, config) => {
+  if (config.schemas?.params) {
+    const parsed = config.schemas.params.safeParse(params);
+    if (!parsed.success) {
+      throw new RouterError("UNPROCESSABLE_ENTITY", "Invalid route parameters");
+    }
+    return parsed.data;
   }
-  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] ?? "")
-    }),
-    {}
-  );
+  return params;
 };
 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");
+      throw new RouterError("UNPROCESSABLE_ENTITY", "Invalid search parameters");
     }
     return parsed.data;
   }
@@ -114,33 +108,42 @@ var getHeaders = (request) => {
 };
 var getBody = async (request, config) => {
   if (!isSupportedBodyMethod(request.method)) {
-    return void 0;
+    return null;
   }
-  const contentType = request.headers.get("Content-Type") ?? "";
-  if (contentType.includes("application/json")) {
-    const json = await request.json();
+  const clone = request.clone();
+  const contentType = clone.headers.get("Content-Type") ?? "";
+  if (contentType.includes("application/json") || config.schemas?.body) {
+    const json = await clone.json();
     if (config.schemas?.body) {
       const parsed = config.schemas.body.safeParse(json);
       if (!parsed.success) {
-        throw new AuraStackRouterError("UNPROCESSABLE_ENTITY", "Invalid request body");
+        throw new RouterError("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();
+  try {
+    if (createContentTypeRegex(["application/x-www-form-urlencoded", "multipart/form-data"], contentType)) {
+      return await clone.formData();
+    }
+    if (createContentTypeRegex(["text/", "application/xml"], contentType)) {
+      return await clone.text();
+    }
+    if (createContentTypeRegex(["application/octet-stream"], contentType)) {
+      return await clone.arrayBuffer();
+    }
+    if (createContentTypeRegex(["image/", "video/", "audio/", "application/pdf"], contentType)) {
+      return await clone.blob();
+    }
+    return null;
+  } catch {
+    throw new RouterError("UNPROCESSABLE_ENTITY", "Invalid request body, the content-type does not match the body format");
   }
-  return null;
+};
+var createContentTypeRegex = (contentTypes, contenType) => {
+  const regex = new RegExp(`${contentTypes.join("|")}`);
+  return regex.test(contenType);
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {