> ## Documentation Index
> Fetch the complete documentation index at: https://suvidhajs.is-cool.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> A Structured Approach to Express APIs

<div className="text-center mb-16">
  <h1 className="text-4xl font-bold mb-4">Suvidha</h1>

  <p className="text-xl text-gray-600 dark:text-gray-300">
    Validation • Context • Control
  </p>
</div>

<CardGroup cols={2}>
  <Card title="Type-Safe Middleware" icon="shield-check">
    Chain middleware like LEGO blocks, with type inferred context
    propagation.
  </Card>

  <Card title="Data Validation" icon="certificate">
    Zod-powered type safety for body, params, and queries—without cluttering
    your routes.
  </Card>

  <Card title="Framework Independence" icon="code-branch">
    Keep your business logic clean. No Express.js baggage.
  </Card>

  <Card title="Explicit Control" icon="sliders">
    Fine-grained control over request/response lifecycle.
  </Card>
</CardGroup>

<Tooltip tip="सुविधा - Hindi for 'facility'">Suvidha</Tooltip> is a lightweight,
type-safe Express.js library that adds powerful validation, middleware context
management, and response handling.

> A utility class for building Express.js route handlers with built-in\
> data validation and middleware support. It allows you to define Zod\
> schemas for request parameters, body, and query, and chain middleware
> functions that can enrich the request context.

* **No Rewrites** - Adopt incrementally in existing Express apps.
* **TypeScript Native** - Inferred types end "**guess what's in req**" games.

## Installation

The library is available on the npm registry.

```bash theme={"system"}
npm install suvidha
```

## Quickstart

<Tabs>
  <Tab title="app.ts">
    ```ts theme={"system"}
    import express from "express";
    import { Suvidha, DefaultHandlers, Formatter } from "suvidha";
    import { UserSchema } from "./dto";
    import { authenticate, roleCheck } from "./middlewares";
    import { createUserHandler } from "./controller";

    const app = express();
    app.use(express.json());

    // Configure Suvidha with default handlers
    const suvidha = () => Suvidha.create(new DefaultHandlers());

    // Protected user creation endpoint
    app.post(
        "/users",
        suvidha()
            .use(authenticate)
            .use(roleCheck) // check permissions
            .body(UserSchema) // Validate request body
            .handler(async (req) => {
                // All validation/security passed
                const newUser = req.body; // type of newUser: z.infer<typeof UserSchema>
                const { role } = req.context.user; // type of role: string
                return createUserHandler(newUser, role); // Execute business logic
            }),
    );

    app.listen(3000);
    ```
  </Tab>

  <Tab title="controller.ts">
    ```ts {13, 17} theme={"system"}
    import { Http }  "suvidha";
    import { UserDTO } from "./dto";

    declare function createUser(
        user: UserDTO,
        role: string,
    ): Promise<{ id: string }>;

    // Core business logic handler
    export async function createUserHandler(user: UserDTO, role: string) {
        try {
            const result = await createUser(user, role);
            // return "body with HTTP 201 Created status"
            return Http.Created.body(result);
        } catch (err: any) {
            if (err.code === "DUPLICATE_EMAIL") {
                // throw "body with HTTP 409 Conflict status"
                throw Http.Conflict.body({
                    message: "Email already exists",
                });
            }
            throw err;
        }
    }
    ```
  </Tab>

  <Tab title="middlewares.ts">
    ```ts theme={"system"}
    import { Http, CtxRequest } from "suvidha";

    type User = { role: string };

    // Mock authentication service
    const verify = async (token: string): Promise<User> => {
        // Replace with real auth logic
        return { role: "admin" };
    };

    // Middlewares add data to the context, which will be available
    // to all subsequent middlewares and handlers

    export const authenticate = async (req: CtxRequest) => {
        const token = req.headers["authorization"]!;
        const user = await verify(token).catch((_) => {
            throw new Http.Unauthorized(); // Convert auth failures to 401
        });
        return { user }; // add `{ user }` to context
    };

    // Role guard: Requires admin privileges
    // This middleware expects { user: User } in the context
    export const roleCheck = (req: CtxRequest<{ user: User }>) => {
        if (req.context.user.role !== "admin") {
            throw Http.Forbidden.body({ message: "Admin access required" });
        }
        return {}; // Nothing to add to the context
    };
    ```
  </Tab>

  <Tab title="dto.ts">
    ```ts theme={"system"}
    // data transfer objects
    import { z } from "zod";

    // User validation schema
    export const UserSchema = z.object({
        username: z.string().min(3),
        email: z.string().email(),
        age: z.number().min(13),
    });

    export type UserDTO = z.infer<typeof UserSchema>;
    ```
  </Tab>
</Tabs>

**sample response**

```json theme={"system"}
{
    "status": "success",
    "data": {
        "id": "67adc39ea1ff4e9d60273236"
    },
    "meta": {}
}
```