@kaito-http/core 3.0.0-beta.7 → 3.0.1

package/dist/index.cjs

@@ -0,0 +1,344 @@
+"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, {
+  KaitoError: () => KaitoError,
+  KaitoRequest: () => KaitoRequest,
+  Router: () => Router,
+  WrappedError: () => WrappedError,
+  createKaitoHandler: () => createKaitoHandler,
+  createUtilities: () => createUtilities,
+  isNodeLikeDev: () => isNodeLikeDev,
+  parsable: () => parsable
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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;
+    }
+    return _WrappedError.from(maybeError);
+  }
+  static from(data) {
+    return new _WrappedError(data);
+  }
+};
+var KaitoError = class extends Error {
+  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;
+      }
+    }
+    const response = await handle(request);
+    if (config.transform) {
+      const result = await config.transform(request, response);
+      if (result instanceof Response) return result;
+    }
+    return response;
+  };
+}
+
+// src/request.ts
+var KaitoRequest = class {
+  url;
+  _request;
+  constructor(url, request) {
+    this._request = request;
+    this.url = url;
+  }
+  get headers() {
+    return this._request.headers;
+  }
+  get method() {
+    return this._request.method;
+  }
+  async arrayBuffer() {
+    return this._request.arrayBuffer();
+  }
+  async blob() {
+    return this._request.blob();
+  }
+  async formData() {
+    return this._request.formData();
+  }
+  async bytes() {
+    const buffer = await this.arrayBuffer();
+    return new Uint8Array(buffer);
+  }
+  async json() {
+    return this._request.json();
+  }
+  async text() {
+    return this._request.text();
+  }
+  get request() {
+    return this._request;
+  }
+};
+
+// 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({
+    through: async (context) => context,
+    routes: /* @__PURE__ */ new Set()
+  });
+  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;
+  }
+  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,
+      through: this.state.through
+    };
+    return new _Router({
+      ...this.state,
+      routes: /* @__PURE__ */ new Set([...this.state.routes, merged])
+    });
+  };
+  merge = (pathPrefix, other) => {
+    const newRoutes = [...other.state.routes].map((route) => ({
+      ...route,
+      path: `${pathPrefix}${route.path}`
+    }));
+    return new _Router({
+      ...this.state,
+      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());
+      }
+      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 };
+        }
+      }
+      return { params };
+    };
+    return async (req) => {
+      const url = new URL(req.url);
+      const method = req.method;
+      const { route, params } = findRoute(method, url.pathname);
+      if (!route) {
+        const body = {
+          success: false,
+          data: null,
+          message: `Cannot ${method} ${url.pathname}`
+        };
+        return Response.json(body, { status: 404 });
+      }
+      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 result = await route.run({
+          ctx,
+          body,
+          query,
+          params
+        });
+        if (result instanceof Response) {
+          if (isNodeLikeDev) {
+            if (head.touched) {
+              const msg = [
+                "Kaito detected that you used the KaitoHead object to modify the headers or status, but then returned a Response in the route",
+                "This is usually a mistake, as your Response object will override any changes you made to the headers or status code.",
+                "",
+                "This warning was shown because `process.env.NODE_ENV=development`"
+              ].join("\n");
+              console.warn(msg);
+            }
+          }
+          return result;
+        }
+        return head.toResponse({
+          success: true,
+          data: result,
+          message: "OK"
+        });
+      } catch (e) {
+        const error = WrappedError.maybe(e);
+        if (error instanceof KaitoError) {
+          return head.status(error.status).toResponse({
+            success: false,
+            data: null,
+            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
+        });
+      }
+    };
+  };
+  method = (method) => (path, route) => {
+    return this.add(method, path, route);
+  };
+  get = this.method("GET");
+  post = this.method("POST");
+  put = this.method("PUT");
+  patch = this.method("PATCH");
+  delete = this.method("DELETE");
+  head = this.method("HEAD");
+  options = this.method("OPTIONS");
+  through = (through) => {
+    return new _Router({
+      ...this.state,
+      through: async (context) => through(await this.state.through(context))
+    });
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KaitoError,
+  KaitoRequest,
+  Router,
+  WrappedError,
+  createKaitoHandler,
+  createUtilities,
+  isNodeLikeDev,
+  parsable
+});

package/dist/index.d.cts

