@axeom/core 0.1.1

package/dist/index.cjs

@@ -0,0 +1,804 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  $SERVER: () => $SERVER,
+  Axeom: () => Axeom,
+  AxeomError: () => AxeomError,
+  BadRequestError: () => BadRequestError,
+  ConflictError: () => ConflictError,
+  ForbiddenError: () => ForbiddenError,
+  InternalServerError: () => InternalServerError,
+  NotFoundError: () => NotFoundError,
+  UnauthorizedError: () => UnauthorizedError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var AxeomError = class extends Error {
+  constructor(message, status = 500, code = "INTERNAL_SERVER_ERROR", details) {
+    super(message);
+    this.message = message;
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.name = this.constructor.name;
+  }
+};
+var NotFoundError = class extends AxeomError {
+  constructor(message = "Resource not found", details) {
+    super(message, 404, "NOT_FOUND", details);
+  }
+};
+var UnauthorizedError = class extends AxeomError {
+  constructor(message = "Unauthorized access", details) {
+    super(message, 401, "UNAUTHORIZED", details);
+  }
+};
+var BadRequestError = class extends AxeomError {
+  constructor(message = "Bad request", details) {
+    super(message, 400, "BAD_REQUEST", details);
+  }
+};
+var ForbiddenError = class extends AxeomError {
+  constructor(message = "Forbidden", details) {
+    super(message, 403, "FORBIDDEN", details);
+  }
+};
+var InternalServerError = class extends AxeomError {
+  constructor(message = "Internal server error") {
+    super(message, 500, "INTERNAL_SERVER_ERROR");
+  }
+};
+var ConflictError = class extends AxeomError {
+  constructor(message = "Conflict", details) {
+    super(message, 409, "CONFLICT", details);
+  }
+};
+
+// src/hooks.ts
+var Hooks = class {
+  onRequests = [];
+  onBeforeMatch = [];
+  onResponses = [];
+  beforeHandles = [];
+  afterHandles = [];
+  addRequestHook(fn) {
+    this.onRequests.push(fn);
+  }
+  addBeforeMatchHook(fn) {
+    this.onBeforeMatch.push(fn);
+  }
+  addResponseHook(fn) {
+    this.onResponses.push(fn);
+  }
+  addBeforeHandleHook(fn) {
+    this.beforeHandles.push(fn);
+  }
+  addAfterHandleHook(fn) {
+    this.afterHandles.push(fn);
+  }
+  getState() {
+    return {
+      onRequests: this.onRequests,
+      onBeforeMatch: this.onBeforeMatch,
+      onResponses: this.onResponses,
+      beforeHandles: this.beforeHandles,
+      afterHandles: this.afterHandles
+    };
+  }
+  setState(state) {
+    this.onRequests = [...state.onRequests];
+    this.onBeforeMatch = [...state.onBeforeMatch || []];
+    this.onResponses = [...state.onResponses];
+    this.beforeHandles = [...state.beforeHandles];
+    this.afterHandles = [...state.afterHandles];
+  }
+};
+
+// src/radix.ts
+var RadixNode = class _RadixNode {
+  part;
+  children = /* @__PURE__ */ new Map();
+  wildcardChild = null;
+  catchAllChild = null;
+  paramName = null;
+  handlers = /* @__PURE__ */ new Map();
+  constructor(part = "", paramName = null) {
+    this.part = part;
+    this.paramName = paramName;
+  }
+  insert(segments, method, route, index = 0) {
+    if (index === segments.length) {
+      this.handlers.set(method, route);
+      return;
+    }
+    const currentSegment = segments[index];
+    if (currentSegment === "*") {
+      if (!this.catchAllChild) {
+        this.catchAllChild = new _RadixNode("*");
+      }
+      this.catchAllChild.handlers.set(method, route);
+      return;
+    }
+    const isWildcard = currentSegment.startsWith(":");
+    if (isWildcard) {
+      const paramName = currentSegment.slice(1);
+      if (!this.wildcardChild) {
+        this.wildcardChild = new _RadixNode(currentSegment, paramName);
+      }
+      this.wildcardChild.insert(segments, method, route, index + 1);
+    } else {
+      if (!this.children.has(currentSegment)) {
+        this.children.set(currentSegment, new _RadixNode(currentSegment));
+      }
+      this.children.get(currentSegment).insert(segments, method, route, index + 1);
+    }
+  }
+  search(segments, method, index = 0, params = {}) {
+    if (index === segments.length) {
+      const route = this.handlers.get(method);
+      if (route) return { route, params };
+      if (this.catchAllChild) {
+        const caRoute = this.catchAllChild.handlers.get(method);
+        if (caRoute) {
+          params["*"] = "";
+          return { route: caRoute, params };
+        }
+      }
+      return null;
+    }
+    const currentSegment = segments[index];
+    const child = this.children.get(currentSegment);
+    if (child) {
+      const result = child.search(segments, method, index + 1, params);
+      if (result) return result;
+    }
+    if (this.wildcardChild && this.wildcardChild.paramName) {
+      const newParams = {
+        ...params,
+        [this.wildcardChild.paramName]: currentSegment
+      };
+      const result = this.wildcardChild.search(
+        segments,
+        method,
+        index + 1,
+        newParams
+      );
+      if (result) return result;
+    }
+    if (this.catchAllChild) {
+      const route = this.catchAllChild.handlers.get(method);
+      if (route) {
+        params["*"] = segments.slice(index).join("/");
+        return { route, params };
+      }
+    }
+    return null;
+  }
+};
+var RadixTree = class {
+  root = new RadixNode("");
+  add(method, path, route) {
+    const segments = this.splitPath(path);
+    this.root.insert(segments, method.toUpperCase(), route);
+  }
+  match(method, path) {
+    const segments = this.splitPath(path);
+    return this.root.search(segments, method.toUpperCase());
+  }
+  splitPath(path) {
+    return path.split("/").filter(Boolean);
+  }
+};
+
+// src/utils.ts
+function createRegex(path, paramNames = []) {
+  const regexSource = path.replace(/\//g, "\\/").replace(/:([^/]+)/g, (_, name) => {
+    if (!paramNames.includes(name)) paramNames.push(name);
+    return "([^/]+)";
+  }).replace(/\*/g, () => {
+    if (!paramNames.includes("*")) paramNames.push("*");
+    return "(.*)";
+  });
+  return new RegExp(`^${regexSource}$`);
+}
+function formatValidationError(error) {
+  const issues = error.issues || [];
+  if (Array.isArray(issues) && issues.length > 0) {
+    return issues.map((issue) => ({
+      path: issue.path,
+      message: issue.message,
+      code: issue.code,
+      metadata: issue.expected ? {
+        expected: issue.expected,
+        received: issue.received
+      } : void 0
+    }));
+  }
+  return [
+    {
+      path: ["_form"],
+      message: error.message || "Unknown validation error",
+      code: "custom"
+    }
+  ];
+}
+
+// src/router.ts
+var Router = class {
+  tree = new RadixTree();
+  routes = [];
+  /**
+   * Registers a new route with its associated state (hooks, derivations, and decorators).
+   */
+  add(method, path, handler, state, schema, metadata) {
+    const paramNames = [];
+    const route = {
+      method,
+      path,
+      regex: createRegex(path, paramNames),
+      handler,
+      paramNames,
+      schema,
+      metadata,
+      derives: [...state.derives],
+      decorators: { ...state.decorators },
+      onRequests: [...state.onRequests],
+      onResponses: [...state.onResponses],
+      beforeHandles: [...state.beforeHandles],
+      afterHandles: [...state.afterHandles]
+    };
+    this.routes.push(route);
+    this.tree.add(method, path, route);
+    return route;
+  }
+  /**
+   * Finds a matching route for the given method and pathname.
+   */
+  match(method, pathname) {
+    const result = this.tree.match(method, pathname);
+    if (!result) return null;
+    const { route, params } = result;
+    const matchArray = [pathname];
+    route.paramNames.forEach((name) => {
+      matchArray.push(params[name]);
+    });
+    return { route, match: matchArray };
+  }
+  addRoute(route) {
+    this.routes.push(route);
+    this.tree.add(route.method, route.path, route);
+  }
+  getRoutes() {
+    return this.routes;
+  }
+  setRoutes(routes) {
+    this.routes = routes;
+    this.tree = new RadixTree();
+    routes.forEach((r) => this.tree.add(r.method, r.path, r));
+  }
+};
+
+// src/index.ts
+var $SERVER = /* @__PURE__ */ Symbol("Axeom:server");
+var InternalContext = class {
+  params = {};
+  query = {};
+  request;
+  time;
+  body = void 0;
+  _responseHeaders;
+  _server;
+  constructor(request, server, startTime, decorators) {
+    this.request = request;
+    this._server = server;
+    this.time = startTime;
+    this._responseHeaders = {};
+    this.setResponseHeader = this.setResponseHeader.bind(this);
+    this.getResponseHeaders = this.getResponseHeaders.bind(this);
+    this.setDuration = this.setDuration.bind(this);
+    Object.assign(this, decorators);
+  }
+  get headers() {
+    return this.request.headers;
+  }
+  setDuration(label) {
+    return performance.now() - this.time;
+  }
+  setResponseHeader(name, value) {
+    this._responseHeaders[name] = value;
+  }
+  getResponseHeaders() {
+    return this._responseHeaders;
+  }
+};
+var Axeom = class _Axeom {
+  router = new Router();
+  hooks = new Hooks();
+  server;
+  derives = [];
+  decorators = {
+    logger: {
+      info: () => {
+      },
+      error: () => {
+      },
+      warn: () => {
+      },
+      debug: () => {
+      }
+    },
+    error: {
+      NotFound: (msg) => {
+        throw new NotFoundError(msg);
+      },
+      Unauthorized: (msg) => {
+        throw new UnauthorizedError(msg);
+      },
+      BadRequest: (msg) => {
+        throw new BadRequestError(msg);
+      },
+      Forbidden: (msg) => {
+        throw new ForbiddenError(msg);
+      },
+      Conflict: (msg) => {
+        throw new ConflictError(msg);
+      }
+    }
+  };
+  errorHandler = (error) => {
+    if (error instanceof AxeomError) {
+      return {
+        status: "error",
+        code: error.code,
+        message: error.message,
+        details: error.details
+      };
+    }
+    console.error(error);
+    return { status: "error", message: "Internal Server Error" };
+  };
+  /**
+   * Adds dynamic properties to the context by running a function before the route handler.
+   * Derivations can be asynchronous and can return a Response to short-circuit the request.
+   *
+   * @param fn - A function that receives the current context and returns new properties to merge.
+   */
+  derive(fn) {
+    this.derives.push(fn);
+    return this;
+  }
+  /**
+   * Registers a plugin.
+   * Plugins are functions that receive the Axeom instance and can register routes,
+   * hooks, or decorators.
+   *
+   * @param plugin - The plugin function to execute.
+   */
+  use(plugin) {
+    return plugin(this);
+  }
+  /**
+   * Groups routes under a common path prefix.
+   * This provides isolation for derivations and hooks within the group.
+   *
+   * @param prefix - The path prefix (e.g., "/api/v1").
+   * @param run - A function where you define the routes for this group.
+   */
+  group(prefix, run) {
+    const branch = new _Axeom();
+    branch.derives = [...this.derives];
+    branch.decorators = { ...this.decorators };
+    branch.hooks.setState(this.hooks.getState());
+    const result = run(branch);
+    result.router.getRoutes().forEach((route) => {
+      const fullPath = `${prefix}${route.path}`.replace(/\/+/g, "/");
+      const paramNames = [];
+      this.router.addRoute({
+        ...route,
+        path: fullPath,
+        regex: createRegex(fullPath, paramNames),
+        paramNames
+      });
+    });
+    return this;
+  }
+  /**
+   * Adds static properties to the context.
+   * Decorators are available on every request context immediately.
+   *
+   * @param obj - An object containing properties to add to the context.
+   */
+  decorate(obj) {
+    this.decorators = { ...this.decorators, ...obj };
+    return this;
+  }
+  addRoute(method, path, handler, schema, metadata) {
+    this.router.add(
+      method,
+      path,
+      handler,
+      {
+        derives: this.derives,
+        decorators: this.decorators,
+        ...this.hooks.getState()
+      },
+      schema,
+      metadata
+    );
+    return this;
+  }
+  get(path, handler, schema) {
+    return this.addRoute("GET", path, handler, schema);
+  }
+  post(path, handler, schema) {
+    return this.addRoute("POST", path, handler, schema);
+  }
+  put(path, handler, schema) {
+    return this.addRoute("PUT", path, handler, schema);
+  }
+  patch(path, handler, schema) {
+    return this.addRoute("PATCH", path, handler, schema);
+  }
+  delete(path, handler, schema) {
+    return this.addRoute("DELETE", path, handler, schema);
+  }
+  /**
+   * Main entry point for handling requests.
+   *
+   * This is the standard WinterTC interface that converts a Request into a Response.
+   * It executes the entire request lifecycle including hooks, derivations, and validation.
+   *
+   * @param incomingRequest - The standard Web Request object.
+   * @param options - Optional runtime configuration (e.g. server instance).
+   * @returns A promise resolving to a standard Web Response object.
+   */
+  async handle(incomingRequest, options) {
+    const handshake = await this._handleHandshake(incomingRequest, options);
+    const { response } = handshake;
+    response._axeom_meta = handshake;
+    return response;
+  }
+  /**
+   * Internal method used by adapters to handle both HTTP and WebSocket handshakes.
+   * Returns the final response and the context used for the request.
+   */
+  async _handleHandshake(incomingRequest, options) {
+    const url = new URL(incomingRequest.url);
+    const { pathname } = url;
+    const method = incomingRequest.method;
+    const startTime = performance.now();
+    const server = options?.server || this.server;
+    const ctx = new InternalContext(
+      incomingRequest,
+      server,
+      startTime,
+      this.decorators
+    );
+    const finalizeResponse = async (res, currentCtx, routeHooks) => {
+      let finalRes = res;
+      const safeCtx = currentCtx || ctx;
+      const hooksToRun = routeHooks?.onResponses || this.hooks.onResponses;
+      if (hooksToRun && hooksToRun.length > 0) {
+        for (const onResponseFn of hooksToRun) {
+          const result = await onResponseFn(finalRes, safeCtx);
+          if (result instanceof Response) finalRes = result;
+        }
+      }
+      if (safeCtx && typeof safeCtx.getResponseHeaders === "function") {
+        const ctxHeaders = safeCtx.getResponseHeaders();
+        Object.entries(ctxHeaders).forEach(([name, value]) => {
+          finalRes.headers.set(name, value);
+        });
+      }
+      return finalRes;
+    };
+    if (this.hooks.onBeforeMatch.length > 0) {
+      for (const hook of this.hooks.onBeforeMatch) {
+        const result = await hook(incomingRequest);
+        if (result instanceof Response)
+          return { response: await finalizeResponse(result, ctx) };
+      }
+    }
+    const matched = this.router.match(method, pathname);
+    if (!matched) {
+      return {
+        response: await finalizeResponse(
+          new Response("Route not found", { status: 404 }),
+          ctx
+        )
+      };
+    }
+    const { route, match } = matched;
+    try {
+      const rawParams = {};
+      route.paramNames.forEach((name, index) => {
+        rawParams[name] = match[index + 1];
+      });
+      ctx.params = rawParams;
+      const queryStart = incomingRequest.url.indexOf("?");
+      ctx.query = queryStart === -1 ? {} : Object.fromEntries(
+        new URLSearchParams(
+          incomingRequest.url.slice(queryStart + 1)
+        ).entries()
+      );
+      if (method !== "GET" && method !== "HEAD") {
+        const contentType = incomingRequest.headers.get("content-type");
+        try {
+          if (contentType?.includes("application/json")) {
+            ctx.body = await incomingRequest.json();
+          } else if (contentType?.includes("multipart/form-data") || contentType?.includes("application/x-www-form-urlencoded")) {
+            ctx.body = await incomingRequest.formData();
+          }
+        } catch {
+          ctx.body = null;
+        }
+      }
+      if (route.derives && route.derives.length > 0) {
+        for (const deriveFn of route.derives) {
+          const result = await deriveFn(ctx);
+          if (result instanceof Response)
+            return {
+              response: await finalizeResponse(result, ctx, route),
+              context: ctx
+            };
+          if (result) Object.assign(ctx, result);
+        }
+      }
+      if (route.onRequests && route.onRequests.length > 0) {
+        for (const onRequestFn of route.onRequests) {
+          await onRequestFn(ctx);
+        }
+      }
+      if (route.beforeHandles && route.beforeHandles.length > 0) {
+        for (const hook of route.beforeHandles) {
+          const response2 = await hook(ctx);
+          if (response2 instanceof Response)
+            return {
+              response: await finalizeResponse(response2, ctx, route),
+              context: ctx
+            };
+        }
+      }
+      if (route.schema) {
+        try {
+          if (route.schema.params)
+            ctx.params = await route.schema.params.parse(ctx.params);
+          if (route.schema.query)
+            ctx.query = await route.schema.query.parse(ctx.query);
+          if (route.schema.body) {
+            if (ctx.body instanceof FormData) {
+              ctx.body = Object.fromEntries(ctx.body.entries());
+            }
+            ctx.body = await route.schema.body.parse(ctx.body);
+          }
+        } catch (e) {
+          const formattedErrors = formatValidationError(e);
+          return {
+            response: await finalizeResponse(
+              Response.json(
+                {
+                  code: "VALIDATION_FAILED",
+                  message: "Request validation failed",
+                  errors: formattedErrors
+                },
+                { status: 400 }
+              ),
+              ctx,
+              route
+            )
+          };
+        }
+      }
+      let response;
+      if (route.handler) {
+        response = await route.handler(ctx);
+      }
+      if (!(response instanceof Response)) {
+        response = Response.json(response);
+      }
+      if (route.afterHandles && route.afterHandles.length > 0) {
+        for (const hook of route.afterHandles) {
+          const result = await hook(ctx);
+          if (result instanceof Response)
+            return {
+              response: await finalizeResponse(result, ctx, route),
+              context: ctx
+            };
+        }
+      }
+      return {
+        response: await finalizeResponse(response, ctx, route),
+        context: ctx
+      };
+    } catch (error) {
+      const errorResponse = await this.errorHandler(error, ctx);
+      return {
+        response: await finalizeResponse(
+          Response.json(errorResponse, {
+            status: error?.status || 500
+          }),
+          ctx,
+          route
+        ),
+        context: ctx
+      };
+    }
+  }
+  /**
+   * Registers a global error handler.
+   */
+  onError(fn) {
+    this.errorHandler = fn;
+    return this;
+  }
+  /**
+   * Registers a global hook that runs as soon as a request is received.
+   */
+  onRequest(fn) {
+    this.hooks.addRequestHook(fn);
+    return this;
+  }
+  /**
+   * Registers a hook that runs before the router attempts to match a path.
+   * Useful for global redirects or early security checks.
+   */
+  onBeforeMatch(fn) {
+    this.hooks.addBeforeMatchHook(fn);
+    return this;
+  }
+  /**
+   * Registers a global hook that runs after a Response has been created.
+   * Allows modifying headers or the body before it's sent.
+   */
+  onResponse(fn) {
+    this.hooks.addResponseHook(fn);
+    return this;
+  }
+  /**
+   * Registers a hook that runs before the route handler is executed.
+   */
+  onBeforeHandle(fn) {
+    this.hooks.addBeforeHandleHook(fn);
+    return this;
+  }
+  /**
+   * Registers a hook that runs after the route handler is executed.
+   */
+  onAfterHandle(fn) {
+    this.hooks.addAfterHandleHook(fn);
+    return this;
+  }
+  /**
+   * Registers a Server-Sent Events (SSE) route.
+   *
+   * @param path - The path for the SSE stream.
+   * @param handler - A function returning an async iterable that yields data chunks.
+   */
+  sse(path, handler) {
+    return this.get(path, async (ctx) => {
+      if (ctx[$SERVER]?.timeout) {
+        ctx[$SERVER].timeout(ctx.request, 0);
+      }
+      const stream = await handler(ctx);
+      const readable = new ReadableStream({
+        async start(controller) {
+          for await (const chunk of stream) {
+            const data = typeof chunk === "string" ? chunk : JSON.stringify(chunk);
+            controller.enqueue(`data: ${data}
+
+`);
+          }
+          controller.close();
+        }
+      }).pipeThrough(new TextEncoderStream());
+      return new Response(readable, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive"
+        }
+      });
+    });
+  }
+  /**
+   * Automatically detect the runtime and start a server.
+   * Currently supports: Bun, Deno.
+   * For Node, use a specific adapter like @axeom/express.
+   *
+   * @param portOrOptions - The port number or a server options object.
+   */
+  listen(portOrOptions = 3e3) {
+    const options = typeof portOrOptions === "number" ? { port: portOrOptions } : portOrOptions || {};
+    const port = options.port || 3e3;
+    if (typeof Bun !== "undefined") {
+      this.server = Bun.serve({
+        ...options,
+        port,
+        fetch: async (req, server) => {
+          const res = await this.handle(req);
+          if (res.status === 101) {
+            const url = new URL(req.url);
+            const matched = this.router.match(req.method, url.pathname);
+            if (matched && matched.route.metadata?.ws) {
+              const success = server.upgrade(req, {
+                data: matched.route.metadata.ws
+              });
+              if (success) return void 0;
+            }
+          }
+          return res;
+        },
+        websocket: {
+          open: (ws) => ws.data.open?.(ws),
+          message: (ws, message) => ws.data.message?.(ws, message),
+          close: (ws, code, reason) => ws.data.close?.(ws, code, reason),
+          error: (ws, error) => ws.data.error?.(ws, error)
+        }
+      });
+      console.log(`\x1B[32m Axeom listening on ${this.server.url}\x1B[0m`);
+      return this.server;
+    }
+    if (typeof Deno !== "undefined" && typeof Deno.serve === "function") {
+      this.server = Deno.serve({ ...options, port }, async (req) => {
+        const res = await this.handle(req);
+        if (res.status === 101) {
+          const url = new URL(req.url);
+          const matched = this.router.match(req.method, url.pathname);
+          if (matched && matched.route.metadata?.ws) {
+            const { socket, response } = Deno.upgradeWebSocket(req);
+            const handlers = matched.route.metadata.ws;
+            socket.onopen = () => handlers.open?.(socket);
+            socket.onmessage = (e) => handlers.message?.(socket, e.data);
+            socket.onclose = () => handlers.close?.(socket);
+            socket.onerror = (e) => handlers.error?.(socket, e);
+            return response;
+          }
+        }
+        return res;
+      });
+      return this.server;
+    }
+    if (typeof process !== "undefined" && process.release?.name === "node") {
+      throw new Error(
+        "[Axeom] Automatic runtime detection found Node.js. Axeom requires a Fetch API compatible server. Please use @axeom/express for Node.js environments."
+      );
+    }
+    throw new Error(
+      "[Axeom] Automatic runtime detection failed. Ensure you are running in a supported environment (Bun, Deno) or use an adapter."
+    );
+  }
+};
+var index_default = Axeom;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  $SERVER,
+  Axeom,
+  AxeomError,
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  InternalServerError,
+  NotFoundError,
+  UnauthorizedError
+});