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

package/dist/stream/stream.cjs

@@ -0,0 +1,134 @@
+"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/stream/stream.ts
+var stream_exports = {};
+__export(stream_exports, {
+  KaitoSSEResponse: () => KaitoSSEResponse,
+  SSEController: () => SSEController,
+  sse: () => sse,
+  sseEventToString: () => sseEventToString,
+  sseFromAnyReadable: () => sseFromAnyReadable
+});
+module.exports = __toCommonJS(stream_exports);
+var KaitoSSEResponse = class extends Response {
+  constructor(body, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("Content-Type", "text/event-stream");
+    headers.set("Cache-Control", "no-cache");
+    headers.set("Connection", "keep-alive");
+    super(body, {
+      ...init,
+      headers
+    });
+  }
+  async *[Symbol.asyncIterator]() {
+    for await (const chunk of this.body) {
+      yield chunk;
+    }
+  }
+};
+function sseEventToString(event) {
+  let result = "";
+  if (event.event) {
+    result += `event:${event.event}
+`;
+  }
+  if (event.id) {
+    result += `id:${event.id}
+`;
+  }
+  if (event.retry) {
+    result += `retry:${event.retry}
+`;
+  }
+  if (event.data !== void 0) {
+    result += `data:${JSON.stringify(event.data)}`;
+  }
+  return result;
+}
+var SSEController = class {
+  controller;
+  constructor(controller) {
+    this.controller = controller;
+  }
+  enqueue(event) {
+    this.controller.enqueue(sseEventToString(event) + "\n\n");
+  }
+  close() {
+    this.controller.close();
+  }
+  [Symbol.dispose]() {
+    this.close();
+  }
+};
+function sseFromSource(source) {
+  const start = source.start;
+  const pull = source.pull;
+  const cancel = source.cancel;
+  const readable = new ReadableStream({
+    ...cancel ? { cancel } : {},
+    ...start ? {
+      start: async (controller) => {
+        await start(new SSEController(controller));
+      }
+    } : {},
+    ...pull ? {
+      pull: async (controller) => {
+        await pull(new SSEController(controller));
+      }
+    } : {}
+  });
+  return new KaitoSSEResponse(readable);
+}
+function sse(source) {
+  const evaluated = typeof source === "function" ? source() : source;
+  if ("next" in evaluated) {
+    const generator = evaluated;
+    return sseFromSource({
+      async start(controller) {
+        try {
+          for await (const event of generator) {
+            controller.enqueue(event);
+          }
+        } finally {
+          controller.close();
+        }
+      }
+    });
+  } else {
+    return sseFromSource(evaluated);
+  }
+}
+function sseFromAnyReadable(stream, transform) {
+  const transformer = new TransformStream({
+    transform: (chunk, controller) => {
+      controller.enqueue(transform(chunk));
+    }
+  });
+  return sse(stream.pipeThrough(transformer));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KaitoSSEResponse,
+  SSEController,
+  sse,
+  sseEventToString,
+  sseFromAnyReadable
+});

package/dist/stream/stream.d.cts