@@ -0,0 +1,255 @@
+declare class WrappedError<T> extends Error {
+    readonly data: T;
+    static maybe<T>(maybeError: T): (T & Error) | WrappedError<T>;
+    static from<T>(data: T): WrappedError<T>;
+    private constructor();
+}
+declare class KaitoError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+declare class KaitoRequest {
+    readonly url: URL;
+    private readonly _request;
+    constructor(url: URL, request: Request);
+    get headers(): Headers;
+    get method(): string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob(): Promise<Blob>;
+    formData(): Promise<FormData>;
+    bytes(): Promise<Uint8Array>;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+    get request(): Request;
+}
+
+type KaitoMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE';
+
+/**
+ * This class is merely a wrapper around a `Headers` object and a status code.
+ * It's used while the router is executing a route to store any mutations to the status
+ * code or headers that the developer may want to make.
+ *
+ * This exists because there's otherwise no way to indicate back to Kaito that
+ * the developer wants to change the status code or headers.
+ *
+ * @example
+ * ```ts
+ * const response = new KaitoHead();
+ *
+ * response.status(200);
+ * response.headers.set('Content-Type', 'application/json');
+ *
+ * console.log(response.headers); // Headers {'content-type': 'application/json'}
+ * ```
+ */
+declare class KaitoHead {
+    private _headers;
+    private _status;
+    constructor();
+    get headers(): Headers;
+    /**
+     * Gets the status code of this KaitoHead instance
+     * @returns The status code
+     */
+    status(): number;
+    /**
+     * Sets the status code of this KaitoHead instance
+     * @param status The status code to set
+     * @returns This KaitoHead instance
+     */
+    status(status: number): 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<T>(body: APIResponse<T>): Response;
+    /**
+     * Whether this KaitoHead instance has been touched/modified
+     */
+    get touched(): boolean;
+}
+
+/**
+ * A helper to check if the environment is Node.js-like and the NODE_ENV is development
+ */
+declare const isNodeLikeDev: boolean;
+type ErroredAPIResponse = {
+    success: false;
+    data: null;
+    message: string;
+};
+type SuccessfulAPIResponse<T> = {
+    success: true;
+    data: T;
+    message: 'OK';
+};
+type APIResponse<T> = ErroredAPIResponse | SuccessfulAPIResponse<T>;
+type AnyResponse = APIResponse<unknown>;
+type MakeOptional<T, K extends keyof T> = T extends T ? Omit<T, K> & Partial<Pick<T, K>> : never;
+type ExtractRouteParams<T extends string> = string extends T ? Record<string, string> : T extends `${string}:${infer Param}/${infer Rest}` ? {
+    [k in Param | keyof ExtractRouteParams<Rest>]: string;
+} : T extends `${string}:${infer Param}` ? {
+    [k in Param]: string;
+} : {};
+/**
+ * A function that is called to get the context for a request.
+ *
+ * This is useful for things like authentication, to pass in a database connection, etc.
+ *
+ * It's fine for this function to throw; if it does, the error is passed to the `onError` function.
+ *
+ * @param req - The kaito request object, which contains the request method, url, headers, etc
+ * @param head - The kaito head object, which contains getters and setters for headers and status
+ * @returns The context for your routes
+ */
+type GetContext<Result> = (req: KaitoRequest, head: KaitoHead) => Promise<Result>;
+/**
+ * A helper function to create typed necessary functions
+ *
+ * @example
+ * ```ts
+ * const {router, getContext} = createUtilities(async (req, res) => {
+ *   // Return context here
+ * })
+ *
+ * const app = router().get('/', async () => "hello");
+ *
+ * const server = createKaitoHandler({
+ *   router: app,
+ *   getContext,
+ *   // ...
+ * });
+ * ```
+ */
+declare function createUtilities<Context>(getContext: GetContext<Context>): {
+    getContext: GetContext<Context>;
+    router: () => Router<Context, Context, never>;
+};
+interface Parsable<Output = any, Input = Output> {
+    _input: Input;
+    parse: (value: unknown) => Output;
+}
+type InferParsable<T> = T extends Parsable<infer Output, infer Input> ? {
+    input: Input;
+    output: Output;
+} : never;
+declare function parsable<T>(parse: (value: unknown) => T): Parsable<T, T>;
+
+type RouteArgument<Path extends string, Context, QueryOutput, BodyOutput> = {
+    ctx: Context;
+    body: BodyOutput;
+    query: QueryOutput;
+    params: ExtractRouteParams<Path>;
+};
+type AnyQueryDefinition = Record<string, Parsable<any, string | undefined>>;
+type Through<From, To> = (context: From) => Promise<To>;
+type Route<ContextFrom, ContextTo, Result, Path extends string, Method extends KaitoMethod, Query extends AnyQueryDefinition, Body extends Parsable> = {
+    through: Through<ContextFrom, ContextTo>;
+    body?: Body;
+    query?: Query;
+    path: Path;
+    method: Method;
+    run(arg: RouteArgument<Path, ContextTo, {
+        [Key in keyof Query]: InferParsable<Query[Key]>['output'];
+    }, InferParsable<Body>['output']>): Promise<Result>;
+};
+type AnyRoute<ContextFrom = any, ContextTo = any> = Route<ContextFrom, ContextTo, any, any, any, AnyQueryDefinition, any>;
+
+type PrefixRoutesPathInner<R extends AnyRoute, Prefix extends `/${string}`> = R extends Route<infer ContextFrom, infer ContextTo, infer Result, infer Path, infer Method, infer Query, infer BodyOutput> ? Route<ContextFrom, ContextTo, Result, `${Prefix}${Path}`, Method, Query, BodyOutput> : never;
+type PrefixRoutesPath<Prefix extends `/${string}`, R extends AnyRoute> = R extends R ? PrefixRoutesPathInner<R, Prefix> : never;
+type RouterState<Routes extends AnyRoute, ContextFrom, ContextTo> = {
+    routes: Set<Routes>;
+    through: (context: ContextFrom) => Promise<ContextTo>;
+};
+type InferRoutes<R extends Router<any, any, any>> = R extends Router<any, any, infer R> ? R : never;
+declare class Router<ContextFrom, ContextTo, R extends AnyRoute> {
+    private readonly state;
+    static create: <Context>() => Router<Context, Context, never>;
+    private static parseQuery;
+    constructor(options: RouterState<R, ContextFrom, ContextTo>);
+    get routes(): Set<R>;
+    add: <Result, Path extends string, Method extends KaitoMethod, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(method: Method, path: Path, route: (Method extends "GET" ? Omit<Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body>, "body" | "path" | "method" | "through"> : Omit<Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body>, "path" | "method" | "through">) | Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body>["run"]) => Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, Method, Query, Body>>;
+    readonly merge: <PathPrefix extends `/${string}`, OtherRoutes extends AnyRoute>(pathPrefix: PathPrefix, other: Router<ContextFrom, unknown, OtherRoutes>) => Router<ContextFrom, ContextTo, Extract<R | PrefixRoutesPath<PathPrefix, OtherRoutes>, AnyRoute>>;
+    freeze: (server: Omit<HandlerConfig<ContextFrom>, "router">) => (req: Request) => Promise<Response>;
+    private readonly method;
+    get: <Result, Path extends string, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(path: Path, route: ((arg: RouteArgument<Path, ContextTo, { [Key in keyof Query]: InferParsable<Query[Key]>["output"]; }, InferParsable<Body>["output"]>) => Promise<Result>) | Omit<Route<ContextFrom, ContextTo, Result, Path, "GET", Query, Body>, "body" | "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, "GET", Query, Body>>;
+    post: <Result, Path extends string, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(path: Path, route: ((arg: RouteArgument<Path, ContextTo, { [Key in keyof Query]: InferParsable<Query[Key]>["output"]; }, InferParsable<Body>["output"]>) => Promise<Result>) | Omit<Route<ContextFrom, ContextTo, Result, Path, "POST", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, "POST", Query, Body>>;
+    put: <Result, Path extends string, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(path: Path, route: ((arg: RouteArgument<Path, ContextTo, { [Key in keyof Query]: InferParsable<Query[Key]>["output"]; }, InferParsable<Body>["output"]>) => Promise<Result>) | Omit<Route<ContextFrom, ContextTo, Result, Path, "PUT", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, "PUT", Query, Body>>;
+    patch: <Result, Path extends string, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(path: Path, route: ((arg: RouteArgument<Path, ContextTo, { [Key in keyof Query]: InferParsable<Query[Key]>["output"]; }, InferParsable<Body>["output"]>) => Promise<Result>) | Omit<Route<ContextFrom, ContextTo, Result, Path, "PATCH", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, "PATCH", Query, Body>>;
+    delete: <Result, Path extends string, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(path: Path, route: ((arg: RouteArgument<Path, ContextTo, { [Key in keyof Query]: InferParsable<Query[Key]>["output"]; }, InferParsable<Body>["output"]>) => Promise<Result>) | Omit<Route<ContextFrom, ContextTo, Result, Path, "DELETE", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, "DELETE", Query, Body>>;
+    head: <Result, Path extends string, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(path: Path, route: ((arg: RouteArgument<Path, ContextTo, { [Key in keyof Query]: InferParsable<Query[Key]>["output"]; }, InferParsable<Body>["output"]>) => Promise<Result>) | Omit<Route<ContextFrom, ContextTo, Result, Path, "HEAD", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, "HEAD", Query, Body>>;
+    options: <Result, Path extends string, Query extends AnyQueryDefinition = {}, Body extends Parsable = never>(path: Path, route: ((arg: RouteArgument<Path, ContextTo, { [Key in keyof Query]: InferParsable<Query[Key]>["output"]; }, InferParsable<Body>["output"]>) => Promise<Result>) | Omit<Route<ContextFrom, ContextTo, Result, Path, "OPTIONS", Query, Body>, "path" | "method" | "through">) => Router<ContextFrom, ContextTo, R | Route<ContextFrom, ContextTo, Result, Path, "OPTIONS", Query, Body>>;
+    through: <NextContext>(through: (context: ContextTo) => Promise<NextContext>) => Router<ContextFrom, NextContext, R>;
+}
+
+type HandlerConfig<ContextFrom> = {
+    /**
+     * The root router to mount on this handler.
+     */
+    router: Router<ContextFrom, unknown, any>;
+    /**
+     * A function that is called to get the context for a request.
+     *
+     * This is useful for things like authentication, to pass in a database connection, etc.
+     *
+     * It's fine for this function to throw; if it does, the error is passed to the `onError` function.
+     */
+    getContext: GetContext<ContextFrom>;
+    /**
+     * A function that is called when an error occurs inside a route handler.
+     *
+     * The result of this function is used to determine the response status and message, and is
+     * always sent to the client. You could include logic to check for production vs development
+     * environments here, and this would also be a good place to include error tracking
+     * like Sentry or Rollbar.
+     *
+     * @param arg - The error thrown, and the KaitoRequest instance
+     * @returns A KaitoError or an object with a status and message
+     */
+    onError: (arg: {
+        error: Error;
+        req: KaitoRequest;
+    }) => Promise<KaitoError | {
+        status: number;
+        message: string;
+    }>;
+    /**
+     * A function that is called before every request. Most useful for bailing out early in the case of an OPTIONS request.
+     *
+     * @example
+     * ```ts
+     * before: async req => {
+     * 	if (req.method === 'OPTIONS') {
+     * 		return new Response(null, {status: 204});
+     * 	}
+     * }
+     * ```
+     */
+    before?: (req: Request) => Promise<Response | void | undefined>;
+    /**
+     * Transforms the response before it is sent to the client. Very useful for settings headers like CORS.
+     *
+     * You can also return a new response in this function, or just mutate the current one.
+     *
+     * This function WILL receive the result of `.before()` if you return a response from it. This means
+     *  you only need to define headers in a single place.
+     *
+     * @example
+     * ```ts
+     * transform: async (req, res) => {
+     * 	res.headers.set('Access-Control-Allow-Origin', 'http://localhost:3000');
+     * 	res.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+     * 	res.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+     * 	res.headers.set('Access-Control-Max-Age', '86400');
+     * 	res.headers.set('Access-Control-Allow-Credentials', 'true');
+     * }
+     * ```
+     */
+    transform?: (req: Request, res: Response) => Promise<Response | void | undefined>;
+};
+declare function createKaitoHandler<Context>(config: HandlerConfig<Context>): (request: Request) => Promise<Response>;
+
+export { type APIResponse, type AnyQueryDefinition, type AnyResponse, type AnyRoute, type ErroredAPIResponse, type ExtractRouteParams, type GetContext, type HandlerConfig, type InferParsable, type InferRoutes, KaitoError, type KaitoMethod, KaitoRequest, type MakeOptional, type Parsable, type Route, type RouteArgument, Router, type RouterState, type SuccessfulAPIResponse, type Through, WrappedError, createKaitoHandler, createUtilities, isNodeLikeDev, parsable };