@alis-kit/routers 1.0.0

package/dist/exceptions/UnauthorizedException.js

@@ -0,0 +1,28 @@
+import { BaseException } from "./BaseException.js";
+/**
+ * Exception for 401 Unauthorized responses.
+ *
+ * Digunakan ketika authentication diperlukan tapi tidak disertakan
+ * atau token tidak valid. Berbeda dengan ForbiddenException (403)
+ * yang berarti user sudah terautentikasi tapi tidak punya akses.
+ *
+ * @example
+ * ```typescript
+ * import { UnauthorizedException } from "@alis-kit/routers";
+ *
+ * class AuthController {
+ *   @PostMapping("/refresh")
+ *   async refresh(@Req() req: express.Request) {
+ *     const token = req.headers["authorization"];
+ *     if (!token) {
+ *       throw new UnauthorizedException("Access token is required");
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class UnauthorizedException extends BaseException {
+    status = 401;
+    code = "UNAUTHORIZED";
+}
+//# sourceMappingURL=UnauthorizedException.js.map

package/dist/exceptions/UnauthorizedException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnauthorizedException.js","sourceRoot":"","sources":["../../exceptions/UnauthorizedException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,MAAM,GAAG,GAAG,CAAC;IACb,IAAI,GAAG,cAAc,CAAC;CAChC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { RouterKit } from "./core/RouterKit.js";
+export { ReqController } from "./decorators/controller/ReqController.js";
+export { GetMapping, PostMapping, PutMapping, PatchMapping, DeleteMapping, } from "./decorators/mapping/index.js";
+export { Body, Query, Param, Req, Cookie, Reply } from "./decorators/parameter/index.js";
+export { UseMiddleware, HttpStatus } from "./decorators/method/index.js";
+export { BaseException } from "./exceptions/BaseException.js";
+export { BadRequestException } from "./exceptions/BadRequestException.js";
+export { UnauthorizedException } from "./exceptions/UnauthorizedException.js";
+export { ForbiddenException } from "./exceptions/ForbiddenException.js";
+export { NotFoundException } from "./exceptions/NotFoundException.js";
+export { ConflictException } from "./exceptions/ConflictException.js";
+export { ServerErrorException } from "./exceptions/ServerErrorException.js";
+export { CookieSetter } from "./cookie/CookieSetter.js";
+export type { Framework, AuthType, HttpMethod, MiddlewareFn, HandlerFn, Class, CookieOptions, SwaggerConfig, LoggerConfig, RouterKitConfig, ControllerOptions, MappingOptions, } from "./types/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AAGzE,OAAO,EACL,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAGzF,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,YAAY,EACV,SAAS,EACT,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,SAAS,EACT,KAAK,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+// ── Core ──────────────────────────────────────────────────────────
+export { RouterKit } from "./core/RouterKit.js";
+// ── Decorators: Controller ────────────────────────────────────────
+export { ReqController } from "./decorators/controller/ReqController.js";
+// ── Decorators: Mapping ───────────────────────────────────────────
+export { GetMapping, PostMapping, PutMapping, PatchMapping, DeleteMapping, } from "./decorators/mapping/index.js";
+// ── Decorators: Parameter ─────────────────────────────────────────
+export { Body, Query, Param, Req, Cookie, Reply } from "./decorators/parameter/index.js";
+// ── Decorators: Method ────────────────────────────────────────────
+export { UseMiddleware, HttpStatus } from "./decorators/method/index.js";
+// ── Exceptions ────────────────────────────────────────────────────
+export { BaseException } from "./exceptions/BaseException.js";
+export { BadRequestException } from "./exceptions/BadRequestException.js";
+export { UnauthorizedException } from "./exceptions/UnauthorizedException.js";
+export { ForbiddenException } from "./exceptions/ForbiddenException.js";
+export { NotFoundException } from "./exceptions/NotFoundException.js";
+export { ConflictException } from "./exceptions/ConflictException.js";
+export { ServerErrorException } from "./exceptions/ServerErrorException.js";
+// ── Cookie ────────────────────────────────────────────────────────
+export { CookieSetter } from "./cookie/CookieSetter.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,qEAAqE;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AAEzE,qEAAqE;AACrE,OAAO,EACL,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,+BAA+B,CAAC;AAEvC,qEAAqE;AACrE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AAEzF,qEAAqE;AACrE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAEzE,qEAAqE;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAE5E,qEAAqE;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/swagger/SwaggerGenerator.d.ts

@@ -0,0 +1,63 @@
+import type { ZodSchema } from "zod";
+import type { OpenAPISpec, OpenAPISchema, ResolvedRoute, SwaggerConfig } from "../types/index.js";
+/**
+ * Generates an OpenAPI 3.0 specification dari resolved route metadata.
+ *
+ * Mengkonversi decorator metadata + Zod schemas menjadi spec OpenAPI
+ * yang bisa disajikan lewat Swagger UI. Mendukung grouping by tag,
+ * sorting, dan extract parameter dari Zod schemas.
+ *
+ * @example
+ * ```typescript
+ * import { SwaggerGenerator } from "@alis-kit/routers";
+ *
+ * const spec = SwaggerGenerator.generate(resolvedRoutes, {
+ *   title: "My API",
+ *   version: "1.0.0",
+ *   sortBy: "path",
+ * });
+ *
+ * console.log(spec); // OpenAPI 3.0 spec object
+ * ```
+ */
+export declare class SwaggerGenerator {
+    /**
+     * Generates a complete OpenAPI 3.0 spec from resolved routes.
+     *
+     * @param routes - Array of resolved route information dari RouteResolver
+     * @param config - Swagger configuration (title, version, sort order, search)
+     * @returns Complete OpenAPI specification object
+     */
+    static generate(routes: ResolvedRoute[], config: SwaggerConfig): OpenAPISpec;
+    /**
+     * Builds an OpenAPI operation object from a single resolved route.
+     * Includes parameter definitions, request body (from Zod), and responses.
+     */
+    private static buildOperation;
+    /**
+     * Converts a Zod schema to an array of OpenAPI query parameters.
+     * Mengekstrak setiap field dari Zod Object jadi parameter individual.
+     */
+    private static zodToQueryParams;
+    /**
+     * Converts a Zod object schema to an OpenAPI schema object.
+     * Public karena dipakai juga oleh SwaggerUI untuk body schema.
+     */
+    static zodToOpenAPI(schema: ZodSchema): OpenAPISchema;
+    /**
+     * Converts an individual Zod field type to OpenAPI schema representation.
+     * Handles: optional, nullable, default, string, number, boolean, array, object, enum.
+     */
+    private static zodFieldToOpenAPI;
+    /**
+     * Attempts to extract the shape object from a Zod schema.
+     * Supports both ZodObject and ZodEffects (coerce) wrapping.
+     */
+    private static getZodShape;
+    /**
+     * Checks if a Zod field is optional or has a default value.
+     * Used to determine `required` in OpenAPI parameter definitions.
+     */
+    private static isOptional;
+}
+//# sourceMappingURL=SwaggerGenerator.d.ts.map

