stoker

stoke the flame 🤙🔥

Utilities for hono and @hono/zod-openapi.

To see real world usage of these utilities, checkout the hono-open-api-starter routes example

• stoker
  • Utilities
    • stoker/http-status-codes
      • Example Usage
    • stoker/http-status-phrases
      • Example Usage
  • Middlewares
    • stoker/middlewares/not-found
      • Example Usage
    • stoker/middlewares/on-error
      • Example Usage
    • stoker/middlewares/serve-emoji-favicon
      • Example Usage
  • Open API
    • Default Hook
      • Example Usage
    • Helpers
      • stoker/openapi/helpers/json-content
        • Example Usage
      • stoker/openapi/helpers/json-content-required
        • Example Usage
      • stoker/openapi/helpers/json-content-one-of
        • Example Usage
      • stoker/openapi/helpers/one-of
    • Schemas
      • stoker/openapi/schemas/id-params
        • Example Usage
      • stoker/openapi/schemas/slug-params
        • Example Usage
      • stoker/openapi/schemas/id-uuid-params
        • Example Usage
      • stoker/openapi/schemas/get-params-schema
        • Example Usage
      • stoker/openapi/schemas/create-message-object
        • Example Usage
      • stoker/openapi/schemas/create-error-schema
        • Example Usage
  • Credits

Utilities

stoker/http-status-codes

HTTP status code constants. Provides individual typed / documented exports. Use anywhere you need a status code instead of hard coding raw numbers.

Sourced from http-status-codes | RFC1945 (HTTP/1.0), RFC2616 (HTTP/1.1), RFC2518 (WebDAV), RFC6585 (Additional HTTP Status Codes), and RFC7538 (Permanent Redirect).

Why not use the http-status-codes package directly? http-status-codes exports enums which do not work well with the @hono/zod-openapi type system and the built in StatusCode type from hono/utils/http-status.

Example Usage

1import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
3import * as HttpStatusCodes from "stoker/http-status-codes";
4
5const app = new OpenAPIHono();
6
7app.notFound((c) => {
8  return c.json({
9    message: `Not Found - ${c.req.path}`,
10  }, HttpStatusCodes.NOT_FOUND);
11});
12
13app.onError((err, c) => {
14  return c.json(
15    {
16      message: err.message,
17    },
18    HttpStatusCodes.INTERNAL_SERVER_ERROR,
19  );
20});
21
22app.openapi(
23  createRoute({
24    path: "/",
25    tags: ["Index"],
26    description: "Index route",
27    method: "get",
28    responses: {
29      [HttpStatusCodes.OK]: {
30        content: {
31          "application/json": {
32            schema: z.object({
33              message: z.string(),
34            }),
35          },
36        },
37        description: "Index route",
38      },
39    },
40  }),
41  (c) => {
42    return c.json({ message: "Hello World" }, HttpStatusCodes.OK);
43  },
44);
45
46export default app;

stoker/http-status-phrases

HTTP status phrase constants.

Example Usage

1import * as HttpStatusPhrases from "stoker/http-status-phrases";
2
3console.log(HttpStatusPhrases.NOT_FOUND); // Not Found

Middlewares

stoker/middlewares/not-found

A default 404 handler.

• Responds with JSON object
  • Message property includes not found path
• Sets status code to 404

Example Usage

1import { Hono } from "hono";
2
3import notFound from "stoker/middlewares/not-found";
4
5const app = new Hono();
6
7app.notFound(notFound);
8
9export default app;

stoker/middlewares/on-error

A default error handler.

• Responds with JSON object
  • Message property includes error message
  • Stack trace included when NODE_ENV !== "production"
• Sets status code to existing status code if already set OR 500

Example Usage

1import { Hono } from "hono";
2
3import onError from "stoker/middlewares/on-error";
4
5const app = new Hono();
6
7app.onError(onError);
8
9export default app;

stoker/middlewares/serve-emoji-favicon

Serve an svg emoji as a favicon from /favicon.ico

Example Usage

1import { Hono } from "hono";
2
3import serveEmojiFavicon from "stoker/middlewares/serve-emoji-favicon";
4
5const app = new Hono();
6
7app.use(serveEmojiFavicon("🔥"));
8
9export default app;

Open API

Default Hook

A default error hook you can include in your OpenAPIHono instance. Includes the success status and ZodError

Example Usage

1import { OpenAPIHono } from "@hono/zod-openapi";
2
3import defaultHook from "stoker/openapi/default-hook";
4
5/*
6Any validation errors will respond with status code 422 and body:
7{
8  success: false,
9  error: {}, // Full Zod Error
10}
11*/
12const app = new OpenAPIHono({
13  defaultHook,
14});
15
16export default app;

