@aura-stack/router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aura Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# `@aura-stack/router`
+
+A modern, **TypeScript-first** router and endpoint definition library for Node.js.  
+Build fully-typed APIs with declarative endpoints, automatic parameter inference, and first-class middleware support — all returning native `Response` objects for seamless compatibility with the Fetch API.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Defining Endpoints](#defining-endpoints)
+- [Validation & Middlewares](#validation--middlewares)
+- [API Reference](#api-reference)
+
+## Features
+
+- `Type-safe routing` — only configured HTTP methods are available at compile time.
+- `Declarative API` — define endpoints using `createEndpoint` and group them with `createRouter`.
+- `Typed params & queries` — automatic inference of path (`/users/:id`) and search parameters.
+- `Schema validation` — built-in support for `zod` to validate request bodies, queries, or params.
+- `Middleware chaining` — supports global and per-endpoint middleware execution, with short-circuit control.
+
+## Installation
+
+```bash
+pnpm add @aura-stack/router
+# or
+npm install @aura-stack/router
+# or
+yarn add @aura-stack/router
+```
+
+## Quick Start
+
+```ts
+import { createEndpoint, createRouter } from "@aura-stack/router"
+
+const session = createEndpoint("GET", "/auth/session", async (_, ctx) => {
+  return Response.json(
+    {
+      session: {
+        userId: "uuid",
+        username: "John",
+      },
+    },
+    { headers: ctx.headers }
+  )
+})
+
+const { GET } = createRouter([session])
+```
+
+## Defining Endpoints
+
+```ts
+import { z } from "zod"
+import { createEndpoint, createEndpointConfig } from "@aura-stack/router"
+
+const credentialsConfig = createEndpointConfig({
+  schemas: {
+    body: z.object({
+      username: z.string(),
+      password: z.string(),
+    }),
+  },
+})
+
+export const signIn = createEndpoint(
+  "POST",
+  "/auth/credentials",
+  async (request, ctx) => {
+    const { body, headers } = ctx
+    headers.set("x-login", "success")
+    return Response.json({ status: "ok", body }, { headers })
+  },
+  credentialsConfig
+)
+```
+
+## Validation & Middlewares
+
+**Validation.** Provide Zod schemas in `createEndpointConfig`:
+
+```ts
+import { createEndpoint, createEndpointConfig } from "@aura-stack/router"
+
+const config = createEndpointConfig({
+  schemas: {
+    searchParams: z.object({
+      redirect_uri: z.string(),
+    }),
+  },
+})
+
+const oauth = createEndpoint(
+  "GET",
+  "/auth/signin/:provider",
+  async (_req, ctx) => {
+    const { provider } = ctx.params
+    const { redirect_uri } = ctx.searchParams
+    return Response.json({ provider, redirect_uri }, { status: 302 })
+  },
+  config
+)
+```
+
+If validation fails, the helper throws an informative error before your handler executes.
+
+**Middlewares.** Provide async middleware functions to read or modify the request.
+
+```ts
+import { createRouter, type GlobalMiddleware } from "@aura-stack/router"
+
+const audit: GlobalMiddleware = async (request) => {
+  request.headers.set("x-request-id", crypto.randomUUID())
+  return request
+}
+
+const router = createRouter([oauth], { middlewares: [audit] })
+```
+
+## API Reference
+
+| Function                                          | Description                                                                |
+| ------------------------------------------------- | -------------------------------------------------------------------------- |
+| `createEndpoint(method, route, handler, config?)` | Define a type-safe endpoint with optional validation and middlewares.      |
+| `createEndpointConfig(config)`                    | Helper that preserves Zod inference for endpoint schemas.                  |
+| `createRouter(endpoints, config?)`                | Build a router that dispatches native Fetch requests to the right handler. |

package/dist/assert.cjs

@@ -0,0 +1,50 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/assert.ts
+var assert_exports = {};
+__export(assert_exports, {
+  isSupportedBodyMethod: () => isSupportedBodyMethod,
+  isSupportedMethod: () => isSupportedMethod,
+  isValidHandler: () => isValidHandler,
+  isValidRoute: () => isValidRoute
+});
+module.exports = __toCommonJS(assert_exports);
+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";
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isSupportedBodyMethod,
+  isSupportedMethod,
+  isValidHandler,
+  isValidRoute
+});

package/dist/assert.d.cts

@@ -0,0 +1,32 @@
+import { HTTPMethod, RoutePattern, RouteHandler } from './types.cjs';
+import 'zod';
+
+/**
+ * Checks if the provided method is a supported HTTP method.
+ *
+ * @param method - The HTTP method to check.
+ * @returns True if the method is supported, false otherwise.
+ */
+declare const isSupportedMethod: (method: string) => method is HTTPMethod;
+/**
+ * Check if the provided method can includes a body as per HTTP specification.
+ * @param method - The HTTP method to check.
+ * @returns True if the method can include a body, false otherwise.
+ */
+declare const isSupportedBodyMethod: (method: string) => method is HTTPMethod;
+/**
+ * Checks if the provided route is a valid route pattern.
+ *
+ * @param route - The route pattern to check.
+ * @returns True if the route is valid, false otherwise.
+ */
+declare const isValidRoute: (route: string) => route is RoutePattern;
+/**
+ * Checks if the provided handler is a valid route handler function.
+ *
+ * @param handler - The handler to check.
+ * @returns True if the handler is valid, false otherwise.
+ */
+declare const isValidHandler: (handler: unknown) => handler is RouteHandler<any, any>;
+
+export { isSupportedBodyMethod, isSupportedMethod, isValidHandler, isValidRoute };

package/dist/assert.d.ts

@@ -0,0 +1,32 @@
+import { HTTPMethod, RoutePattern, RouteHandler } from './types.js';
+import 'zod';
+
+/**
+ * Checks if the provided method is a supported HTTP method.
+ *
+ * @param method - The HTTP method to check.
+ * @returns True if the method is supported, false otherwise.
+ */
+declare const isSupportedMethod: (method: string) => method is HTTPMethod;
+/**
+ * Check if the provided method can includes a body as per HTTP specification.
+ * @param method - The HTTP method to check.
+ * @returns True if the method can include a body, false otherwise.
+ */
+declare const isSupportedBodyMethod: (method: string) => method is HTTPMethod;
+/**
+ * Checks if the provided route is a valid route pattern.
+ *
+ * @param route - The route pattern to check.
+ * @returns True if the route is valid, false otherwise.
+ */
+declare const isValidRoute: (route: string) => route is RoutePattern;
+/**
+ * Checks if the provided handler is a valid route handler function.
+ *
+ * @param handler - The handler to check.
+ * @returns True if the handler is valid, false otherwise.
+ */
+declare const isValidHandler: (handler: unknown) => handler is RouteHandler<any, any>;
+
+export { isSupportedBodyMethod, isSupportedMethod, isValidHandler, isValidRoute };

package/dist/assert.js

@@ -0,0 +1,12 @@
+import {
+  isSupportedBodyMethod,
+  isSupportedMethod,
+  isValidHandler,
+  isValidRoute
+} from "./chunk-ENOBC3XN.js";
+export {
+  isSupportedBodyMethod,
+  isSupportedMethod,
+  isValidHandler,
+  isValidRoute
+};

package/dist/chunk-6UBPSXKR.js

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,23 @@
+// 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

@@ -0,0 +1,78 @@
+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-RFYOPPMW.js

@@ -0,0 +1,45 @@
+// 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.entries(statusCode).reduce(
+  (previous, [status, code]) => {
+    return { ...previous, [code]: status };
+  },
+  {}
+);
+var AuraStackRouterError = class extends Error {
+  constructor(type, message, name) {
+    super(message);
+    this.name = name ?? "AuraStackRouterError";
+    this.status = statusCode[type];
+    this.statusText = statusText[this.status];
+  }
+};
+
+export {
+  AuraStackRouterError
+};

package/dist/chunk-RVJ2F7OL.js

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

package/dist/chunk-VBI7H3AK.js

@@ -0,0 +1,75 @@
+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
+};