@sugardarius/anzen 0.1.2 → 1.0.1

package/README.md

@@ -1,5 +1,3 @@
-## [Unreleased yet]
-
 A flexible, framework validation agnostic, type-safe factory for creating Next.JS App Router route handlers.
 
 - 🔧 Framework validation agnostic, use a validation library of your choice supporting [Standard Schema](https://standardschema.dev/).
@@ -7,6 +5,7 @@ A flexible, framework validation agnostic, type-safe factory for creating Next.J
 - 🧹 Clean and flexible API.
 - 🔒 Type-safe.
 - 🌱 Dependency free.
+- 🪶 Less than 100kB unpacked.
 
 ## Install
 
@@ -17,10 +16,11 @@ npm i @sugardarius/anzen
 ## Usage
 
 ```tsx
+import { object, string, number } from 'decoders'
 import { createSafeRouteHandler } from '@sugardarius/anzen'
 import { auth } from '~/lib/auth'
 
-export const GET = createSafeRouteHandler(
+export const POST = createSafeRouteHandler(
   {
     authorize: async ({ req }) => {
       const session = await auth.getSession(req)
@@ -30,9 +30,13 @@ export const GET = createSafeRouteHandler(
 
       return { user: session.user }
     },
+    body: object({
+      foo: string,
+      bar: number,
+    }),
   },
-  async ({ auth }, req): Promise<Response> => {
-    return Response.json({ user: auth.user }, { status: 200 })
+  async ({ auth, body }, req): Promise<Response> => {
+    return Response.json({ user: auth.user, body }, { status: 200 })
   }
 )
 ```
@@ -41,11 +45,13 @@ The example above shows how to use the factory to authorize your requests.
 
 ## Framework validation agnostic
 
-By design the factory is framework validation agnostic 🌟. When doing your validations you can use whatever you want as framework validation as long as it implements the [Standard Schema](https://github.com/standard-schema/standard-schema) common interface. You can use your favorite validation library like [Zod](https://zod.dev/) or [decoders](https://decoders.cc/).
+By design the factory is framework validation agnostic 🌟. When doing your validations you can use whatever you want as framework validation as long as it implements the [Standard Schema](https://github.com/standard-schema/standard-schema) common interface. You can use your favorite validation library like [Zod](https://zod.dev/), [Validbot](https://valibot.dev/) or [decoders](https://decoders.cc/).
 
 ```tsx
+// (POST) /app/api/races/[id]/route.ts
 import { z } from 'zod'
 import { object, string, number } from 'decoders'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
 
 export const POST = createSafeRouteHandler(
   {
@@ -57,8 +63,8 @@ export const POST = createSafeRouteHandler(
       name: string,
     }),
   },
-  async ({ body }) => {
-    return Response.json({ body })
+  async ({ segments, body }) => {
+    return Response.json({ segments, body })
   }
 )
 ```
@@ -73,6 +79,318 @@ If you define an async validation then the route handler will throw an error.
 
 Check the API and the available options to configure the factory as you wish.
 
+### Function signature
+
+```tsx
+import {
+  type CreateSafeRouteHandlerOptions,
+  type SafeRouteHandlerContext,
+  createSafeRouteHandler
+} from '@sugardarius/anzen'
+
+/**
+ * Returns a Next.js API route handler function.
+ */
+export const VERB = createSafeRouteHandler(
+  /**
+   * Options to configure the route handler
+   */
+  options: CreateSafeRouteHandlerOptions,
+  /**
+   * The route handler function.
+   */
+  async (
+    /**
+     * Context object providing:
+     *  auth context
+     *  validated segments, search params, body and form data
+     */
+    ctx: SafeRouteHandlerContext,
+    /**
+     * Original request
+     */
+    req: Request
+): Promise<Response> => Response.json({}))
+```
+
+### Base options
+
+When creating a safe route handler you can use a bunch of options for helping you achieve different tasks 👇🏻
+
+#### `id?: string`
+
+Used for logging in development or when the `debug` option is enabled. You can also use it to add extra logging or monitoring.
+By default the id is set to `[unknown:route:handler]`
+
+```tsx
+export const POST = createSafeRouteHandler(
+  {
+    id: 'my-safe-route-handler',
+  },
+  async ({ id }) => {
+    return Response.json({ id })
+  }
+)
+```
+
+#### `authorize?: AuthFunction<AC>`
+
+Function to use to authorize the request. By default it always authorize the request.
+
+Returns a response when the request is not authorized.
+
+```tsx
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+import { auth } from '~/lib/auth'
+
+export const GET = createSafeRouteHandler(
+  {
+    authorize: async ({ req, url }) => {
+      console.log('url', url)
+      const session = await auth.getSession(req)
+      if (!session) {
+        return new Response(null, { status: 401 })
+      }
+
+      return { user: session.user }
+    },
+  },
+  async ({ auth, body }, req): Promise<Response> => {
+    return Response.json({ user: auth.user }, { status: 200 })
+  }
+)
+```
+
+#### `onErrorResponse?: (err: unknown) => Awaitable<Response>`
+
+Callback triggered when the request fails.
+By default it returns a simple `500` response and the error is logged into the console.
+
+Use it if your handler use custom errors and you want to manage them properly by returning a proper response.
+
+You can read more about it under the [Error handling](#error-handling) section.
+
+#### `debug?: boolean`
+
+Use this options to enable debug mode. It will add logs in the handler to help you debug the request.
+
+By default it's set to `false` for production builds.
+In development builds, it will be `true` if `NODE_ENV` is not set to `production`.
+
+```tsx
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const GET = createSafeRouteHandler({ debug: true }, async () => {
+  return new Response(null, { status: 200 })
+})
+```
+
+### Route handler options
+
+You can configure route handler options to validation using a validation library dynamic route segments, URL query parameters, request json body or request form data body 👇🏻
+
+#### `segments?: TSegments`
+
+[Dynamic route segments](https://nextjs.org/docs/app/building-your-application/routing/route-handlers#dynamic-route-segments) used for the route handler path. By design it will handle if the segments are a `Promise` or not.
+
+Please note the expected input is a `StandardSchemaDictionary`.
+
+```tsx
+import { z } from 'zod'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const GET = createSafeRouteHandler(
+  {
+    segments: {
+      accountId: z.string(),
+      projectId: z.string().optional(),
+    },
+  },
+  async ({ segments }) => {
+    return Response.json({ segments })
+  }
+)
+```
+
+#### `onSegmentsValidationErrorResponse?: OnValidationErrorResponse`
+
+Callback triggered when dynamic segments validations returned issues. By default it returns a simple `400` response and issues are logged into the console.
+
+```tsx
+import { z } from 'zod'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const GET = createSafeRouteHandler(
+  {
+    segments: {
+      accountId: z.string(),
+      projectId: z.string().optional(),
+    },
+    onSegmentsValidationErrorResponse: (issues) => {
+      return Response.json({ issues }, { status: 400 })
+    },
+  },
+  async ({ segments }) => {
+    return Response.json({ segments })
+  }
+)
+```
+
+#### `searchParams?: TSearchParams`
+
+Search params used in the route.
+
+Please note the expected input is a `StandardSchemaDictionary`.
+
+```tsx
+import { string, numeric, optional } from 'decoders'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const GET = createSafeRouteHandler(
+  {
+    searchParams: {
+      query: string,
+      page: optional(numeric),
+    },
+  },
+  async ({ searchParams }) => {
+    return Response.json({ searchParams })
+  }
+)
+```
+
+#### `onSearchParamsValidationErrorResponse?: OnValidationErrorResponse`
+
+Callback triggered when search params validations returned issues. By default it returns a simple `400` response and issues are logged into the console.
+
+```tsx
+import { string, numeric, optional } from 'decoders'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const GET = createSafeRouteHandler(
+  {
+    searchParams: {
+      query: string,
+      page: optional(numeric),
+    },
+    onSearchParamsValidationErrorResponse: (issues) => {
+      return Response.json({ issues }, { status: 400 })
+    },
+  },
+  async ({ searchParams }) => {
+    return Response.json({ searchParams })
+  }
+)
+```
+
+#### `body?: TBody`
+
+Request body.
+
+Returns a `405` response if the request method is not `POST`, 'PUT' or 'PATCH'.
+
+Returns a `415`response if the request does not explicitly set the `Content-Type` to `application/json`.
+
+Please note the body is parsed as JSON, so it must be a valid JSON object. Body shouldn't be used with `formData` at the same time. They are **exclusive**.
+
+Why making the distinction? `formData` is used as a `StandardSchemaDictionary` whereas `body` is used as a `StandardSchemaV1`.
+
+```tsx
+import { z } from 'zod'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const POST = createSafeRouteHandler(
+  {
+    body: z.object({
+      name: z.string(),
+      model: z.string(),
+      apiKey: z.string(),
+    }),
+  },
+  async ({ body }) => {
+    return Response.json({ body })
+  }
+)
+```
+
+#### `onBodyValidationErrorResponse?: OnValidationErrorResponse`
+
+Callback triggered when body validation returned issues. By default it returns a simple `400` response and issues are logged into the console.
+
+```tsx
+import { z } from 'zod'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const POST = createSafeRouteHandler(
+  {
+    body: z.object({
+      name: z.string(),
+      model: z.string(),
+      apiKey: z.string(),
+    }),
+    onBodyValidationErrorResponse: (issues) => {
+      return Response.json({ issues }, { status: 400 })
+    },
+  },
+  async ({ body }) => {
+    return Response.json({ body })
+  }
+)
+```
+
+#### `formData?: TFormData`
+
+Request form data.
+
+Returns a `405` response if the request method is not `POST`, 'PUT' or 'PATCH'.
+
+Returns a `415`response if the request does not explicitly set the `Content-Type` to `multipart/form-data` or to `application/x-www-form-urlencoded`.
+
+Please note formData shouldn't be used with `body` at the same time. They are **exclusive**.
+
+Why making the distinction? `formData` is used as a `StandardSchemaDictionary` whereas `body` is used as a `StandardSchemaV1`.
+
+```tsx
+import { z } from 'zod'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const POST = createSafeRouteHandler(
+  {
+    formData: {
+      id: z.string(),
+      message: z.string(),
+    },
+  },
+  async ({ formData }) => {
+    return Response.json({ formData })
+  }
+)
+```
+
+#### `onFormDataValidationErrorResponse?: OnValidationErrorResponse`
+
+Callback triggered when form data validation returned issues. By default it returns a simple `400` response and issues are logged into the console.
+
+```tsx
+import { z } from 'zod'
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const POST = createSafeRouteHandler(
+  {
+    formData: {
+      id: z.string(),
+      message: z.string(),
+    },
+    onFormDataValidationErrorResponse: (issues) => {
+      return Response.json({ issues }, { status: 400 })
+    },
+  },
+  async ({ formData }) => {
+    return Response.json({ formData })
+  }
+)
+```
+
 ### Error handling
 
 By design the factory will catch any error thrown in the route handler will return a simple response with `500` status.
@@ -80,6 +398,7 @@ By design the factory will catch any error thrown in the route handler will retu
 You can customize the error response if you want to fine tune error response management.
 
 ```tsx
+import { createSafeRouteHandler } from '@sugardarius/anzen'
 import { HttpError, DbUnknownError } from '~/lib/errors'
 import { db } from '~/lib/db'
 
@@ -111,6 +430,19 @@ export const GET = createSafeRouteHandler(
 )
 ```
 
+### Using the request in the route handler
+
+The original `request` is cascaded in the route handler function if you need to access to it.
+
+```tsx
+import { createSafeRouteHandler } from '@sugardarius/anzen'
+
+export const GET = createSafeRouteHandler({}, async (ctx, req) => {
+  console.log('integrity', req.integrity)
+  return new Response(null, { status: 200 })
+})
+```
+
 ## Fair use note
 
 Please note that if you're not using any of the proposed options in `createSafeRouteHandler` it means you're surely don't need it.
@@ -131,6 +463,10 @@ export function GET() {
 
 Feel free to open an issue or a PR if you think a relevant option could be added into the factory 🙂
 
+## Requirements
+
+The factory `createSafeRouteHandler` requires Next.js `v14` or `v15` and typescript `v5` as peer dependencies.
+
 ## Contributing
 
 All contributions are welcome! 🙂 Feel free to open an issue if you find a bug or create a pull request if you have a feature request.

package/dist/index.d.cts

@@ -88,8 +88,7 @@ type BaseOptions<AC extends AuthContext | undefined> = {
      * ID for the route handler.
      * Used when logging in development or when `debug` is enabled.
      *
-     * You can also use it in the route handler definition to add extra logging
-     * or monitoring.
+     * You can also use it to add extra logging or monitoring.
      */
     id?: string;
     /**
@@ -112,7 +111,7 @@ type BaseOptions<AC extends AuthContext | undefined> = {
      * Use this options to enable debug mode.
      * It will add logs in the handler to help you debug the request.
      *
-     * By default it's `false` for production builds.
+     * By default it's set to `false` for production builds.
      * In development builds, it will be `true` if `NODE_ENV` is not set to `production`.
      */
     debug?: boolean;
@@ -120,7 +119,10 @@ type BaseOptions<AC extends AuthContext | undefined> = {
 type OnValidationErrorResponse = (issues: readonly StandardSchemaV1.Issue[]) => Awaitable<Response>;
 type CreateSafeRouteHandlerOptions<AC extends AuthContext | undefined, TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined> = {
     /**
-     * Dynamic route segments used in the route handler path.
+     * Dynamic route segments used for the route handler path.
+     * By design it will handler if the segments are a `Promise` or not.
+     *
+     * Please note the expected input is a `StandardSchemaDictionary`.
      */
     segments?: TSegments;
     /**
@@ -130,6 +132,8 @@ type CreateSafeRouteHandlerOptions<AC extends AuthContext | undefined, TSegments
     onSegmentsValidationErrorResponse?: OnValidationErrorResponse;
     /**
      * Search params used in the route.
+     *
+     * Please note the expected input is a `StandardSchemaDictionary`.
      */
     searchParams?: TSearchParams;
     /**
@@ -144,7 +148,7 @@ type CreateSafeRouteHandlerOptions<AC extends AuthContext | undefined, TSegments
      * Returns a `415`response if the request does not explicitly set the `Content-Type` to `application/json`.
      *
      * IMPORTANT: The body is parsed as JSON, so it must be a valid JSON object!
-     * IMPORTANT: body shouldn't be used with `formData` at the same time. They are exclusive.
+     * IMPORTANT: Body shouldn't be used with `formData` at the same time. They are exclusive.
      * Why making the distinction? `formData` is used as a `StandardSchemaDictionary` whereas `body` is used as a `StandardSchemaV1`.
      */
     body?: TBody;
@@ -195,14 +199,29 @@ type SafeRouteHandlerContext<AC extends AuthContext | undefined, TSegments exten
      */
     readonly url: URL;
 } & (AC extends AuthContext ? {
+    /**
+     * Auth context
+     */
     readonly auth: AC;
 } : EmptyObjectType) & (TSegments extends TSegmentsDict ? {
+    /**
+     * Validated route dynamic segments
+     */
     readonly segments: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TSegments>>;
 } : EmptyObjectType) & (TSearchParams extends TSearchParamsDict ? {
+    /**
+     * Validated search params
+     */
     readonly searchParams: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TSearchParams>>;
 } : EmptyObjectType) & (TBody extends TBodySchema ? {
+    /**
+     * Validated request body
+     */
     readonly body: StandardSchemaV1.InferOutput<TBody>;
 } : EmptyObjectType) & (TFormData extends TFormDataDict ? {
+    /**
+     * Validated form data
+     */
     readonly formData: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TFormData>>;
 } : EmptyObjectType);
 type SafeRouteHandler<AC extends AuthContext | undefined, TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined> = (

package/dist/index.d.ts

@@ -88,8 +88,7 @@ type BaseOptions<AC extends AuthContext | undefined> = {
      * ID for the route handler.
      * Used when logging in development or when `debug` is enabled.
      *
-     * You can also use it in the route handler definition to add extra logging
-     * or monitoring.
+     * You can also use it to add extra logging or monitoring.
      */
     id?: string;
     /**
@@ -112,7 +111,7 @@ type BaseOptions<AC extends AuthContext | undefined> = {
      * Use this options to enable debug mode.
      * It will add logs in the handler to help you debug the request.
      *
-     * By default it's `false` for production builds.
+     * By default it's set to `false` for production builds.
      * In development builds, it will be `true` if `NODE_ENV` is not set to `production`.
      */
     debug?: boolean;
@@ -120,7 +119,10 @@ type BaseOptions<AC extends AuthContext | undefined> = {
 type OnValidationErrorResponse = (issues: readonly StandardSchemaV1.Issue[]) => Awaitable<Response>;
 type CreateSafeRouteHandlerOptions<AC extends AuthContext | undefined, TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined> = {
     /**
-     * Dynamic route segments used in the route handler path.
+     * Dynamic route segments used for the route handler path.
+     * By design it will handler if the segments are a `Promise` or not.
+     *
+     * Please note the expected input is a `StandardSchemaDictionary`.
      */
     segments?: TSegments;
     /**
@@ -130,6 +132,8 @@ type CreateSafeRouteHandlerOptions<AC extends AuthContext | undefined, TSegments
     onSegmentsValidationErrorResponse?: OnValidationErrorResponse;
     /**
      * Search params used in the route.
+     *
+     * Please note the expected input is a `StandardSchemaDictionary`.
      */
     searchParams?: TSearchParams;
     /**
@@ -144,7 +148,7 @@ type CreateSafeRouteHandlerOptions<AC extends AuthContext | undefined, TSegments
      * Returns a `415`response if the request does not explicitly set the `Content-Type` to `application/json`.
      *
      * IMPORTANT: The body is parsed as JSON, so it must be a valid JSON object!
-     * IMPORTANT: body shouldn't be used with `formData` at the same time. They are exclusive.
+     * IMPORTANT: Body shouldn't be used with `formData` at the same time. They are exclusive.
      * Why making the distinction? `formData` is used as a `StandardSchemaDictionary` whereas `body` is used as a `StandardSchemaV1`.
      */
     body?: TBody;
@@ -195,14 +199,29 @@ type SafeRouteHandlerContext<AC extends AuthContext | undefined, TSegments exten
      */
     readonly url: URL;
 } & (AC extends AuthContext ? {
+    /**
+     * Auth context
+     */
     readonly auth: AC;
 } : EmptyObjectType) & (TSegments extends TSegmentsDict ? {
+    /**
+     * Validated route dynamic segments
+     */
     readonly segments: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TSegments>>;
 } : EmptyObjectType) & (TSearchParams extends TSearchParamsDict ? {
+    /**
+     * Validated search params
+     */
     readonly searchParams: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TSearchParams>>;
 } : EmptyObjectType) & (TBody extends TBodySchema ? {
+    /**
+     * Validated request body
+     */
     readonly body: StandardSchemaV1.InferOutput<TBody>;
 } : EmptyObjectType) & (TFormData extends TFormDataDict ? {
+    /**
+     * Validated form data
+     */
     readonly formData: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TFormData>>;
 } : EmptyObjectType);
 type SafeRouteHandler<AC extends AuthContext | undefined, TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined> = (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sugardarius/anzen",
-  "version": "0.1.2",
+  "version": "1.0.1",
   "description": "A fast, framework validation agnostic, type-safe factory for creating Next.JS App Router route handlers.",
   "license": "MIT",
   "packageManager": "npm@11.3.0",
@@ -67,18 +67,21 @@
     "typescript": "^5"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.17.4",
-    "@eslint/js": "^9.25.1",
+    "@arethetypeswrong/cli": "^0.18.1",
+    "@eslint/js": "^9.27.0",
     "@release-it/keep-a-changelog": "^7.0.0",
-    "@types/node": "^22.15.3",
-    "eslint": "^9.25.1",
+    "@types/node": "^22.15.19",
+    "@types/react": "^19.1.4",
+    "@types/react-dom": "^19.1.5",
+    "eslint": "^9.27.0",
     "prettier": "^3.5.3",
     "publint": "^0.3.12",
-    "release-it": "^19.0.1",
-    "tsup": "^8.4.0",
-    "turbo": "^2.5.2",
+    "release-it": "^19.0.2",
+    "tsup": "^8.5.0",
+    "turbo": "^2.5.3",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.31.1",
-    "vitest": "^3.1.2"
+    "typescript-eslint": "^8.32.1",
+    "vitest": "^3.1.4",
+    "zod": "^3.25.7"
   }
 }