package/dist/swagger/SwaggerGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwaggerGenerator.d.ts","sourceRoot":"","sources":["../../swagger/SwaggerGenerator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAkF,MAAM,KAAK,CAAC;AACrH,OAAO,KAAK,EACV,WAAW,EAKX,aAAa,EACb,aAAa,EACb,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW;IAwC5E;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAyE7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwB/B;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,aAAa;IA4BrD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAmDhC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAW1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;CAS1B"}

package/dist/swagger/SwaggerGenerator.js

@@ -0,0 +1,266 @@
+/**
+ * Generates an OpenAPI 3.0 specification dari resolved route metadata.
+ *
+ * Mengkonversi decorator metadata + Zod schemas menjadi spec OpenAPI
+ * yang bisa disajikan lewat Swagger UI. Mendukung grouping by tag,
+ * sorting, dan extract parameter dari Zod schemas.
+ *
+ * @example
+ * ```typescript
+ * import { SwaggerGenerator } from "@alis-kit/routers";
+ *
+ * const spec = SwaggerGenerator.generate(resolvedRoutes, {
+ *   title: "My API",
+ *   version: "1.0.0",
+ *   sortBy: "path",
+ * });
+ *
+ * console.log(spec); // OpenAPI 3.0 spec object
+ * ```
+ */
+export class SwaggerGenerator {
+    /**
+     * Generates a complete OpenAPI 3.0 spec from resolved routes.
+     *
+     * @param routes - Array of resolved route information dari RouteResolver
+     * @param config - Swagger configuration (title, version, sort order, search)
+     * @returns Complete OpenAPI specification object
+     */
+    static generate(routes, config) {
+        const paths = {};
+        const tagSet = new Set();
+        const swaggerRoutes = routes.filter((r) => r.swagger !== false);
+        const sortedRoutes = [...swaggerRoutes].sort((a, b) => {
+            if (config.sortBy === "method") {
+                return a.method.localeCompare(b.method) || a.fullPath.localeCompare(b.fullPath);
+            }
+            return a.fullPath.localeCompare(b.fullPath) || a.method.localeCompare(b.method);
+        });
+        for (const route of sortedRoutes) {
+            const tag = route.routeOptions.tag ?? route.controllerTag;
+            tagSet.add(tag);
+            const openApiPath = route.fullPath.replace(/:(\w+)/g, "{$1}");
+            if (!paths[openApiPath]) {
+                paths[openApiPath] = {};
+            }
+            const operation = SwaggerGenerator.buildOperation(route, tag);
+            paths[openApiPath][route.method] = operation;
+        }
+        const tags = [...tagSet].sort().map((name) => ({ name }));
+        return {
+            openapi: "3.0.0",
+            info: {
+                title: config.title ?? "API Documentation",
+                version: config.version ?? "1.0.0",
+            },
+            paths,
+            tags,
+        };
+    }
+    /**
+     * Builds an OpenAPI operation object from a single resolved route.
+     * Includes parameter definitions, request body (from Zod), and responses.
+     */
+    static buildOperation(route, tag) {
+        const operation = {
+            tags: [tag],
+            summary: route.routeOptions.summary,
+            description: route.routeOptions.description,
+            responses: {
+                [String(route.statusCode)]: {
+                    description: "Successful response",
+                    content: {
+                        "application/json": {
+                            schema: {
+                                type: "object",
+                                properties: {
+                                    message: { type: "string" },
+                                    data: { type: "object" },
+                                },
+                            },
+                        },
+                    },
+                },
+                "400": { description: "Bad Request" },
+                "500": { description: "Internal Server Error" },
+            },
+        };
+        const parameters = [];
+        let requestBody;
+        for (const param of route.params) {
+            switch (param.type) {
+                case "body":
+                    if (param.schema) {
+                        requestBody = {
+                            required: true,
+                            content: {
+                                "application/json": {
+                                    schema: SwaggerGenerator.zodToOpenAPI(param.schema),
+                                },
+                            },
+                        };
+                    }
+                    break;
+                case "query":
+                    if (param.schema) {
+                        const queryParams = SwaggerGenerator.zodToQueryParams(param.schema);
+                        parameters.push(...queryParams);
+                    }
+                    break;
+                case "param":
+                    if (param.key) {
+                        parameters.push({
+                            name: param.key,
+                            in: "path",
+                            required: true,
+                            schema: { type: "string" },
+                        });
+                    }
+                    break;
+            }
+        }
+        if (parameters.length > 0) {
+            operation.parameters = parameters;
+        }
+        if (requestBody) {
+            operation.requestBody = requestBody;
+        }
+        return operation;
+    }
+    /**
+     * Converts a Zod schema to an array of OpenAPI query parameters.
+     * Mengekstrak setiap field dari Zod Object jadi parameter individual.
+     */
+    static zodToQueryParams(schema) {
+        const params = [];
+        try {
+            const shape = SwaggerGenerator.getZodShape(schema);
+            if (shape) {
+                for (const [key, fieldSchema] of Object.entries(shape)) {
+                    const zodField = fieldSchema;
+                    const isOptional = SwaggerGenerator.isOptional(zodField);
+                    params.push({
+                        name: key,
+                        in: "query",
+                        required: !isOptional,
+                        schema: SwaggerGenerator.zodFieldToOpenAPI(zodField),
+                    });
+                }
+            }
+        }
+        catch {
+            // Silently skip unparseable schemas
+        }
+        return params;
+    }
+    /**
+     * Converts a Zod object schema to an OpenAPI schema object.
+     * Public karena dipakai juga oleh SwaggerUI untuk body schema.
+     */
+    static zodToOpenAPI(schema) {
+        try {
+            const shape = SwaggerGenerator.getZodShape(schema);
+            if (shape) {
+                const properties = {};
+                const required = [];
+                for (const [key, fieldSchema] of Object.entries(shape)) {
+                    const zodField = fieldSchema;
+                    properties[key] = SwaggerGenerator.zodFieldToOpenAPI(zodField);
+                    if (!SwaggerGenerator.isOptional(zodField)) {
+                        required.push(key);
+                    }
+                }
+                return {
+                    type: "object",
+                    properties,
+                    ...(required.length > 0 ? { required } : {}),
+                };
+            }
+        }
+        catch {
+            // Fallback
+        }
+        return { type: "object" };
+    }
+    /**
+     * Converts an individual Zod field type to OpenAPI schema representation.
+     * Handles: optional, nullable, default, string, number, boolean, array, object, enum.
+     */
+    static zodFieldToOpenAPI(schema) {
+        const def = schema._def;
+        const typeName = def?.typeName;
+        if (typeName === "ZodOptional") {
+            const innerDef = def;
+            return SwaggerGenerator.zodFieldToOpenAPI(innerDef.innerType);
+        }
+        if (typeName === "ZodNullable") {
+            const innerDef = def;
+            const inner = SwaggerGenerator.zodFieldToOpenAPI(innerDef.innerType);
+            return { ...inner, nullable: true };
+        }
+        if (typeName === "ZodDefault") {
+            const innerDef = def;
+            const inner = SwaggerGenerator.zodFieldToOpenAPI(innerDef.innerType);
+            return { ...inner, default: def._def.defaultValue() };
+        }
+        if (typeName === "ZodEffects") {
+            const innerSchema = def.schema;
+            if (innerSchema) {
+                return SwaggerGenerator.zodFieldToOpenAPI(innerSchema);
+            }
+        }
+        switch (typeName) {
+            case "ZodString":
+                return { type: "string" };
+            case "ZodNumber":
+                return { type: "number" };
+            case "ZodBoolean":
+                return { type: "boolean" };
+            case "ZodArray": {
+                const arrayDef = def;
+                return {
+                    type: "array",
+                    items: SwaggerGenerator.zodFieldToOpenAPI(arrayDef.type),
+                };
+            }
+            case "ZodObject": {
+                return SwaggerGenerator.zodToOpenAPI(schema);
+            }
+            case "ZodEnum": {
+                const enumValues = def.values;
+                return { type: "string", enum: enumValues };
+            }
+            default:
+                return { type: "string" };
+        }
+    }
+    /**
+     * Attempts to extract the shape object from a Zod schema.
+     * Supports both ZodObject and ZodEffects (coerce) wrapping.
+     */
+    static getZodShape(schema) {
+        const zodObj = schema;
+        if (zodObj?.shape && typeof zodObj.shape === "object") {
+            return zodObj.shape;
+        }
+        if (zodObj?._def?.shape && typeof zodObj._def.shape === "function") {
+            return zodObj._def.shape();
+        }
+        return null;
+    }
+    /**
+     * Checks if a Zod field is optional or has a default value.
+     * Used to determine `required` in OpenAPI parameter definitions.
+     */
+    static isOptional(schema) {
+        const typeName = schema._def?.typeName;
+        if (typeName === "ZodOptional" || typeName === "ZodDefault")
+            return true;
+        if (typeName === "ZodNullable") {
+            const innerDef = schema._def;
+            return SwaggerGenerator.isOptional(innerDef.innerType);
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=SwaggerGenerator.js.map

package/dist/swagger/SwaggerGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwaggerGenerator.js","sourceRoot":"","sources":["../../swagger/SwaggerGenerator.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,gBAAgB;IAC3B;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAuB,EAAE,MAAqB;QAC5D,MAAM,KAAK,GAAoC,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;QAEjC,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC;QAEhE,MAAM,YAAY,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACpD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC/B,OAAO,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YAClF,CAAC;YACD,OAAO,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC;QAEH,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,KAAK,CAAC,YAAY,CAAC,GAAG,IAAI,KAAK,CAAC,aAAa,CAAC;YAC1D,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAEhB,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAE9D,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;gBACxB,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;YAC1B,CAAC;YAED,MAAM,SAAS,GAAG,gBAAgB,CAAC,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC9D,KAAK,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;QAC/C,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAE1D,OAAO;YACL,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE;gBACJ,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,mBAAmB;gBAC1C,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;aACnC;YACD,KAAK;YACL,IAAI;SACL,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,cAAc,CAAC,KAAoB,EAAE,GAAW;QAC7D,MAAM,SAAS,GAAqB;YAClC,IAAI,EAAE,CAAC,GAAG,CAAC;YACX,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,OAAO;YACnC,WAAW,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW;YAC3C,SAAS,EAAE;gBACT,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,EAAE;oBAC1B,WAAW,EAAE,qBAAqB;oBAClC,OAAO,EAAE;wBACP,kBAAkB,EAAE;4BAClB,MAAM,EAAE;gCACN,IAAI,EAAE,QAAQ;gCACd,UAAU,EAAE;oCACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oCAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iCACzB;6BACF;yBACF;qBACF;iBACF;gBACD,KAAK,EAAE,EAAE,WAAW,EAAE,aAAa,EAAE;gBACrC,KAAK,EAAE,EAAE,WAAW,EAAE,uBAAuB,EAAE;aAChD;SACF,CAAC;QAEF,MAAM,UAAU,GAAuB,EAAE,CAAC;QAC1C,IAAI,WAA2C,CAAC;QAEhD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACjC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;gBACnB,KAAK,MAAM;oBACT,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;wBACjB,WAAW,GAAG;4BACZ,QAAQ,EAAE,IAAI;4BACd,OAAO,EAAE;gCACP,kBAAkB,EAAE;oCAClB,MAAM,EAAE,gBAAgB,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC;iCACpD;6BACF;yBACF,CAAC;oBACJ,CAAC;oBACD,MAAM;gBAER,KAAK,OAAO;oBACV,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;wBACjB,MAAM,WAAW,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;wBACpE,UAAU,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;oBAClC,CAAC;oBACD,MAAM;gBAER,KAAK,OAAO;oBACV,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;wBACd,UAAU,CAAC,IAAI,CAAC;4BACd,IAAI,EAAE,KAAK,CAAC,GAAG;4BACf,EAAE,EAAE,MAAM;4BACV,QAAQ,EAAE,IAAI;4BACd,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;yBAC3B,CAAC,CAAC;oBACL,CAAC;oBACD,MAAM;YACV,CAAC;QACH,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,SAAS,CAAC,UAAU,GAAG,UAAU,CAAC;QACpC,CAAC;QACD,IAAI,WAAW,EAAE,CAAC;YAChB,SAAS,CAAC,WAAW,GAAG,WAAW,CAAC;QACtC,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,gBAAgB,CAAC,MAAiB;QAC/C,MAAM,MAAM,GAAuB,EAAE,CAAC;QAEtC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACnD,IAAI,KAAK,EAAE,CAAC;gBACV,KAAK,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACvD,MAAM,QAAQ,GAAG,WAAyB,CAAC;oBAC3C,MAAM,UAAU,GAAG,gBAAgB,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;oBACzD,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,GAAG;wBACT,EAAE,EAAE,OAAO;wBACX,QAAQ,EAAE,CAAC,UAAU;wBACrB,MAAM,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,QAAQ,CAAC;qBACrD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,MAAiB;QACnC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACnD,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,UAAU,GAAkC,EAAE,CAAC;gBACrD,MAAM,QAAQ,GAAa,EAAE,CAAC;gBAE9B,KAAK,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACvD,MAAM,QAAQ,GAAG,WAAyB,CAAC;oBAC3C,UAAU,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;oBAC/D,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;wBAC3C,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;oBACrB,CAAC;gBACH,CAAC;gBAED,OAAO;oBACL,IAAI,EAAE,QAAQ;oBACd,UAAU;oBACV,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC7C,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,WAAW;QACb,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,iBAAiB,CAAC,MAAkB;QACjD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,MAAM,QAAQ,GAAG,GAAG,EAAE,QAA8B,CAAC;QAErD,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;YAC/B,MAAM,QAAQ,GAAG,GAAgC,CAAC;YAClD,OAAO,gBAAgB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,SAAuB,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;YAC/B,MAAM,QAAQ,GAAG,GAAgC,CAAC;YAClD,MAAM,KAAK,GAAG,gBAAgB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,SAAuB,CAAC,CAAC;YACnF,OAAO,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QACtC,CAAC;QACD,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC9B,MAAM,QAAQ,GAAG,GAAwE,CAAC;YAC1F,MAAM,KAAK,GAAG,gBAAgB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,SAAuB,CAAC,CAAC;YACnF,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAG,GAAyC,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QAC/F,CAAC;QACD,IAAI,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAI,GAAyC,CAAC,MAAM,CAAC;YACtE,IAAI,WAAW,EAAE,CAAC;gBAChB,OAAO,gBAAgB,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;QAED,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,WAAW;gBACd,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC5B,KAAK,WAAW;gBACd,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC5B,KAAK,YAAY;gBACf,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7B,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,MAAM,QAAQ,GAAG,GAA6B,CAAC;gBAC/C,OAAO;oBACL,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,IAAkB,CAAC;iBACvE,CAAC;YACJ,CAAC;YACD,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,OAAO,gBAAgB,CAAC,YAAY,CAAC,MAA8B,CAAC,CAAC;YACvE,CAAC;YACD,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,MAAM,UAAU,GAAI,GAAwC,CAAC,MAAM,CAAC;gBACpE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;YAC9C,CAAC;YACD;gBACE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,WAAW,CAAC,MAAiB;QAC1C,MAAM,MAAM,GAAG,MAA0D,CAAC;QAC1E,IAAI,MAAM,EAAE,KAAK,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACtD,OAAO,MAAM,CAAC,KAAmC,CAAC;QACpD,CAAC;QACD,IAAI,MAAM,EAAE,IAAI,EAAE,KAAK,IAAI,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACnE,OAAQ,MAAM,CAAC,IAAI,CAAC,KAA0C,EAAE,CAAC;QACnE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACK,MAAM,CAAC,UAAU,CAAC,MAAkB;QAC1C,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,EAAE,QAA8B,CAAC;QAC7D,IAAI,QAAQ,KAAK,aAAa,IAAI,QAAQ,KAAK,YAAY;YAAE,OAAO,IAAI,CAAC;QACzE,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;YAC/B,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAiC,CAAC;YAC1D,OAAO,gBAAgB,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAuB,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/swagger/SwaggerUI.d.ts

@@ -0,0 +1,30 @@
+import type { OpenAPISpec, SwaggerConfig } from "../types/index.js";
+/**
+ * Serves Swagger UI for the generated OpenAPI specification.
+ *
+ * Saat ini mendukung Express via `swagger-ui-express`.
+ * Untuk Fastify, disarankan menggunakan `@fastify/swagger-ui` plugin terpisah.
+ *
+ * @example
+ * ```typescript
+ * import { SwaggerUI } from "@alis-kit/routers";
+ *
+ * // Biasanya tidak dipanggil langsung — RouterKit.handleSwagger() yang handle.
+ * SwaggerUI.serve(expressApp, openApiSpec, { enabled: true, path: "/api/docs" });
+ * // Swagger UI available at /api/docs
+ * ```
+ */
+export declare class SwaggerUI {
+    /**
+     * Mounts Swagger UI on the given Express app at the configured path.
+     *
+     * Menggunakan dynamic `require()` agar `swagger-ui-express` tidak perlu
+     * diinstall jika Swagger tidak dipakai.
+     *
+     * @param app - The Express application instance
+     * @param spec - The OpenAPI specification object (dari SwaggerGenerator)
+     * @param config - Swagger configuration (path, sort options, search)
+     */
+    static serve(app: unknown, spec: OpenAPISpec, config: SwaggerConfig): void;
+}
+//# sourceMappingURL=SwaggerUI.d.ts.map

package/dist/swagger/SwaggerUI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwaggerUI.d.ts","sourceRoot":"","sources":["../../swagger/SwaggerUI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOpE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;CA8B3E"}

package/dist/swagger/SwaggerUI.js

@@ -0,0 +1,52 @@
+/**
+ * Serves Swagger UI for the generated OpenAPI specification.
+ *
+ * Saat ini mendukung Express via `swagger-ui-express`.
+ * Untuk Fastify, disarankan menggunakan `@fastify/swagger-ui` plugin terpisah.
+ *
+ * @example
+ * ```typescript
+ * import { SwaggerUI } from "@alis-kit/routers";
+ *
+ * // Biasanya tidak dipanggil langsung — RouterKit.handleSwagger() yang handle.
+ * SwaggerUI.serve(expressApp, openApiSpec, { enabled: true, path: "/api/docs" });
+ * // Swagger UI available at /api/docs
+ * ```
+ */
+export class SwaggerUI {
+    /**
+     * Mounts Swagger UI on the given Express app at the configured path.
+     *
+     * Menggunakan dynamic `require()` agar `swagger-ui-express` tidak perlu
+     * diinstall jika Swagger tidak dipakai.
+     *
+     * @param app - The Express application instance
+     * @param spec - The OpenAPI specification object (dari SwaggerGenerator)
+     * @param config - Swagger configuration (path, sort options, search)
+     */
+    static serve(app, spec, config) {
+        const path = config.path ?? "/api/docs";
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const swaggerUi = require("swagger-ui-express");
+            const swaggerApp = app;
+            const options = {
+                explorer: true,
+                swaggerOptions: {
+                    docExpansion: "none",
+                    filter: true,
+                    showRequestDuration: true,
+                    tagsSorter: "alpha",
+                    operationsSorter: config.sortBy === "method" ? "method" : "alpha",
+                },
+            };
+            swaggerApp.use(path, swaggerUi.serve, swaggerUi.setup(spec, options));
+            console.log(`Swagger UI available at ${path}`);
+        }
+        catch {
+            console.warn("swagger-ui-express is not installed. Install it to enable Swagger UI:\n" +
+                "   npm install swagger-ui-express");
+        }
+    }
+}
+//# sourceMappingURL=SwaggerUI.js.map

package/dist/swagger/SwaggerUI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwaggerUI.js","sourceRoot":"","sources":["../../swagger/SwaggerUI.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,SAAS;IACpB;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,CAAC,GAAY,EAAE,IAAiB,EAAE,MAAqB;QACjE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,WAAW,CAAC;QAExC,IAAI,CAAC;YACH,iEAAiE;YACjE,MAAM,SAAS,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;YAEhD,MAAM,UAAU,GAAG,GAAiB,CAAC;YAErC,MAAM,OAAO,GAAG;gBACd,QAAQ,EAAE,IAAI;gBACd,cAAc,EAAE;oBACd,YAAY,EAAE,MAAM;oBACpB,MAAM,EAAE,IAAI;oBACZ,mBAAmB,EAAE,IAAI;oBACzB,UAAU,EAAE,OAAO;oBACnB,gBAAgB,EAAE,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO;iBAClE;aACF,CAAC;YAEF,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;YAEtE,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,IAAI,CACV,yEAAyE;gBACvE,mCAAmC,CACtC,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}