@@ -0,0 +1,36 @@
+declare class KaitoSSEResponse<_T> extends Response {
+    constructor(body: ReadableStream<string>, init?: ResponseInit);
+    [Symbol.asyncIterator](): AsyncGenerator<Uint8Array<ArrayBufferLike>, void, unknown>;
+}
+type SSEEvent<T, E extends string> = ({
+    data: T;
+    event?: E | undefined;
+} | {
+    data?: T | undefined;
+    event: E;
+}) & {
+    retry?: number;
+    id?: string;
+};
+/**
+ * Converts an SSE Event into a string, ready for sending to the client
+ * @param event The SSE Event
+ * @returns A stringified version
+ */
+declare function sseEventToString(event: SSEEvent<unknown, string>): string;
+declare class SSEController<U, E extends string> implements Disposable {
+    private readonly controller;
+    constructor(controller: ReadableStreamDefaultController<string>);
+    enqueue(event: SSEEvent<U, E>): void;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+interface SSESource<U, E extends string> {
+    cancel?: UnderlyingSourceCancelCallback;
+    start?(controller: SSEController<U, E>): Promise<void>;
+    pull?(controller: SSEController<U, E>): Promise<void>;
+}
+declare function sse<U, E extends string, T extends SSEEvent<U, E>>(source: SSESource<U, E> | AsyncGenerator<T, unknown, unknown> | (() => AsyncGenerator<T, unknown, unknown>)): KaitoSSEResponse<T>;
+declare function sseFromAnyReadable<R, U, E extends string>(stream: ReadableStream<R>, transform: (chunk: R) => SSEEvent<U, E>): KaitoSSEResponse<SSEEvent<U, E>>;
+
+export { KaitoSSEResponse, SSEController, type SSEEvent, type SSESource, sse, sseEventToString, sseFromAnyReadable };

package/dist/stream/stream.d.ts

@@ -0,0 +1,36 @@
+declare class KaitoSSEResponse<_T> extends Response {
+    constructor(body: ReadableStream<string>, init?: ResponseInit);
+    [Symbol.asyncIterator](): AsyncGenerator<Uint8Array<ArrayBufferLike>, void, unknown>;
+}
+type SSEEvent<T, E extends string> = ({
+    data: T;
+    event?: E | undefined;
+} | {
+    data?: T | undefined;
+    event: E;
+}) & {
+    retry?: number;
+    id?: string;
+};
+/**
+ * Converts an SSE Event into a string, ready for sending to the client
+ * @param event The SSE Event
+ * @returns A stringified version
+ */
+declare function sseEventToString(event: SSEEvent<unknown, string>): string;
+declare class SSEController<U, E extends string> implements Disposable {
+    private readonly controller;
+    constructor(controller: ReadableStreamDefaultController<string>);
+    enqueue(event: SSEEvent<U, E>): void;
+    close(): void;
+    [Symbol.dispose](): void;
+}
+interface SSESource<U, E extends string> {
+    cancel?: UnderlyingSourceCancelCallback;
+    start?(controller: SSEController<U, E>): Promise<void>;
+    pull?(controller: SSEController<U, E>): Promise<void>;
+}
+declare function sse<U, E extends string, T extends SSEEvent<U, E>>(source: SSESource<U, E> | AsyncGenerator<T, unknown, unknown> | (() => AsyncGenerator<T, unknown, unknown>)): KaitoSSEResponse<T>;
+declare function sseFromAnyReadable<R, U, E extends string>(stream: ReadableStream<R>, transform: (chunk: R) => SSEEvent<U, E>): KaitoSSEResponse<SSEEvent<U, E>>;
+
+export { KaitoSSEResponse, SSEController, type SSEEvent, type SSESource, sse, sseEventToString, sseFromAnyReadable };

package/dist/stream/stream.js

@@ -0,0 +1,105 @@
+// src/stream/stream.ts
+var KaitoSSEResponse = class extends Response {
+  constructor(body, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("Content-Type", "text/event-stream");
+    headers.set("Cache-Control", "no-cache");
+    headers.set("Connection", "keep-alive");
+    super(body, {
+      ...init,
+      headers
+    });
+  }
+  async *[Symbol.asyncIterator]() {
+    for await (const chunk of this.body) {
+      yield chunk;
+    }
+  }
+};
+function sseEventToString(event) {
+  let result = "";
+  if (event.event) {
+    result += `event:${event.event}
+`;
+  }
+  if (event.id) {
+    result += `id:${event.id}
+`;
+  }
+  if (event.retry) {
+    result += `retry:${event.retry}
+`;
+  }
+  if (event.data !== void 0) {
+    result += `data:${JSON.stringify(event.data)}`;
+  }
+  return result;
+}
+var SSEController = class {
+  controller;
+  constructor(controller) {
+    this.controller = controller;
+  }
+  enqueue(event) {
+    this.controller.enqueue(sseEventToString(event) + "\n\n");
+  }
+  close() {
+    this.controller.close();
+  }
+  [Symbol.dispose]() {
+    this.close();
+  }
+};
+function sseFromSource(source) {
+  const start = source.start;
+  const pull = source.pull;
+  const cancel = source.cancel;
+  const readable = new ReadableStream({
+    ...cancel ? { cancel } : {},
+    ...start ? {
+      start: async (controller) => {
+        await start(new SSEController(controller));
+      }
+    } : {},
+    ...pull ? {
+      pull: async (controller) => {
+        await pull(new SSEController(controller));
+      }
+    } : {}
+  });
+  return new KaitoSSEResponse(readable);
+}
+function sse(source) {
+  const evaluated = typeof source === "function" ? source() : source;
+  if ("next" in evaluated) {
+    const generator = evaluated;
+    return sseFromSource({
+      async start(controller) {
+        try {
+          for await (const event of generator) {
+            controller.enqueue(event);
+          }
+        } finally {
+          controller.close();
+        }
+      }
+    });
+  } else {
+    return sseFromSource(evaluated);
+  }
+}
+function sseFromAnyReadable(stream, transform) {
+  const transformer = new TransformStream({
+    transform: (chunk, controller) => {
+      controller.enqueue(transform(chunk));
+    }
+  });
+  return sse(stream.pipeThrough(transformer));
+}
+export {
+  KaitoSSEResponse,
+  SSEController,
+  sse,
+  sseEventToString,
+  sseFromAnyReadable
+};

package/package.json

@@ -1,15 +1,30 @@
 {
   "name": "@kaito-http/core",
-  "version": "3.0.0-beta.7",
+  "version": "3.0.1",
   "type": "module",
   "author": "Alistair Smith <hi@alistair.sh>",
   "description": "Functional HTTP Framework for TypeScript",
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "attw": "attw --profile node16 --pack .",
+    "test": "node --test --import=tsx ./src/**/*.test.ts"
   },
   "exports": {
     "./package.json": "./package.json",
-    ".": "./dist/index.js"
+    ".": {
+      "import": {
+        "types": "./src/index.ts",
+        "default": "./dist/index.js"
+      },
+      "require": "./dist/index.cjs"
+    },
+    "./stream": {
+      "import": {
+        "types": "./src/stream/stream.ts",
+        "default": "./dist/stream/stream.js"
+      },
+      "require": "./dist/stream/stream.cjs"
+    }
   },
   "homepage": "https://github.com/kaito-http/kaito",
   "repository": "https://github.com/kaito-http/kaito",
@@ -20,24 +35,18 @@
   ],
   "license": "MIT",
   "devDependencies": {
-    "@types/content-type": "^1.1.8",
-    "@types/cookie": "^0.6.0",
-    "@types/node": "^22.7.4",
-    "tsup": "^8.3.0",
-    "typescript": "^5.6.2"
+    "@arethetypeswrong/cli": "^0.17.2",
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
   },
   "files": [
     "package.json",
     "README.md",
-    "dist"
+    "dist",
+    "src"
   ],
   "bugs": {
     "url": "https://github.com/kaito-http/kaito/issues"
-  },
-  "dependencies": {
-    "content-type": "^1.0.5",
-    "cookie": "^0.6.0",
-    "find-my-way": "^9.1.0",
-    "raw-body": "^3.0.0"
   }
 }