Helpers

stoker/openapi/helpers/json-content

Create a content / schema description with a type of application/json

Example Usage

1import { z } from "@hono/zod-openapi";
2
3import jsonContent from "stoker/openapi/helpers/json-content";
4
5const schema = z.object({
6  message: z.string(),
7});
8
9/*
10* Equivalent to:
11{
12  content: {
13    "application/json": {
14      schema,
15    },
16  },
17  description: "Retrieve the user",
18}
19*/
20const response = jsonContent(
21  schema,
22  "Retrieve the message"
23);

stoker/openapi/helpers/json-content-required

Useful for json body schema validators.

Create a content / schema description with a type of application/json and required set to true

Example Usage

1import { z } from "@hono/zod-openapi";
2
3import jsonContentRequired from "stoker/openapi/helpers/json-content-required";
4
5const schema = z.object({
6  message: z.string(),
7});
8
9/*
10* Equivalent to:
11{
12  content: {
13    "application/json": {
14      schema,
15    },
16  },
17  description: "Retrieve the user",
18  required: true
19}
20*/
21const response = jsonContentRequired(
22  schema,
23  "Retrieve the message"
24);

stoker/openapi/helpers/json-content-one-of

Peer dependency of @asteasolutions/zod-to-openapi

WARNING: Not recommended right now, type hints from @hono/zod-openapi are not correct when using this helper. If you don't absolutely need oneOf in your specification, use zod or (anyOf) instead.

Create a json content / schema description where the schema can be oneOf multiple schemas. Useful when you have multiple possible validation response schemas.

Example Usage

1import { z } from "@hono/zod-openapi";
2
3import jsonContentOneOf from "stoker/openapi/helpers/json-content-one-of";
4import createErrorSchema from "stoker/openapi/schemas/create-error-schema";
5import IdParamsSchema from "stoker/openapi/schemas/id-params";
6
7const bodySchema = z.object({
8  name: z.string(),
9});
10
11/*
12* Equivalent to:
13{
14  content: {
15    "application/json": {
16      schema: {
17        oneOf: SchemaObject[]
18      },
19    },
20  },
21  description: "Invalid Id params or Invalid Body"
22}
23*/
24const result = jsonContentOneOf(
25  [createErrorSchema(IdParamsSchema), createErrorSchema(bodySchema)],
26  "Invalid Id params or Invalid Body"
27);

stoker/openapi/helpers/one-of

Peer dependency of @asteasolutions/zod-to-openapi

Used internally by stoker/openapi/helpers/json-content-one-of but exported here in case you need to access the generated schemas for other use cases.

1import { z } from "@hono/zod-openapi";
2
3import oneOf from "stoker/openapi/helpers/one-of";
4import createErrorSchema from "stoker/openapi/schemas/create-error-schema";
5import IdParamsSchema from "stoker/openapi/schemas/id-params";
6
7const bodySchema = z.object({
8  name: z.string(),
9});
10
11/*
12* Returns: SchemaObject[]
13*/
14const result = oneOf([createErrorSchema(IdParamsSchema), createErrorSchema(bodySchema)]);

Schemas

Commonly used zod schemas for use when creating routes with @hono/zod-openapi

stoker/openapi/schemas/id-params

Validate id in path params as a number.

Example Usage

1import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
3import * as HttpStatusCodes from "stoker/http-status-codes";
4import jsonContent from "stoker/openapi/helpers/json-content";
5import IdParamsSchema from "stoker/openapi/schemas/id-params";
6
7const app = new OpenAPIHono();
8
9app.openapi(
10  createRoute({
11    method: "get",
12    path: "/users/{id}",
13    request: {
14      params: IdParamsSchema,
15    },
16    responses: {
17      [HttpStatusCodes.OK]: jsonContent(
18        z.object({
19          id: z.number(),
20        }),
21        "Retrieve the user",
22      ),
23    },
24  }),
25  (c) => {
26    // id is a valid number
27    const { id } = c.req.valid("param");
28    return c.json({
29      id,
30    }, HttpStatusCodes.OK);
31  },
32);
33
34export default app;

stoker/openapi/schemas/slug-params

Validate slug in path params as a slug.

Example Usage

1import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
3import * as HttpStatusCodes from "stoker/http-status-codes";
4import jsonContent from "stoker/openapi/helpers/json-content";
5import SlugParamsSchema from "stoker/openapi/schemas/slug-params";
6
7const app = new OpenAPIHono();
8
9app.openapi(
10  createRoute({
11    method: "get",
12    path: "/posts/{slug}",
13    request: {
14      params: SlugParamsSchema,
15    },
16    responses: {
17      [HttpStatusCodes.OK]: jsonContent(
18        z.object({
19          slug: z.string(),
20        }),
21        "Retrieve the post",
22      ),
23    },
24  }),
25  (c) => {
26    // slug is a valid slug
27    const { slug } = c.req.valid("param");
28    return c.json({
29      slug,
30    }, HttpStatusCodes.OK);
31  },
32);
33
34export default app;

