@kaito-http/core 3.0.1 → 4.0.0-beta.1

package/dist/cors/cors.cjs

@@ -0,0 +1,60 @@
+"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/cors/cors.ts
+var cors_exports = {};
+__export(cors_exports, {
+  experimental_createCORSTransform: () => experimental_createCORSTransform,
+  experimental_createOriginMatcher: () => experimental_createOriginMatcher
+});
+module.exports = __toCommonJS(cors_exports);
+function experimental_createOriginMatcher(origins) {
+  if (origins.length === 0) {
+    return () => false;
+  }
+  const source = origins.map((origin) => {
+    if (origin.startsWith("*.")) {
+      const escapedDomain = origin.slice(2).replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+      return `^(?:https?://)[^.]+\\.${escapedDomain}$`;
+    } else {
+      const escapedOrigin = origin.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+      return `^${escapedOrigin}$`;
+    }
+  }).join("|");
+  const regex = new RegExp(source);
+  return (origin) => regex.test(origin);
+}
+function experimental_createCORSTransform(origins) {
+  const matcher = experimental_createOriginMatcher(origins);
+  return (request, response) => {
+    const origin = request.headers.get("Origin");
+    if (origin && matcher(origin)) {
+      response.headers.set("Access-Control-Allow-Origin", origin);
+      response.headers.set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+      response.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
+      response.headers.set("Access-Control-Max-Age", "86400");
+      response.headers.set("Access-Control-Allow-Credentials", "true");
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  experimental_createCORSTransform,
+  experimental_createOriginMatcher
+});

package/dist/cors/cors.d.cts

@@ -0,0 +1,55 @@
+/**
+ * Creates a function that matches origins against a predefined set of patterns, supporting wildcards.
+ * The matcher handles both exact matches and wildcard subdomain patterns (e.g., '*.example.com').
+ *
+ * **⚠️ This API is experimental and may change or even be removed in the future. ⚠️**
+ *
+ * @param origins Array of origin patterns to match against.
+ * Patterns can be exact origins (e.g., 'https://example.com') or wildcard patterns (e.g., '*.example.com') that match subdomains.
+ * @returns A function that tests if an origin matches any of the patterns
+ *
+ * @example
+ * ```typescript
+ * const allowedOrigins = [
+ *   'https://example.com',
+ *   '*.trusted-domain.com' // Won't match https://evil-domain.com, only subdomains
+ * ];
+ *
+ * const matcher = createOriginMatcher(allowedOrigins);
+ *
+ * // Exact match
+ * console.log(matcher('https://example.com')); // true
+ * console.log(matcher('http://example.com')); // false
+ *
+ * // Wildcard subdomain matches
+ * console.log(matcher('https://app.trusted-domain.com')); // true
+ * console.log(matcher('https://staging.trusted-domain.com')); // true
+ * console.log(matcher('https://trusted-domain.com')); // false, because it's not a subdomain
+ * console.log(matcher('https://evil-domain.com')); // false
+ * ```
+ */
+declare function experimental_createOriginMatcher(origins: string[]): (origin: string) => boolean;
+/**
+ * Create a function to apply CORS headers with sane defaults for most apps.
+ *
+ * **⚠️ This API is experimental and may change or even be removed in the future. ⚠️**
+ *
+ * @param options Options object
+ * @returns A function that will mutate the Response object by applying the CORS headers
+ * @example
+ * ```ts
+ * const cors = createCORSHandler({
+ *   origins: ['https://example.com', "*.allows-subdomains.com", "http://localhost:3000"],
+ * });
+ *
+ * const handler = createKaitoHandler({
+ *  // ...
+ *  transform: async (request, response) => {
+ *    cors(request, response);
+ *  }
+ * });
+ * ```
+ */
+declare function experimental_createCORSTransform(origins: string[]): (request: Request, response: Response) => void;
+
+export { experimental_createCORSTransform, experimental_createOriginMatcher };

package/dist/cors/cors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Creates a function that matches origins against a predefined set of patterns, supporting wildcards.
+ * The matcher handles both exact matches and wildcard subdomain patterns (e.g., '*.example.com').
+ *
+ * **⚠️ This API is experimental and may change or even be removed in the future. ⚠️**
+ *
+ * @param origins Array of origin patterns to match against.
+ * Patterns can be exact origins (e.g., 'https://example.com') or wildcard patterns (e.g., '*.example.com') that match subdomains.
+ * @returns A function that tests if an origin matches any of the patterns
+ *
+ * @example
+ * ```typescript
+ * const allowedOrigins = [
+ *   'https://example.com',
+ *   '*.trusted-domain.com' // Won't match https://evil-domain.com, only subdomains
+ * ];
+ *
+ * const matcher = createOriginMatcher(allowedOrigins);
+ *
+ * // Exact match
+ * console.log(matcher('https://example.com')); // true
+ * console.log(matcher('http://example.com')); // false
+ *
+ * // Wildcard subdomain matches
+ * console.log(matcher('https://app.trusted-domain.com')); // true
+ * console.log(matcher('https://staging.trusted-domain.com')); // true
+ * console.log(matcher('https://trusted-domain.com')); // false, because it's not a subdomain
+ * console.log(matcher('https://evil-domain.com')); // false
+ * ```
+ */
+declare function experimental_createOriginMatcher(origins: string[]): (origin: string) => boolean;
+/**
+ * Create a function to apply CORS headers with sane defaults for most apps.
+ *
+ * **⚠️ This API is experimental and may change or even be removed in the future. ⚠️**
+ *
+ * @param options Options object
+ * @returns A function that will mutate the Response object by applying the CORS headers
+ * @example
+ * ```ts
+ * const cors = createCORSHandler({
+ *   origins: ['https://example.com', "*.allows-subdomains.com", "http://localhost:3000"],
+ * });
+ *
+ * const handler = createKaitoHandler({
+ *  // ...
+ *  transform: async (request, response) => {
+ *    cors(request, response);
+ *  }
+ * });
+ * ```
+ */
+declare function experimental_createCORSTransform(origins: string[]): (request: Request, response: Response) => void;
+
+export { experimental_createCORSTransform, experimental_createOriginMatcher };

package/dist/cors/cors.js

@@ -0,0 +1,34 @@
+// src/cors/cors.ts
+function experimental_createOriginMatcher(origins) {
+  if (origins.length === 0) {
+    return () => false;
+  }
+  const source = origins.map((origin) => {
+    if (origin.startsWith("*.")) {
+      const escapedDomain = origin.slice(2).replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+      return `^(?:https?://)[^.]+\\.${escapedDomain}$`;
+    } else {
+      const escapedOrigin = origin.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+      return `^${escapedOrigin}$`;
+    }
+  }).join("|");
+  const regex = new RegExp(source);
+  return (origin) => regex.test(origin);
+}
+function experimental_createCORSTransform(origins) {
+  const matcher = experimental_createOriginMatcher(origins);
+  return (request, response) => {
+    const origin = request.headers.get("Origin");
+    if (origin && matcher(origin)) {
+      response.headers.set("Access-Control-Allow-Origin", origin);
+      response.headers.set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+      response.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
+      response.headers.set("Access-Control-Max-Age", "86400");
+      response.headers.set("Access-Control-Allow-Credentials", "true");
+    }
+  };
+}
+export {
+  experimental_createCORSTransform,
+  experimental_createOriginMatcher
+};

package/dist/index.cjs

@@ -24,19 +24,17 @@ __export(index_exports, {
   KaitoRequest: () => KaitoRequest,
   Router: () => Router,
   WrappedError: () => WrappedError,
-  createKaitoHandler: () => createKaitoHandler,
-  createUtilities: () => createUtilities,
-  isNodeLikeDev: () => isNodeLikeDev,
-  parsable: () => parsable
+  create: () => create,
+  isNodeLikeDev: () => isNodeLikeDev
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/router/router.ts
+var import_zod = require("zod");
+var import_zod_openapi = require("zod-openapi");
+
 // src/error.ts
 var WrappedError = class _WrappedError extends Error {
-  constructor(data) {
-    super("Something was thrown, but it was not an instance of Error, so a WrappedError was created.");
-    this.data = data;
-  }
   static maybe(maybeError) {
     if (maybeError instanceof Error) {
       return maybeError;
@@ -46,36 +44,62 @@ var WrappedError = class _WrappedError extends Error {
   static from(data) {
     return new _WrappedError(data);
   }
+  data;
+  constructor(data) {
+    super("Something was thrown, but it was not an instance of Error, so a WrappedError was created.");
+    this.data = data;
+  }
 };
 var KaitoError = class extends Error {
+  status;
   constructor(status, message) {
     super(message);
     this.status = status;
   }
 };
 
-// src/handler.ts
-function createKaitoHandler(config) {
-  const handle = config.router.freeze(config);
-  return async (request) => {
-    if (config.before) {
-      const result = await config.before(request);
-      if (result instanceof Response) {
-        if (config.transform) {
-          const result2 = await config.transform(request, result);
-          if (result2 instanceof Response) return result;
-        }
-        return result;
-      }
+// src/head.ts
+var KaitoHead = class {
+  #headers;
+  #status;
+  constructor() {
+    this.#headers = null;
+    this.#status = 200;
+  }
+  get headers() {
+    if (this.#headers === null) {
+      this.#headers = new Headers();
     }
-    const response = await handle(request);
-    if (config.transform) {
-      const result = await config.transform(request, response);
-      if (result instanceof Response) return result;
+    return this.#headers;
+  }
+  status(status) {
+    if (status === void 0) {
+      return this.#status;
     }
-    return response;
-  };
-}
+    this.#status = status;
+    return this;
+  }
+  /**
+   * Turn this KaitoHead instance into a Response instance
+   * @param body The Kaito JSON format to be sent as the response body
+   * @returns A Response instance, ready to be sent
+   */
+  toResponse(body) {
+    const init = {
+      status: this.#status
+    };
+    if (this.#headers) {
+      init.headers = this.#headers;
+    }
+    return Response.json(body, init);
+  }
+  /**
+   * Whether this KaitoHead instance has been touched/modified
+   */
+  get touched() {
+    return this.#status !== 200 || this.#headers !== null;
+  }
+};
 
 // src/request.ts
 var KaitoRequest = class {
@@ -115,91 +139,25 @@ var KaitoRequest = class {
   }
 };
 
-// src/head.ts
-var KaitoHead = class {
-  _headers;
-  _status;
-  constructor() {
-    this._headers = null;
-    this._status = 200;
-  }
-  get headers() {
-    if (this._headers === null) {
-      this._headers = new Headers();
-    }
-    return this._headers;
-  }
-  status(status) {
-    if (status === void 0) {
-      return this._status;
-    }
-    this._status = status;
-    return this;
-  }
-  /**
-   * Turn this KaitoHead instance into a Response instance
-   * @param body The Kaito JSON format to be sent as the response body
-   * @returns A Response instance, ready to be sent
-   */
-  toResponse(body) {
-    const init = {
-      status: this._status
-    };
-    if (this._headers) {
-      init.headers = this._headers;
-    }
-    return Response.json(body, init);
-  }
-  /**
-   * Whether this KaitoHead instance has been touched/modified
-   */
-  get touched() {
-    return this._status !== 200 || this._headers !== null;
-  }
-};
-
 // src/util.ts
 var isNodeLikeDev = typeof process !== "undefined" && typeof process.env !== "undefined" && process.env.NODE_ENV === "development";
-function createUtilities(getContext) {
-  return {
-    getContext,
-    router: () => Router.create()
-  };
-}
-function parsable(parse) {
-  return {
-    parse
-  };
-}
 
 // src/router/router.ts
 var Router = class _Router {
   state;
-  static create = () => new _Router({
+  static create = (config) => new _Router({
     through: async (context) => context,
-    routes: /* @__PURE__ */ new Set()
+    routes: /* @__PURE__ */ new Set(),
+    config
   });
-  static parseQuery(schema, url) {
-    if (!schema) {
-      return {};
-    }
-    const result = {};
-    for (const key in schema) {
-      if (!schema.hasOwnProperty(key)) continue;
-      const value = url.searchParams.get(key);
-      result[key] = schema[key].parse(value);
-    }
-    return result;
-  }
-  constructor(options) {
-    this.state = options;
+  constructor(state) {
+    this.state = state;
   }
   get routes() {
     return this.state.routes;
   }
   add = (method, path, route) => {
     const merged = {
-      // TODO: Ideally fix the typing here, but this will be replaced in Kaito v4 where all routes must return a Response (which we can type)
       ...typeof route === "object" ? route : { run: route },
       method,
       path,
@@ -220,39 +178,54 @@ var Router = class _Router {
       routes: /* @__PURE__ */ new Set([...this.state.routes, ...newRoutes])
     });
   };
-  freeze = (server) => {
-    const routes = /* @__PURE__ */ new Map();
-    for (const route of this.state.routes) {
-      if (!routes.has(route.path)) {
-        routes.set(route.path, /* @__PURE__ */ new Map());
+  static getFindRoute = (routes) => (method, path) => {
+    const params = {};
+    const pathParts = path.split("/").filter(Boolean);
+    const methodRoutes = routes.get(method);
+    if (!methodRoutes) return {};
+    for (const [routePath, route] of methodRoutes) {
+      const routeParts = routePath.split("/").filter(Boolean);
+      if (routeParts.length !== pathParts.length) {
+        continue;
       }
-      routes.get(route.path).set(route.method, route);
-    }
-    const findRoute = (method, path) => {
-      const params = {};
-      const pathParts = path.split("/").filter(Boolean);
-      for (const [routePath, methodHandlers] of routes) {
-        const routeParts = routePath.split("/").filter(Boolean);
-        if (routeParts.length !== pathParts.length) continue;
-        let matches = true;
-        for (let i = 0; i < routeParts.length; i++) {
-          const routePart = routeParts[i];
-          const pathPart = pathParts[i];
-          if (routePart && pathPart && routePart.startsWith(":")) {
-            params[routePart.slice(1)] = pathPart;
-          } else if (routePart !== pathPart) {
-            matches = false;
-            break;
-          }
-        }
-        if (matches) {
-          const route = methodHandlers.get(method);
-          if (route) return { route, params };
+      let matches = true;
+      for (let i = 0; i < routeParts.length; i++) {
+        const routePart = routeParts[i];
+        const pathPart = pathParts[i];
+        if (routePart && pathPart && routePart.startsWith(":")) {
+          params[routePart.slice(1)] = pathPart;
+        } else if (routePart !== pathPart) {
+          matches = false;
+          break;
         }
       }
-      return { params };
-    };
-    return async (req) => {
+      if (matches) return { route, params };
+    }
+    return {};
+  };
+  static buildQuerySchema = (schema) => {
+    const keys = Object.keys(schema);
+    return import_zod.z.instanceof(URLSearchParams).transform((params) => {
+      const result = {};
+      for (const key of keys) {
+        result[key] = params.get(key);
+      }
+      return result;
+    }).pipe(import_zod.z.object(schema));
+  };
+  serve = () => {
+    const methodToRoutesMap = /* @__PURE__ */ new Map();
+    for (const route of this.state.routes) {
+      if (!methodToRoutesMap.has(route.method)) {
+        methodToRoutesMap.set(route.method, /* @__PURE__ */ new Map());
+      }
+      methodToRoutesMap.get(route.method).set(route.path, {
+        ...route,
+        fastQuerySchema: route.query ? _Router.buildQuerySchema(route.query) : void 0
+      });
+    }
+    const findRoute = _Router.getFindRoute(methodToRoutesMap);
+    const handle = async (req) => {
       const url = new URL(req.url);
       const method = req.method;
       const { route, params } = findRoute(method, url.pathname);
@@ -267,10 +240,9 @@ var Router = class _Router {
       const request = new KaitoRequest(url, req);
       const head = new KaitoHead();
       try {
-        const body = route.body ? await route.body.parse(await req.json()) : void 0;
-        const query = _Router.parseQuery(route.query, url);
-        const rootCtx = await server.getContext(request, head);
-        const ctx = await route.through(rootCtx);
+        const body = route.body ? await route.body.parseAsync(await req.json()) : void 0;
+        const query = route.fastQuerySchema ? await route.fastQuerySchema.parseAsync(url.searchParams) : {};
+        const ctx = await route.through(await this.state.config.getContext?.(request, head) ?? null);
         const result = await route.run({
           ctx,
           body,
@@ -293,8 +265,7 @@ var Router = class _Router {
         }
         return head.toResponse({
           success: true,
-          data: result,
-          message: "OK"
+          data: result
         });
       } catch (e) {
         const error = WrappedError.maybe(e);
@@ -305,15 +276,115 @@ var Router = class _Router {
             message: error.message
           });
         }
-        const { status, message } = await server.onError({ error, req: request }).catch(() => ({ status: 500, message: "Internal Server Error" }));
-        return head.status(status).toResponse({
-          success: false,
-          data: null,
-          message
-        });
+        if (!this.state.config.onError) {
+          return head.status(500).toResponse({
+            success: false,
+            data: null,
+            message: "Internal Server Error"
+          });
+        }
+        try {
+          const { status, message } = await this.state.config.onError(error, request);
+          return head.status(status).toResponse({
+            success: false,
+            data: null,
+            message
+          });
+        } catch (e2) {
+          console.error("KAITO - Failed to handle error inside `.onError()`, returning 500 and Internal Server Error");
+          console.error(e2);
+          return head.status(500).toResponse({
+            success: false,
+            data: null,
+            message: "Internal Server Error"
+          });
+        }
+      }
+    };
+    return async (request) => {
+      if (this.state.config.before) {
+        const result = await this.state.config.before(request);
+        if (result instanceof Response) {
+          if (this.state.config.transform) {
+            const transformed = await this.state.config.transform(request, result);
+            if (transformed instanceof Response) {
+              return result;
+            }
+          }
+          return result;
+        }
+      }
+      const response = await handle(request);
+      if (this.state.config.transform) {
+        const transformed = await this.state.config.transform(request, response);
+        if (transformed instanceof Response) {
+          return transformed;
+        }
       }
+      return response;
     };
   };
+  openapi = (highLevelSpec) => {
+    const OPENAPI_VERSION = "3.0.0";
+    const paths = {};
+    for (const route of this.state.routes) {
+      const path = route.path;
+      const pathWithColonParamsReplaceWithCurlyBraces = path.replace(/:(\w+)/g, "{$1}");
+      if (!paths[pathWithColonParamsReplaceWithCurlyBraces]) {
+        paths[pathWithColonParamsReplaceWithCurlyBraces] = {};
+      }
+      const item = {
+        description: route.openapi?.description ?? "Successful response",
+        responses: {
+          200: {
+            description: route.openapi?.description ?? "Successful response",
+            ...route.openapi ? {
+              content: {
+                [{
+                  json: "application/json",
+                  sse: "text/event-stream"
+                }[route.openapi.body.type]]: { schema: route.openapi?.body.schema }
+              }
+            } : {}
+          }
+        }
+      };
+      if (route.body) {
+        item.requestBody = {
+          content: {
+            "application/json": { schema: route.body }
+          }
+        };
+      }
+      const params = {};
+      if (route.query) {
+        params.query = import_zod.z.object(route.query);
+      }
+      const urlParams = path.match(/:(\w+)/g);
+      if (urlParams) {
+        const pathParams = {};
+        for (const param of urlParams) {
+          pathParams[param.slice(1)] = import_zod.z.string();
+        }
+        params.path = import_zod.z.object(pathParams);
+      }
+      item.requestParams = params;
+      paths[pathWithColonParamsReplaceWithCurlyBraces][route.method.toLowerCase()] = item;
+    }
+    const doc = (0, import_zod_openapi.createDocument)({
+      openapi: OPENAPI_VERSION,
+      paths,
+      ...highLevelSpec,
+      servers: Object.entries(highLevelSpec.servers ?? {}).map((entry) => {
+        const [url, description] = entry;
+        return {
+          url,
+          description
+        };
+      })
+    });
+    return this.add("GET", "/openapi.json", async () => Response.json(doc));
+  };
   method = (method) => (path, route) => {
     return this.add(method, path, route);
   };
@@ -327,18 +398,21 @@ var Router = class _Router {
   through = (through) => {
     return new _Router({
       ...this.state,
-      through: async (context) => through(await this.state.through(context))
+      through: async (context) => await through(await this.state.through(context))
     });
   };
 };
+
+// src/create.ts
+function create(config = {}) {
+  return () => Router.create(config);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   KaitoError,
   KaitoRequest,
   Router,
   WrappedError,
-  createKaitoHandler,
-  createUtilities,
-  isNodeLikeDev,
-  parsable
+  create,
+  isNodeLikeDev
 });