package/src/error.ts

@@ -0,0 +1,26 @@
+export class WrappedError<T> extends Error {
+	public static maybe<T>(maybeError: T) {
+		if (maybeError instanceof Error) {
+			return maybeError;
+		}
+
+		return WrappedError.from(maybeError);
+	}
+
+	public static from<T>(data: T) {
+		return new WrappedError(data);
+	}
+
+	private constructor(public readonly data: T) {
+		super('Something was thrown, but it was not an instance of Error, so a WrappedError was created.');
+	}
+}
+
+export class KaitoError extends Error {
+	constructor(
+		public readonly status: number,
+		message: string,
+	) {
+		super(message);
+	}
+}

package/src/handler.ts

@@ -0,0 +1,96 @@
+import type {KaitoError} from './error.ts';
+import type {KaitoRequest} from './request.ts';
+import type {Router} from './router/router.ts';
+import type {GetContext} from './util.ts';
+
+export 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>;
+};
+
+export function createKaitoHandler<Context>(config: HandlerConfig<Context>) {
+	const handle = config.router.freeze(config);
+
+	return async (request: Request): Promise<Response> => {
+		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;
+	};
+}

package/src/head.ts

@@ -0,0 +1,83 @@
+import type {APIResponse} from './util.ts';
+
+/**
+ * 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'}
+ * ```
+ */
+export class KaitoHead {
+	private _headers: Headers | null;
+	private _status: number;
+
+	public constructor() {
+		this._headers = null;
+		this._status = 200;
+	}
+
+	public get headers() {
+		if (this._headers === null) {
+			this._headers = new Headers();
+		}
+
+		return this._headers;
+	}
+
+	/**
+	 * Gets the status code of this KaitoHead instance
+	 * @returns The status code
+	 */
+	public status(): number;
+
+	/**
+	 * Sets the status code of this KaitoHead instance
+	 * @param status The status code to set
+	 * @returns This KaitoHead instance
+	 */
+	public status(status: number): this;
+
+	public status(status?: number) {
+		if (status === undefined) {
+			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
+	 */
+	public toResponse<T>(body: APIResponse<T>): Response {
+		const init: ResponseInit = {
+			status: this._status,
+		};
+
+		if (this._headers) {
+			init.headers = this._headers;
+		}
+
+		return Response.json(body, init);
+	}
+
+	/**
+	 * Whether this KaitoHead instance has been touched/modified
+	 */
+	public get touched() {
+		return this._status !== 200 || this._headers !== null;
+	}
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './error.ts';
+export * from './handler.ts';
+export * from './request.ts';
+export * from './route.ts';
+export * from './router/router.ts';
+export type {KaitoMethod} from './router/types.ts';
+export * from './util.ts';

package/src/request.ts

@@ -0,0 +1,47 @@
+export class KaitoRequest {
+	public readonly url: URL;
+
+	private readonly _request: Request;
+
+	public constructor(url: URL, request: Request) {
+		this._request = request;
+		this.url = url;
+	}
+
+	public get headers() {
+		return this._request.headers;
+	}
+
+	public get method() {
+		return this._request.method;
+	}
+
+	public async arrayBuffer(): Promise<ArrayBuffer> {
+		return this._request.arrayBuffer();
+	}
+
+	public async blob(): Promise<Blob> {
+		return this._request.blob();
+	}
+
+	public async formData(): Promise<FormData> {
+		return this._request.formData();
+	}
+
+	public async bytes(): Promise<Uint8Array> {
+		const buffer = await this.arrayBuffer();
+		return new Uint8Array(buffer);
+	}
+
+	public async json(): Promise<unknown> {
+		return this._request.json();
+	}
+
+	public async text(): Promise<string> {
+		return this._request.text();
+	}
+
+	public get request() {
+		return this._request;
+	}
+}

package/src/route.ts

@@ -0,0 +1,52 @@
+import type {KaitoMethod} from './router/types.ts';
+import type {ExtractRouteParams, InferParsable, Parsable} from './util.ts';
+
+export type RouteArgument<Path extends string, Context, QueryOutput, BodyOutput> = {
+	ctx: Context;
+	body: BodyOutput;
+	query: QueryOutput;
+	params: ExtractRouteParams<Path>;
+};
+
+export type AnyQueryDefinition = Record<string, Parsable<any, string | undefined>>;
+
+export type Through<From, To> = (context: From) => Promise<To>;
+
+export type Route<
+	// Router context
+	ContextFrom,
+	ContextTo,
+	// Route information
+	Result,
+	Path extends string,
+	Method extends KaitoMethod,
+	// Schemas
+	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>;
+};
+
+export type AnyRoute<ContextFrom = any, ContextTo = any> = Route<
+	ContextFrom,
+	ContextTo,
+	any,
+	any,
+	any,
+	AnyQueryDefinition,
+	any
+>;