stoker/openapi/schemas/id-uuid-params

Validate id in path params as a uuid.

Example Usage

1import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
3import * as HttpStatusCodes from "stoker/http-status-codes";
4import jsonContent from "stoker/openapi/helpers/json-content";
5import IdUUIDParamsSchema from "stoker/openapi/schemas/id-uuid-params";
6
7const app = new OpenAPIHono();
8
9app.openapi(
10  createRoute({
11    method: "get",
12    path: "/users/{id}",
13    request: {
14      params: IdUUIDParamsSchema,
15    },
16    responses: {
17      [HttpStatusCodes.OK]: jsonContent(
18        z.object({
19          id: z.uuid(),
20        }),
21        "Retrieve the user",
22      ),
23    },
24  }),
25  (c) => {
26    // id is a valid uuid
27    const { id } = c.req.valid("param");
28    return c.json({
29      id,
30    }, HttpStatusCodes.OK);
31  },
32);
33
34export default app;

stoker/openapi/schemas/get-params-schema

Validate a custom named path param using Zod string validators by calling the function getParamsSchema({ name, validator }).

Name defaults to id. Validator defaults to uuid and supports type "uuid" | "nanoid" | "cuid" | "cuid2" | "ulid".

Example Usage

1import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
3import * as HttpStatusCodes from "stoker/http-status-codes";
4import jsonContent from "stoker/openapi/helpers/json-content";
5import getParamsSchema from "stoker/openapi/schemas/get-params-schema";
6
7const app = new OpenAPIHono();
8
9app.openapi(
10  createRoute({
11    method: "get",
12    path: "/users/{userId}",
13    request: {
14      params: getParamsSchema({
15        name: "userId",
16        validator: "nanoid",
17      }),
18    },
19    responses: {
20      [HttpStatusCodes.OK]: jsonContent(
21        z.object({
22          userId: z.nanoid(),
23        }),
24        "Retrieve the user",
25      ),
26    },
27  }),
28  (c) => {
29    // userId is a valid nanoid
30    const { userId } = c.req.valid("param");
31    return c.json({
32      userId,
33    }, HttpStatusCodes.OK);
34  },
35);
36
37export default app;

stoker/openapi/schemas/create-message-object

Create an object schema with a message string property. Useful for error messages.

Example Usage

1import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
3import * as HttpStatusCodes from "stoker/http-status-codes";
4import * as HttpStatusPhrases from "stoker/http-status-phrases";
5import jsonContent from "stoker/openapi/helpers/json-content";
6import createMessageObjectSchema from "stoker/openapi/schemas/create-message-object";
7import IdParamsSchema from "stoker/openapi/schemas/id-params";
8
9const app = new OpenAPIHono();
10
11app.openapi(
12  createRoute({
13    method: "get",
14    path: "/some-thing-that-might-not-be-found",
15    responses: {
16      [HttpStatusCodes.NOT_FOUND]: jsonContent(
17        createMessageObjectSchema(HttpStatusPhrases.NOT_FOUND),
18        HttpStatusPhrases.NOT_FOUND,
19      ),
20    },
21  }),
22  (c) => {
23    return c.json({
24      message: HttpStatusPhrases.NOT_FOUND,
25    }, HttpStatusCodes.NOT_FOUND);
26  },
27);
28
29export default app;

stoker/openapi/schemas/create-error-schema

Create an example error schema with zod error / validation messages based on given schema.

Example Usage

1import { createRoute, z } from "@hono/zod-openapi";
2
3import * as HttpStatusCodes from "stoker/http-status-codes";
4import jsonContent from "stoker/openapi/helpers/json-content";
5import createErrorSchema from "stoker/openapi/schemas/create-error-schema";
6
7const TaskSchema = z.object({
8  name: z.string(),
9  completed: z.boolean().default(false),
10});
11
12export const createTask = createRoute({
13  method: "post",
14  path: "/task",
15  request: {
16    body: jsonContent(TaskSchema, "The Task"),
17  },
18  responses: {
19    // ... OK response here
20    [HttpStatusCodes.UNPROCESSABLE_ENTITY]: jsonContent(
21      // Creates example schema with validation messages for name / completed
22      createErrorSchema(TaskSchema),
23      "Invalid task",
24    ),
25  },
26});

Credits

Project bootstrapped with antfu/starter-ts