@okay-e9g/hono-config 0.0.16 → 0.0.18

package/package.json

@@ -48,5 +48,5 @@
 		"prepublishOnly": "bun run typecheck && bun test",
 		"typecheck": "tsc --noEmit"
 	},
-	"version": "0.0.16"
+	"version": "0.0.18"
 }

package/src/handlers/not-found.ts

@@ -5,12 +5,14 @@
 import type { Env, NotFoundHandler } from 'hono/types';
 
 import type { ResponseEnv } from '../middlewares/ensure-rt';
-import { statusText } from '../schemas';
+import { rpcStandardErrorText, statusText } from '../schemas';
 
 /**
  * Creates the shared 404 handler used by the configured Hono factories.
  *
- * Falls back to a plain text 404 when no response helper has been installed.
+ * API helpers produce an HTTP 404 envelope. RPC helpers produce a JSON-RPC
+ * `Method Not Found` error with a `null` id and an HTTP 200 status. Falls back
+ * to a plain text 404 when no response helper has been installed.
  *
  * @internal
  */
@@ -26,6 +28,11 @@ export const notFound = <T extends Env>(): NotFoundHandler<T> => {
 			return c.json(response.error(404), 404);
 		}
 
-		return c.json(response.error(statusText[404]));
+		return c.json(
+			response.error({
+				code: -32601,
+				message: rpcStandardErrorText['-32601'],
+			}),
+		);
 	};
 };

package/src/handlers/on-error.ts

@@ -7,10 +7,10 @@ import type { Env, ErrorHandler } from 'hono/types';
 import { z } from 'zod';
 
 import type { ResponseEnv } from '../middlewares/ensure-rt';
-import { type ClientErrorStatusCode, type ServerErrorStatusCode, statusText } from '../schemas';
+import { type ClientErrorStatusCode, rpcStandardErrorText, type ServerErrorStatusCode } from '../schemas';
 
 interface TypedHTTPException extends Omit<HTTPException, 'status'> {
-	status: ClientErrorStatusCode & ServerErrorStatusCode;
+	status: ClientErrorStatusCode | ServerErrorStatusCode;
 }
 
 const assertHTTPException = (err: Error): err is TypedHTTPException => {
@@ -22,7 +22,10 @@ const assertHTTPException = (err: Error): err is TypedHTTPException => {
  *
  * Errors are rethrown when no response helper has been installed, allowing
  * Hono's fallback error handling to handle apps that are not using this
- * package's response envelopes.
+ * package's response envelopes. API helpers preserve HTTP error semantics.
+ * RPC helpers map validation failures to `Invalid Params`, 4xx HTTP exceptions
+ * to `Invalid Request`, and 5xx or generic failures to `Internal Error`,
+ * returning a JSON-RPC envelope with a `null` id.
  *
  * @internal
  */
@@ -39,7 +42,13 @@ export const onError = <T extends Env>(): ErrorHandler<T> => {
 				return c.json(response.error(400, z.flattenError(err)), 400);
 			}
 
-			return c.json(response.error(z.flattenError(err)));
+			return c.json(
+				response.error({
+					code: -32602,
+					data: z.flattenError(err),
+					message: rpcStandardErrorText['-32602'],
+				}),
+			);
 		}
 
 		if (assertHTTPException(err)) {
@@ -49,7 +58,9 @@ export const onError = <T extends Env>(): ErrorHandler<T> => {
 				return c.json(response.error(status, message), status);
 			}
 
-			return c.json(response.error(message === '' ? statusText[status] : message));
+			const code = status < 500 ? -32600 : -32603;
+
+			return c.json(response.error({ code, message: message === '' ? rpcStandardErrorText[code] : message }));
 		}
 
 		const errMessage = err instanceof Error ? err.message : err;
@@ -58,6 +69,11 @@ export const onError = <T extends Env>(): ErrorHandler<T> => {
 			return c.json(response.error(500, errMessage), 500);
 		}
 
-		return c.json(response.error(errMessage === '' ? statusText[500] : errMessage));
+		return c.json(
+			response.error({
+				code: -32603,
+				message: errMessage === '' ? rpcStandardErrorText['-32603'] : errMessage,
+			}),
+		);
 	};
 };

package/src/middlewares/response.ts

