hono 4.13.12 → 5.0.0-rc.0

package/README.md

@@ -63,9 +63,9 @@ The migration guide is available on [docs/MIGRATION.md](docs/MIGRATION.md).
 Contributions Welcome! You can contribute in the following ways.
 
 - Create an Issue - Propose a new feature. Report a bug.
-- Pull Request - Fix a bug or typo. Refactor the code.
-- Create third-party middleware - See [Third-party middleware](docs/CONTRIBUTING.md#third-party-middleware).
+- Build middleware and libraries - Grow the Hono ecosystem.
 - Share - Share your thoughts on the Blog, X, and others.
+- Sponsor - Support the maintainers through GitHub Sponsors: [@yusukebe](https://github.com/sponsors/yusukebe) and [@usualoma](https://github.com/sponsors/usualoma).
 - Make your application - Please try to use Hono.
 
 For more details, see [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).

package/dist/{types/compose.d.ts → compose.d.ts}

@@ -1,6 +1,7 @@
 import { Env, ErrorHandler, Next, NotFoundHandler } from "./types.js";
 import { Context } from "./context.js";
 //#region src/compose.d.ts
+export declare const toError: (err: unknown) => Error;
 /**
  * Compose middleware functions into a single function based on `koa-compose` package.
  *

package/dist/compose.js

@@ -1,4 +1,5 @@
 //#region src/compose.ts
+const toError = (err) => err instanceof Error ? err : new Error(typeof err === "string" ? err : void 0, { cause: err });
 /**
 * Compose middleware functions into a single function based on `koa-compose` package.
 *
@@ -32,11 +33,15 @@ const compose = (middleware, onError, onNotFound) => {
 				context.req.routeIndex = i;
 			} else handler = i === middleware.length && next || void 0;
 			if (handler) try {
-				res = await handler(context, () => dispatch(i + 1));
+				res = await handler(context, () => {
+					const routeIndex = context.req.routeIndex;
+					return dispatch(i + 1).finally(() => context.req.routeIndex = routeIndex);
+				});
 			} catch (err) {
-				if (err instanceof Error && onError) {
-					context.error = err;
-					res = await onError(err, context);
+				if (onError) {
+					const error = toError(err);
+					context.error = error;
+					res = await onError(error, context);
 					isError = true;
 				} else throw err;
 			}
@@ -47,4 +52,4 @@ const compose = (middleware, onError, onNotFound) => {
 	};
 };
 //#endregion
-export { compose };
+export { compose, toError };

package/dist/{types/context.d.ts → context.d.ts}

@@ -268,14 +268,14 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  render: Renderer;
+  get render(): Renderer;
   /**
    * Sets the layout for the response.
    *
    * @param layout - The layout to set.
    * @returns The layout function.
    */
-  setLayout: (layout: Layout<PropsForRenderer & {
+  get setLayout(): (layout: Layout<PropsForRenderer & {
     Layout: Layout;
   }>) => Layout<PropsForRenderer & {
     Layout: Layout;
@@ -285,7 +285,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    *
    * @returns The current layout function.
    */
-  getLayout: () => Layout<PropsForRenderer & {
+  get getLayout(): () => Layout<PropsForRenderer & {
     Layout: Layout;
   }> | undefined;
   /**
@@ -309,7 +309,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  setRenderer: (renderer: Renderer) => void;
+  get setRenderer(): (renderer: Renderer) => void;
   /**
    * `.header()` can set headers.
    *
@@ -330,8 +330,8 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  header: SetHeaders;
-  status: (status: StatusCode) => void;
+  get header(): SetHeaders;
+  get status(): (status: StatusCode) => void;
   /**
    * `.set()` can set the value specified by the key.
    *
@@ -345,7 +345,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  set: Set<IsAny<E> extends true ? {
+  get set(): Set<IsAny<E> extends true ? {
     Variables: ContextVariableMap & Record<PropertyKey, any>;
   } : E>;
   /**
@@ -361,7 +361,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  get: Get<IsAny<E> extends true ? {
+  get get(): Get<IsAny<E> extends true ? {
     Variables: ContextVariableMap & Record<PropertyKey, any>;
   } : E>;
   /**
@@ -375,7 +375,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * ```
    */
   get var(): Readonly<ContextVariableMap & (IsAny<E['Variables']> extends true ? Record<string, any> : E['Variables'])>;
-  newResponse: NewResponse;
+  get newResponse(): NewResponse;
   /**
    * `.body()` can return the HTTP response.
    * You can set headers with `.header()` and set HTTP status code with `.status`.
@@ -397,7 +397,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  body: BodyRespond;
+  get body(): BodyRespond;
   /**
    * `.text()` can render text as `Content-Type:text/plain`.
    *
@@ -410,7 +410,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  text: TextRespond;
+  get text(): TextRespond;
   /**
    * `.json()` can render JSON as `Content-Type:application/json`.
    *
@@ -423,8 +423,8 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  json: JSONRespond;
-  html: HTMLRespond;
+  get json(): JSONRespond;
+  get html(): HTMLRespond;
   /**
    * `.redirect()` can Redirect, default status code is 302.
    *
@@ -440,7 +440,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  redirect: <T extends RedirectStatusCode = 302>(location: string | URL, status?: T) => Response & TypedResponse<undefined, T, "redirect">;
+  get redirect(): <T extends RedirectStatusCode = 302>(location: string | URL, status?: T) => Response & TypedResponse<undefined, T, 'redirect'>;
   /**
    * `.notFound()` can return the Not Found Response.
    *
@@ -453,7 +453,7 @@ export declare class Context<E extends Env = any, P extends string = any, I exte
    * })
    * ```
    */
-  notFound: () => ReturnType<NotFoundHandler>;
+  get notFound(): () => ReturnType<NotFoundHandler>;
 }
 //#endregion
 export {};

package/dist/context.js

@@ -135,23 +135,29 @@ var Context = class {
 	* })
 	* ```
 	*/
-	render = (...args) => {
-		this.#renderer ??= (content) => this.html(content);
-		return this.#renderer(...args);
-	};
+	get render() {
+		return (...args) => {
+			this.#renderer ??= (content) => this.html(content);
+			return this.#renderer(...args);
+		};
+	}
 	/**
 	* Sets the layout for the response.
 	*
 	* @param layout - The layout to set.
 	* @returns The layout function.
 	*/
-	setLayout = (layout) => this.#layout = layout;
+	get setLayout() {
+		return (layout) => this.#layout = layout;
+	}
 	/**
 	* Gets the current layout for the response.
 	*
 	* @returns The current layout function.
 	*/
-	getLayout = () => this.#layout;
+	get getLayout() {
+		return () => this.#layout;
+	}
 	/**
 	* `.setRenderer()` can set the layout in the custom middleware.
 	*
@@ -173,9 +179,11 @@ var Context = class {
 	* })
 	* ```
 	*/
-	setRenderer = (renderer) => {
-		this.#renderer = renderer;
-	};
+	get setRenderer() {
+		return (renderer) => {
+			this.#renderer = renderer;
+		};
+	}
 	/**
 	* `.header()` can set headers.
 	*
@@ -196,16 +204,20 @@ var Context = class {
 	* })
 	* ```
 	*/
-	header = (name, value, options) => {
-		if (this.finalized) this.#res = createResponseInstance(this.#res.body, this.#res);
-		const headers = this.#res ? this.#res.headers : this.#preparedHeaders ??= new Headers();
-		if (value === void 0) headers.delete(name);
-		else if (options?.append) headers.append(name, value);
-		else headers.set(name, value);
-	};
-	status = (status) => {
-		this.#status = status;
-	};
+	get header() {
+		return (name, value, options) => {
+			if (this.finalized) this.#res = createResponseInstance(this.#res.body, this.#res);
+			const headers = this.#res ? this.#res.headers : this.#preparedHeaders ??= new Headers();
+			if (value === void 0) headers.delete(name);
+			else if (options?.append) headers.append(name, value);
+			else headers.set(name, value);
+		};
+	}
+	get status() {
+		return (status) => {
+			this.#status = status;
+		};
+	}
 	/**
 	* `.set()` can set the value specified by the key.
 	*
@@ -219,10 +231,12 @@ var Context = class {
 	* })
 	* ```
 	*/
-	set = (key, value) => {
-		this.#var ??= /* @__PURE__ */ new Map();
-		this.#var.set(key, value);
-	};
+	get set() {
+		return (key, value) => {
+			this.#var ??= /* @__PURE__ */ new Map();
+			this.#var.set(key, value);
+		};
+	}
 	/**
 	* `.get()` can use the value specified by the key.
 	*
@@ -236,9 +250,11 @@ var Context = class {
 	* })
 	* ```
 	*/
-	get = (key) => {
-		return this.#var ? this.#var.get(key) : void 0;
-	};
+	get get() {
+		return (key) => {
+			return this.#var ? this.#var.get(key) : void 0;
+		};
+	}
 	/**
 	* `.var` can access the value of a variable.
 	*
@@ -283,7 +299,9 @@ var Context = class {
 			headers: responseHeaders ?? headers
 		});
 	}
-	newResponse = (...args) => this.#newResponse(...args);
+	get newResponse() {
+		return (...args) => this.#newResponse(...args);
+	}
 	/**
 	* `.body()` can return the HTTP response.
 	* You can set headers with `.header()` and set HTTP status code with `.status`.
@@ -305,7 +323,9 @@ var Context = class {
 	* })
 	* ```
 	*/
-	body = (data, arg, headers) => this.#newResponse(data, arg, headers);
+	get body() {
+		return (data, arg, headers) => this.#newResponse(data, arg, headers);
+	}
 	/**
 	* `.text()` can render text as `Content-Type:text/plain`.
 	*
@@ -318,9 +338,11 @@ var Context = class {
 	* })
 	* ```
 	*/
-	text = (text, arg, headers) => {
-		return !this.#preparedHeaders && !this.#status && !arg && !headers && !this.finalized ? new Response(text) : this.#newResponse(text, arg, setDefaultContentType(TEXT_PLAIN, headers));
-	};
+	get text() {
+		return (text, arg, headers) => {
+			return !this.#preparedHeaders && !this.#status && !arg && !headers && !this.finalized ? new Response(text) : this.#newResponse(text, arg, setDefaultContentType(TEXT_PLAIN, headers));
+		};
+	}
 	/**
 	* `.json()` can render JSON as `Content-Type:application/json`.
 	*
@@ -333,13 +355,19 @@ var Context = class {
 	* })
 	* ```
 	*/
-	json = (object, arg, headers) => {
-		return this.#newResponse(JSON.stringify(object), arg, setDefaultContentType("application/json", headers));
-	};
-	html = (html, arg, headers) => {
-		const res = (html) => this.#newResponse(html, arg, setDefaultContentType("text/html; charset=UTF-8", headers));
-		return typeof html === "object" ? resolveCallback(html, HtmlEscapedCallbackPhase.Stringify, false, {}).then(res) : res(html);
-	};
+	get json() {
+		return (object, arg, headers) => {
+			const body = JSON.stringify(object);
+			if (body === void 0) throw new TypeError("Value is not JSON serializable");
+			return this.#newResponse(body, arg, setDefaultContentType("application/json", headers));
+		};
+	}
+	get html() {
+		return (html, arg, headers) => {
+			const res = (html) => this.#newResponse(html, arg, setDefaultContentType("text/html; charset=UTF-8", headers));
+			return typeof html === "object" ? resolveCallback(html, HtmlEscapedCallbackPhase.Stringify, false, {}).then(res) : res(html);
+		};
+	}
 	/**
 	* `.redirect()` can Redirect, default status code is 302.
 	*
@@ -355,11 +383,13 @@ var Context = class {
 	* })
 	* ```
 	*/
-	redirect = (location, status) => {
-		const locationString = String(location);
-		this.header("Location", !/[^\x00-\xFF]/.test(locationString) ? locationString : encodeURI(locationString));
-		return this.newResponse(null, status ?? 302);
-	};
+	get redirect() {
+		return (location, status) => {
+			const locationString = String(location);
+			this.header("Location", !/[^\x00-\xFF]/.test(locationString) ? locationString : encodeURI(locationString));
+			return this.newResponse(null, status ?? 302);
+		};
+	}
 	/**
 	* `.notFound()` can return the Not Found Response.
 	*
@@ -372,10 +402,12 @@ var Context = class {
 	* })
 	* ```
 	*/
-	notFound = () => {
-		this.#notFoundHandler ??= () => createResponseInstance();
-		return this.#notFoundHandler(this);
-	};
+	get notFound() {
+		return () => {
+			this.#notFoundHandler ??= () => createResponseInstance();
+			return this.#notFoundHandler(this);
+		};
+	}
 };
 //#endregion
 export { Context, TEXT_PLAIN };

package/dist/helper/factory/define-handler.d.ts

@@ -0,0 +1,150 @@
+import { ContentfulStatusCode } from "../../utils/http-status.js";
+import { JSONParsed } from "../../utils/types.js";
+import { Env, FormValue, Handler, IntersectNonAnyTypes, MiddlewareHandler, TypedResponse, ValidationTargets } from "../../types.js";
+import { Context } from "../../context.js";
+import { HtmlEscaped } from "../../utils/html.js";
+import { InferInput } from "../../validator/utils.js";
+//#region src/helper/factory/define-handler.d.ts
+type StandardSchemaIssue = {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | {
+    readonly key: PropertyKey;
+  }> | undefined;
+};
+type StandardSchemaResult<Output> = {
+  readonly value: Output;
+  readonly issues?: undefined;
+} | {
+  readonly issues: ReadonlyArray<StandardSchemaIssue>;
+};
+/**
+ * The part of the Standard Schema interface used by `defineHandler()`.
+ * @see {@link https://standardschema.dev/}
+ */
+export type StandardSchema<Input = unknown, Output = Input> = {
+  readonly '~standard': {
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    } | undefined;
+  };
+};
+type AnyStandardSchema = StandardSchema<any, any>;
+type AnyResponse = Response | TypedResponse<any, any, any>;
+/**
+ * A Standard Schema or a validation function for `Value`.
+ * `T` is the schema itself, or the output of the function. It is `never` when not specified.
+ */
+type Validation<Value, T> = (T & AnyStandardSchema) | ((value: Value, c: Context<any, any, any>) => T | Promise<T>);
+type ResponseValidation<In, Out> = (Out & StandardSchema<In, any>) | ((value: In, c: Context<any, any, any>) => Out | Promise<Out>);
+/**
+ * A Response the handler can return. A JSON Response by `c.json()` is not accepted,
+ * because it bypasses the response validation. Return the value instead.
+ */
+type NonJSONResponse = Response & {
+  readonly _format?: 'text' | 'redirect' | 'body';
+};
+type InputOf<T> = T extends StandardSchema<infer I, any> ? I : Exclude<T, AnyResponse>;
+type OutputOf<T> = T extends StandardSchema<any, infer O> ? O : Exclude<T, AnyResponse>;
+type RequestTarget = keyof ValidationTargets;
+type Targets = { [K in RequestTarget]: unknown; };
+type ValidatedTarget<T extends Targets> = { [K in RequestTarget]: [T[K]] extends [never] ? never : K; }[RequestTarget];
+type ValidatedInput<T extends Targets> = {
+  in: { [K in ValidatedTarget<T>]: K extends 'json' ? InputOf<T[K]> : InferInput<InputOf<T[K]>, K, FormValue>; };
+  out: { [K in ValidatedTarget<T>]: OutputOf<T[K]>; };
+};
+/** The validated values, passed to the handler as the second argument */
+type HandlerInput<T extends Targets> = { [K in ValidatedTarget<T>]: OutputOf<T[K]>; };
+type JSONResponseOf<T> = Response & TypedResponse<JSONParsed<T>, ContentfulStatusCode, 'json'>;
+/** The Response that `toResponse()` converts a returned value to */
+type ConvertedResponse<R> = [unknown] extends [R] ? Response : R extends AnyResponse ? R : R extends null | undefined | void ? Response & TypedResponse<null, 204, 'body'> : R extends string | HtmlEscaped ? Response : JSONResponseOf<R>;
+type AnyMiddleware = MiddlewareHandler<any, any, any>;
+type MiddlewareEnvs<M extends AnyMiddleware[]> = { [K in keyof M]: M[K] extends MiddlewareHandler<infer ME, any, any> ? ME : never; };
+/**
+ * An issue in the failure response. `path` is dot-joined, e.g. `user.email`.
+ * The input value is not included.
+ */
+export type ValidationIssue = {
+  message: string;
+  path?: string;
+};
+/** The issues of one validation target in the failure response */
+export type ValidationFailure = {
+  slot: RequestTarget | 'response';
+  issues: ValidationIssue[];
+};
+type ValidatedHandlerOptions<Param, Query, Header, Cookie, Form, Json, ResponseIn, ResponseOut> = {
+  param?: Validation<ValidationTargets['param'], Param>;
+  query?: Validation<ValidationTargets['query'], Query>;
+  header?: Validation<ValidationTargets['header'], Header>;
+  cookie?: Validation<ValidationTargets['cookie'], Cookie>;
+  form?: Validation<ValidationTargets['form'], Form>;
+  json?: Validation<ValidationTargets['json'], Json>;
+  response?: ResponseValidation<ResponseIn, ResponseOut>;
+};
+type ValidatedHandler<E extends Env, P extends string, T extends Targets, ResponseOut, R> = Handler<E, P, ValidatedInput<T>, Promise<[ResponseOut] extends [never] ? ConvertedResponse<Awaited<R>> : JSONResponseOf<OutputOf<ResponseOut>>>>;
+export interface DefineHandler<E extends Env, P extends string> {
+  /**
+   * Defines a handler, with middleware before it. The returned value is converted to a Response.
+   */
+  <E2 extends Env = E, P2 extends string = P, M extends AnyMiddleware[] = [], R = unknown>(...args: [...middleware: M, handler: (c: Context<IntersectNonAnyTypes<[E2, ...MiddlewareEnvs<M>]>, P2>) => R]): Handler<E2, P2, {}, Promise<ConvertedResponse<Awaited<R>>>>;
+  /**
+   * Defines a handler with request and response validation, with middleware before it.
+   */
+  <Param = never, Query = never, Header = never, Cookie = never, Form = never, Json = never, ResponseIn = unknown, ResponseOut = never, T extends Targets = {
+    param: Param;
+    query: Query;
+    header: Header;
+    cookie: Cookie;
+    form: Form;
+    json: Json;
+  }>(options: ValidatedHandlerOptions<Param, Query, Header, Cookie, Form, Json, ResponseIn, ResponseOut>): <E2 extends Env = E, P2 extends string = P, M extends AnyMiddleware[] = [], R extends ResponseIn | NonJSONResponse | Promise<ResponseIn | NonJSONResponse> = ResponseIn>(...args: [...middleware: M, handler: (c: Context<IntersectNonAnyTypes<[E2, ...MiddlewareEnvs<M>]>, P2, ValidatedInput<T>>, input: HandlerInput<T>) => R]) => ValidatedHandler<E2, P2, T, ResponseOut, R>;
+}
+/**
+ * `defineHandler()` defines a handler. A value returned from the handler is converted to a
+ * Response: an object is returned as JSON, a string or JSX as HTML, and `null` or `undefined`
+ * as `204 No Content`. A `Response` is returned as is. The status is set with `c.status()`, and
+ * it is not in the types. Return `c.json()` to have the status in the types.
+ *
+ * With options, each request target (`param`, `query`, `json`, `form`, `header`, `cookie`)
+ * is validated before the handler runs. The validated values are passed to the handler as
+ * the second argument, and are also available through `c.req.valid()`.
+ * A value returned from the handler is validated with `response` and returned as JSON.
+ *
+ * Each validation accepts a Standard Schema or a validation function.
+ * When a Standard Schema fails, an `HTTPException` is thrown with status 400 for the request
+ * and 500 for the response, so `onError` can handle it. Its `res` is a JSON response of
+ * `{ error, issues }`, and its `cause` is `{ issues }` with the raw Standard Schema issues.
+ *
+ * Middleware passed before the handler runs first, around the validation. Its Env flows into
+ * the handler, so `c.get()` is typed. Otherwise, use `createFactory<Env>().defineHandler`, or
+ * pass the Env and the path as type arguments.
+ *
+ * @see {@link https://hono.dev/docs/helpers/factory#definehandler}
+ *
+ * @experimental
+ * `defineHandler()` is an experimental feature.
+ * The API might be changed.
+ *
+ * @example
+ * ```ts
+ * app.get('/ping', defineHandler(() => ({ pong: true })))
+ * app.get('/me', defineHandler(auth, (c) => c.get('user')))
+ *
+ * app.post(
+ *   '/users/:id',
+ *   defineHandler({
+ *     param: ParamSchema,
+ *     json: BodySchema,
+ *     response: UserSchema,
+ *   })(async (c, { param, json }) => {
+ *     c.status(201)
+ *     return { id: param.id, ...json }
+ *   })
+ * )
+ * ```
+ */
+export declare const defineHandler: DefineHandler<any, any>;
+//#endregion
+export {};