helper function to generate params schema with custom names and zod s…

…tring validators among "uuid" | "nanoid" | "cuid" | "cuid2" | "ulid" (#7)

add getParamsSchema; bump version

---------

Co-authored-by: w3cj <[email protected]>

README.md

@@ -43,10 +43,12 @@ To see real world usage of these utilities, checkout the [hono-open-api-starter
         - [Example Usage](#example-usage-10)
       - [stoker/openapi/schemas/id-uuid-params](#stokeropenapischemasid-uuid-params)
         - [Example Usage](#example-usage-11)
-      - [stoker/openapi/schemas/create-message-object](#stokeropenapischemascreate-message-object)
+      - [stoker/openapi/schemas/get-params-schema](#stokeropenapischemasget-params-schema)
         - [Example Usage](#example-usage-12)
-      - [stoker/openapi/schemas/create-error-schema](#stokeropenapischemascreate-error-schema)
+      - [stoker/openapi/schemas/create-message-object](#stokeropenapischemascreate-message-object)
         - [Example Usage](#example-usage-13)
+      - [stoker/openapi/schemas/create-error-schema](#stokeropenapischemascreate-error-schema)
+        - [Example Usage](#example-usage-14)
   - [Credits](#credits)
 
 ## Utilities
@@ -467,6 +469,54 @@ app.openapi(
 export 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
+
+```ts
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import * as HttpStatusCodes from "stoker/http-status-codes";
+import jsonContent from "stoker/openapi/helpers/json-content";
+import getParamsSchema from "stoker/openapi/schemas/get-params-schema";
+
+const app = new OpenAPIHono();
+
+app.openapi(
+  createRoute({
+    method: "get",
+    path: "/users/{userId}",
+    request: {
+      params: getParamsSchema({
+        name: "userId",
+        validator: "nanoid",
+      }),
+    },
+    responses: {
+      [HttpStatusCodes.OK]: jsonContent(
+        z.object({
+          userId: z.nanoid(),
+        }),
+        "Retrieve the user",
+      ),
+    },
+  }),
+  (c) => {
+    // userId is a valid nanoid
+    const { userId } = c.req.valid("param");
+    return c.json({
+      userId,
+    }, HttpStatusCodes.OK);
+  },
+);
+
+export default app;
+```
+
 #### stoker/openapi/schemas/create-message-object
 
 Create an object schema with a message string property. Useful for error messages.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "stoker",
   "type": "module",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "packageManager": "[email protected]",
   "description": "Utilities for hono and @hono/zod-openapi",
   "author": "w3cj <[email protected]>",
@@ -200,6 +200,16 @@
         "default": "./dist/cjs/openapi/schemas/slug-params.js"
       }
     },
+    "./openapi/schemas/get-params-schema": {
+      "import": {
+        "types": "./dist/esm/openapi/schemas/get-params-schema.d.ts",
+        "default": "./dist/esm/openapi/schemas/get-params-schema.js"
+      },
+      "require": {
+        "types": "./dist/cjs/openapi/schemas/get-params-schema.d.ts",
+        "default": "./dist/cjs/openapi/schemas/get-params-schema.js"
+      }
+    },
     "./openapi/schemas/create-message-object": {
       "import": {
         "types": "./dist/esm/openapi/schemas/create-message-object.d.ts",
@@ -280,6 +290,9 @@
       "openapi/schemas/slug-params": [
         "./dist/esm/openapi/schemas/slug-params.d.ts"
       ],
+      "openapi/schemas/get-params-schema": [
+        "./dist/esm/openapi/schemas/get-params-schema.d.ts"
+      ],
       "openapi/schemas/create-message-object": [
         "./dist/esm/openapi/schemas/create-message-object.d.ts"
       ],

src/openapi/schemas/get-params-schema.ts

@@ -0,0 +1,34 @@
+import { z } from "@hono/zod-openapi";
+
+type Validator = "uuid" | "nanoid" | "cuid" | "cuid2" | "ulid";
+
+export interface ParamsSchema {
+  name?: string;
+  validator?: Validator | undefined;
+}
+
+const examples: Record<Validator, string> = {
+  uuid: "4651e634-a530-4484-9b09-9616a28f35e3",
+  nanoid: "V1StGXR8_Z5jdHi6B-myT",
+  cuid: "cjld2cjxh0000qzrmn831i7rn",
+  cuid2: "tz4a98xxat96iws9zmbrgj3a",
+  ulid: "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+};
+
+const getParamsSchema = ({
+  name = "id",
+  validator = "uuid",
+}: ParamsSchema) => {
+  return z.object({
+    [name]: z.string()[validator]().openapi({
+      param: {
+        name,
+        in: "path",
+      },
+      required: [name],
+      example: examples[validator],
+    }),
+  });
+};
+
+export default getParamsSchema;