@@ -96,11 +96,13 @@ export const apiResponseType = <T extends ApiResponseEnv>(): MiddlewareHandler<T
 };
 
 interface TypedRpcError<T = unknown> extends RpcError {
-	error?: T;
+	error: Omit<RpcError['error'], 'data'> & {
+		data?: T;
+	};
 }
 
 interface TypedRpcResult<T = unknown> extends RpcResult {
-	result?: T;
+	result: T;
 }
 
 /**
@@ -113,13 +115,15 @@ export interface RpcResponseEnv extends Env {
 		 */
 		response: {
 			/**
-			 * Builds a JSON-RPC error response envelope for the provided request id.
+			 * Builds a JSON-RPC error response envelope from a numeric code, message,
+			 * and optional data. The request id defaults to `null` when omitted.
 			 */
-			error: <T>(error?: T, id?: JsonRpc['id']) => TypedRpcError<T>;
+			error: <T>(error: TypedRpcError<T>['error'], id?: JsonRpc['id']) => TypedRpcError<T>;
 			/**
-			 * Builds a JSON-RPC result response envelope for the provided request id.
+			 * Builds a JSON-RPC result response envelope for the required result. The
+			 * request id defaults to `null` when omitted.
 			 */
-			result: <T>(result?: T, id?: JsonRpc['id']) => TypedRpcResult<T>;
+			result: <T>(result: T, id?: JsonRpc['id']) => TypedRpcResult<T>;
 			/**
 			 * Discriminator used by shared error handlers and response guards.
 			 */
@@ -132,7 +136,7 @@ export interface RpcResponseEnv extends Env {
  * Installs `c.var.response` helpers for JSON-RPC 2.0 responses.
  *
  * The helpers produce `error` and `result` envelopes validated by the exported
- * JSON-RPC schemas and default missing ids to the schema default. If another
+ * JSON-RPC schemas and default missing ids to `null`. If another
  * response helper is already installed, the existing helper is kept so
  * applications can compose middleware safely.
  *
@@ -142,10 +146,10 @@ export const rpcResponseType = <T extends RpcResponseEnv>(): MiddlewareHandler<T
 	return createMiddleware<RpcResponseEnv>(async (c, next) => {
 		if (c.var.response === undefined) {
 			c.set('response', {
-				error: <T>(error?: T, id?: JsonRpc['id']) => {
+				error: <T>(error: TypedRpcError<T>['error'], id?: JsonRpc['id']) => {
 					return rpcError.parse({ error, id }) as TypedRpcError<T>;
 				},
-				result: <T>(result?: T, id?: JsonRpc['id']) => {
+				result: <T>(result: T, id?: JsonRpc['id']) => {
 					return rpcResult.parse({ id, result }) as TypedRpcResult<T>;
 				},
 				type: 'rpc',

package/src/schemas/index.ts

@@ -5,3 +5,4 @@
 export * from './api';
 export * from './http-status';
 export * from './rpc';
+export * from './rpc-error';

package/src/schemas/rpc-error.ts

@@ -0,0 +1,37 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { z } from 'zod';
+
+/**
+ * Zod schema for the five pre-defined JSON-RPC 2.0 error codes.
+ *
+ * This schema excludes the reserved server-error range and application-defined
+ * error codes. Use it when a value must be one of the protocol's standard
+ * errors rather than any valid JSON-RPC error code.
+ */
+export const rpcStandardErrorCode = z.union([
+	z.literal(-32600),
+	z.literal(-32601),
+	z.literal(-32602),
+	z.literal(-32603),
+	z.literal(-32700),
+]);
+
+/**
+ * One of the five pre-defined JSON-RPC 2.0 error codes.
+ */
+export type RpcStandardErrorCode = z.infer<typeof rpcStandardErrorCode>;
+
+/**
+ * Title-cased short messages for the pre-defined JSON-RPC 2.0 errors, keyed by
+ * their numeric code for consistency with the package's HTTP status text.
+ */
+export const rpcStandardErrorText: Record<RpcStandardErrorCode, string> = {
+	'-32600': 'Invalid Request',
+	'-32601': 'Method Not Found',
+	'-32602': 'Invalid Params',
+	'-32603': 'Internal Error',
+	'-32700': 'Parse Error',
+};

package/src/schemas/rpc.ts

@@ -4,11 +4,13 @@
 
 import { z } from 'zod';
 
+import { rpcStandardErrorCode } from './rpc-error';
+
 /**
  * Zod schema for JSON-RPC 2.0 fields shared by requests and responses.
  */
 export const jsonRpc = z.object({
-	id: z.union([z.number(), z.string()]).default(1),
+	id: z.union([z.null(), z.number(), z.string()]).default(null),
 	jsonrpc: z.literal('2.0').default('2.0'),
 });
 
@@ -43,11 +45,22 @@ export type RpcRequests = z.infer<typeof rpcRequests>;
 
 /**
  * Zod schema for a JSON-RPC 2.0 error response.
+ *
+ * The error object requires a standard or reserved server-error code and a
+ * message, and may include implementation-defined data.
  */
-export const rpcError = z.object({
-	...jsonRpc.shape,
-	error: z.unknown().optional(),
-}).strict();
+export const rpcError = z
+	.object({
+		...jsonRpc.shape,
+		error: z
+			.object({
+				code: z.union([rpcStandardErrorCode, z.int().min(-32099).max(-32000)]),
+				data: z.unknown().optional(),
+				message: z.string(),
+			})
+			.strict(),
+	})
+	.strict();
 
 /**
  * TypeScript type inferred from `rpcError`.
@@ -57,10 +70,12 @@ export type RpcError = z.infer<typeof rpcError>;
 /**
  * Zod schema for a JSON-RPC 2.0 result response.
  */
-export const rpcResult = z.object({
-	...jsonRpc.shape,
-	result: z.unknown().optional(),
-}).strict();
+export const rpcResult = z
+	.object({
+		...jsonRpc.shape,
+		result: z.unknown(),
+	})
+	.strict();
 
 /**
  * TypeScript type inferred from `rpcResult`.