@kaito-http/core 3.0.0-beta.3 → 3.0.0-beta.4

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+import * as find_my_way from 'find-my-way';
+import find_my_way__default, { HTTPMethod } from 'find-my-way';
+export { HTTPMethod } from 'find-my-way';
+import * as http from 'http';
+import * as http$1 from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { CookieSerializeOptions } from 'cookie';
+
+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 raw: IncomingMessage;
+    private _url;
+    constructor(raw: IncomingMessage);
+    /**
+     * The full URL of the request, including the protocol, hostname, and path.
+     * Note: does not include the query string or hash
+     */
+    get fullURL(): string;
+    /**
+     * A new URL instance for the full URL of the request.
+     */
+    get url(): URL;
+    /**
+     * The HTTP method of the request.
+     */
+    get method(): HTTPMethod;
+    /**
+     * The protocol of the request, either `http` or `https`.
+     */
+    get protocol(): 'http' | 'https';
+    /**
+     * The request headers
+     */
+    get headers(): http.IncomingHttpHeaders;
+    /**
+     * The hostname of the request.
+     */
+    get hostname(): string;
+}
+
+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>;
+declare class KaitoResponse<T = unknown> {
+    readonly raw: ServerResponse;
+    constructor(raw: ServerResponse);
+    /**
+     * Send a response
+     * @param key The key of the header
+     * @param value The value of the header
+     * @returns The response object
+     */
+    header(key: string, value: string | readonly string[]): this;
+    /**
+     * Set the status code of the response
+     * @param code The status code
+     * @returns The response object
+     */
+    status(code: number): this;
+    /**
+     * Set a cookie
+     * @param name The name of the cookie
+     * @param value The value of the cookie
+     * @param options The options for the cookie
+     * @returns The response object
+     */
+    cookie(name: string, value: string, options: CookieSerializeOptions): this;
+    /**
+     * Send a JSON APIResponse body
+     * @param data The data to send
+     * @returns The response object
+     */
+    json(data: APIResponse<T>): this;
+}
+
+type Before<BeforeAfterContext> = (req: http$1.IncomingMessage, res: http$1.ServerResponse) => Promise<BeforeAfterContext>;
+type HandlerResult = {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    data: {
+        status: number;
+        message: string;
+    };
+};
+type After<BeforeAfterContext> = (ctx: BeforeAfterContext, result: HandlerResult) => Promise<void>;
+type ServerConfigWithBefore<BeforeAfterContext> = {
+    before: Before<BeforeAfterContext>;
+    after?: After<BeforeAfterContext>;
+} | {
+    before?: undefined;
+};
+type ServerConfig<ContextFrom, BeforeAfterContext> = ServerConfigWithBefore<BeforeAfterContext> & {
+    router: Router<ContextFrom, unknown, any>;
+    getContext: GetContext<ContextFrom>;
+    rawRoutes?: Partial<Record<KaitoMethod, Array<{
+        path: string;
+        handler: (request: http$1.IncomingMessage, response: http$1.ServerResponse) => unknown;
+    }>>>;
+    onError(arg: {
+        error: Error;
+        req: KaitoRequest;
+        res: KaitoResponse;
+    }): Promise<KaitoError | {
+        status: number;
+        message: string;
+    }>;
+};
+declare function createFMWServer<Context, BeforeAfterContext = null>(config: ServerConfig<Context, BeforeAfterContext>): {
+    readonly server: http$1.Server<typeof http$1.IncomingMessage, typeof http$1.ServerResponse>;
+    readonly fmw: find_my_way.Instance<find_my_way.HTTPVersion.V1>;
+};
+declare function createServer<Context, BeforeAfterContext = null>(config: ServerConfig<Context, BeforeAfterContext>): http$1.Server<typeof http$1.IncomingMessage, typeof http$1.ServerResponse>;
+
+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 RouterOptions<ContextFrom, ContextTo> = {
+    through: (context: ContextFrom) => Promise<ContextTo>;
+};
+declare class Router<ContextFrom, ContextTo, R extends AnyRoute> {
+    private readonly routerOptions;
+    readonly routes: Set<R>;
+    static create: <Context>() => Router<Context, Context, never>;
+    private static parseQuery;
+    private static handle;
+    constructor(routes: Iterable<R>, options: RouterOptions<ContextFrom, ContextTo>);
+    /**
+     * Adds a new route to the router
+     * @deprecated Use the method-specific methods instead
+     */
+    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: ServerConfig<ContextFrom, any>) => find_my_way__default.Instance<find_my_way__default.HTTPVersion.V1>;
+    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>(transform: (context: ContextTo) => Promise<NextContext>) => Router<ContextFrom, NextContext, R>;
+}
+
+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;
+} : {};
+type KaitoMethod = HTTPMethod | '*';
+type GetContext<Result> = (req: KaitoRequest, res: KaitoResponse) => Promise<Result>;
+/**
+ * @deprecated use `createUtilities` instead
+ */
+declare function createGetContext<Context>(callback: GetContext<Context>): GetContext<Context>;
+/**
+ * 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 = createServer({
+ *   router: app,
+ *   getContext,
+ *   // ...
+ * });
+ * ```
+ */
+declare function createUtilities<Context>(getContext: GetContext<Context>): {
+    getContext: GetContext<Context>;
+    router: () => Router<Context, Context, never>;
+};
+type InferContext<T> = T extends (req: KaitoRequest, res: KaitoResponse) => Promise<infer U> ? U : never;
+declare function getLastEntryInMultiHeaderValue(headerValue: string | string[]): string;
+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;
+type RemoveEndSlashes<T extends string> = T extends `${infer U}/` ? U : T;
+type AddStartSlashes<T extends string> = T extends `/${infer U}` ? `/${U}` : `/${T}`;
+type NormalizePath<T extends string> = AddStartSlashes<RemoveEndSlashes<T>>;
+type Values<T> = T[keyof T];
+type NoEmpty<T> = [keyof T] extends [never] ? never : T;
+declare function getBody(req: KaitoRequest): Promise<unknown>;
+
+type RouteArgument<Path extends string, Context, QueryOutput, BodyOutput> = {
+    ctx: Context;
+    body: BodyOutput;
+    query: QueryOutput;
+    params: ExtractRouteParams<Path>;
+};
+type AnyQueryDefinition = Record<string, Parsable>;
+type RouteRunner<Result, Path extends string, Context, QueryOutput, BodyOutput> = (args: RouteArgument<Path, Context, QueryOutput, BodyOutput>) => Promise<Result>;
+type Route<ContextFrom, ContextTo, Result, Path extends string, Method extends KaitoMethod, Query extends AnyQueryDefinition, Body extends Parsable> = {
+    through: (context: ContextFrom) => Promise<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<FromContext = any, ToContext = any> = Route<FromContext, ToContext, any, any, any, AnyQueryDefinition, any>;
+
+export { type APIResponse, type AddStartSlashes, type After, type AnyQueryDefinition, type AnyResponse, type AnyRoute, type Before, type ErroredAPIResponse, type ExtractRouteParams, type GetContext, type HandlerResult, type InferContext, type InferParsable, KaitoError, type KaitoMethod, KaitoRequest, KaitoResponse, type NoEmpty, type NormalizePath, type Parsable, type RemoveEndSlashes, type Route, type RouteArgument, type RouteRunner, Router, type RouterOptions, type ServerConfig, type ServerConfigWithBefore, type SuccessfulAPIResponse, type Values, WrappedError, createFMWServer, createGetContext, createServer, createUtilities, getBody, getLastEntryInMultiHeaderValue };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaito-http/core",
-  "version": "3.0.0-beta.3",
+  "version": "3.0.0-beta.4",
   "type": "module",
   "author": "Alistair Smith <hi@alistair.sh>",
   "description": "Functional HTTP Framework for TypeScript",