@venizia/ignis 0.0.5-9 → 0.0.6-0

package/dist/base/controllers/base.d.ts

@@ -1,17 +1,108 @@
-import { Hook, RouteConfig } from '@hono/zod-openapi';
-import { TAuthStrategy, ValueOrPromise } from '@venizia/ignis-helpers';
+import { Hook, OpenAPIHono } from '@hono/zod-openapi';
+import { ValueOrPromise } from '@venizia/ignis-helpers';
 import { Env, Schema } from 'hono';
 import { AbstractController } from './abstract';
-import { TAuthRouteConfig, TLazyRouteHandler, TRouteBindingOptions, TRouteDefinition } from './common/types';
-export declare abstract class BaseController<RouteEnv extends Env = Env, RouteSchema extends Schema = {}, BasePath extends string = '/', ConfigurableOptions extends object = {}> extends AbstractController<RouteEnv, RouteSchema, BasePath, ConfigurableOptions> {
-    bindRoute<RC extends TAuthRouteConfig<RouteConfig>>(opts: {
-        configs: RC;
-    }): TRouteBindingOptions<RC, RouteEnv, RouteSchema, BasePath>;
-    defineRoute<RC extends TAuthRouteConfig<RouteConfig>>(opts: {
-        configs: RC;
-        handler: TLazyRouteHandler<RC, RouteEnv>;
+import { IAuthenticateRouteConfig, IBindRouteOptions, IDefineRouteOptions, TRouteHandler } from './common/types';
+/**
+ * Base controller class with default implementations for route binding.
+ *
+ * Extends {@link AbstractController} with concrete implementations of
+ * {@link bindRoute} and {@link defineRoute}. This is the recommended
+ * base class for creating custom controllers.
+ *
+ * @typeParam RouteEnv - Hono environment type for context variables
+ * @typeParam RouteSchema - Combined schema type for all routes
+ * @typeParam BasePath - Base path prefix for the router
+ * @typeParam ConfigurableOptions - Options passed during configuration
+ * @typeParam Definitions - Route definitions map type for strongly-typed method overrides
+ *
+ * @example
+ * ```typescript
+ * class UserController extends BaseController {
+ *   async binding() {
+ *     // Define routes using defineRoute
+ *     this.defineRoute({
+ *       configs: {
+ *         path: '/',
+ *         method: 'get',
+ *         authenticate: { strategies: ['jwt'] },
+ *         responses: { 200: jsonResponse({ schema: UserSchema }) }
+ *       },
+ *       handler: async (c) => {
+ *         const users = await this.userService.findAll();
+ *         return c.json(users);
+ *       }
+ *     });
+ *
+ *     // Or use fluent bindRoute pattern
+ *     this.bindRoute({
+ *       configs: { path: '/{id}', method: 'get', ... }
+ *     }).to({
+ *       handler: (c) => c.json({ id: c.req.param('id') })
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseController<RouteEnv extends Env = Env, RouteSchema extends Schema = {}, BasePath extends string = '/', ConfigurableOptions extends object = {}, Definitions extends Record<string, IAuthenticateRouteConfig> = Record<string, IAuthenticateRouteConfig>> extends AbstractController<RouteEnv, RouteSchema, BasePath, ConfigurableOptions, Definitions> {
+    /**
+     * Helper method to cast to Hono OpenAPI Handler
+     */
+    toHonoHandler<ResponseType = unknown>(opts: {
+        handler: TRouteHandler<ResponseType, RouteEnv>;
+    }): Parameters<OpenAPIHono<RouteEnv>["openapi"]>[1];
+    /**
+     * Creates a fluent binding for registering a route.
+     *
+     * Returns an object with a `to()` method for attaching the handler.
+     * Useful for conditional binding or when you need access to the binding object.
+     *
+     * @typeParam RouteConfig - The route configuration type
+     * @param opts - Object containing route configuration
+     * @returns Binding options with `to()` method
+     *
+     * @example
+     * ```typescript
+     * const binding = this.bindRoute({ configs: myRouteConfig });
+     * binding.to({ handler: myHandler });
+     * ```
+     */
+    bindRoute<RouteConfig extends IAuthenticateRouteConfig>(opts: {
+        configs: RouteConfig;
+    }): IBindRouteOptions<RouteConfig, RouteEnv, RouteSchema, BasePath>;
+    /**
+     * Defines and registers a route with its handler in a single call.
+     *
+     * This is the preferred method for registering routes. It automatically:
+     * - Processes authentication strategies into middleware
+     * - Adds OpenAPI security requirements
+     * - Tags the route with the controller scope
+     *
+     * @typeParam RouteConfig - The route configuration type
+     * @param opts - Object containing route config, handler, and optional hook
+     * @returns The registered route definition
+     *
+     * @example
+     * ```typescript
+     * this.defineRoute({
+     *   configs: {
+     *     path: '/users',
+     *     method: 'get',
+     *     authenticate: { strategies: ['jwt'] },
+     *     responses: { 200: jsonResponse({ schema: z.array(UserSchema) }) }
+     *   },
+     *   handler: async (c) => {
+     *     const users = await db.select().from(usersTable);
+     *     return c.json(users, 200);
+     *   }
+     * });
+     * ```
+     */
+    defineRoute<RouteConfig extends IAuthenticateRouteConfig, ResponseType = unknown>(opts: {
+        configs: RouteConfig;
+        handler: TRouteHandler<ResponseType, RouteEnv>;
         hook?: Hook<any, RouteEnv, string, ValueOrPromise<any>>;
-    }): TRouteDefinition<RC, RouteEnv, RouteSchema, BasePath>;
+    }): IDefineRouteOptions<RouteConfig, RouteEnv, RouteSchema, BasePath>;
     /**
      * Define a JSX route that renders server-side HTML
      * Scope: [BaseController][defineJSXRoute]
@@ -37,12 +128,10 @@ export declare abstract class BaseController<RouteEnv extends Env = Env, RouteSc
      * @param opts - Route configuration and handler
      * @returns Route definition
      */
-    defineJSXRoute<RC extends RouteConfig & {
-        authStrategies?: Array<TAuthStrategy>;
-    }>(opts: {
-        configs: RC;
-        handler: TLazyRouteHandler<RC, RouteEnv>;
+    defineJSXRoute<RouteConfig extends IAuthenticateRouteConfig, ResponseType = unknown>(opts: {
+        configs: RouteConfig;
+        handler: TRouteHandler<ResponseType, RouteEnv>;
         hook?: Hook<any, RouteEnv, string, ValueOrPromise<any>>;
-    }): TRouteDefinition<RC, RouteEnv, RouteSchema, BasePath>;
+    }): IDefineRouteOptions<RouteConfig, RouteEnv, RouteSchema, BasePath>;
 }
 //# sourceMappingURL=base.d.ts.map

package/dist/base/controllers/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/base/controllers/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB,8BAAsB,cAAc,CAClC,QAAQ,SAAS,GAAG,GAAG,GAAG,EAC1B,WAAW,SAAS,MAAM,GAAG,EAAE,EAC/B,QAAQ,SAAS,MAAM,GAAG,GAAG,EAC7B,mBAAmB,SAAS,MAAM,GAAG,EAAE,CACvC,SAAQ,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,mBAAmB,CAAC;IAEhF,SAAS,CAAC,EAAE,SAAS,gBAAgB,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE;QACxD,OAAO,EAAE,EAAE,CAAC;KACb,GAAG,oBAAoB,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC;IAe7D,WAAW,CAAC,EAAE,SAAS,gBAAgB,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE;QAC1D,OAAO,EAAE,EAAE,CAAC;QACZ,OAAO,EAAE,iBAAiB,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;KACzD,GAAG,gBAAgB,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC;IASzD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,cAAc,CAAC,EAAE,SAAS,WAAW,GAAG;QAAE,cAAc,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAA;KAAE,EAAE,IAAI,EAAE;QACvF,OAAO,EAAE,EAAE,CAAC;QACZ,OAAO,EAAE,iBAAiB,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;KACzD,GAAG,gBAAgB,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC;CAQ1D"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/base/controllers/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,8BAAsB,cAAc,CAClC,QAAQ,SAAS,GAAG,GAAG,GAAG,EAC1B,WAAW,SAAS,MAAM,GAAG,EAAE,EAC/B,QAAQ,SAAS,MAAM,GAAG,GAAG,EAC7B,mBAAmB,SAAS,MAAM,GAAG,EAAE,EACvC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,MAAM,CACnE,MAAM,EACN,wBAAwB,CACzB,CACD,SAAQ,kBAAkB,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,mBAAmB,EAAE,WAAW,CAAC;IAC7F;;OAEG;IACH,aAAa,CAAC,YAAY,GAAG,OAAO,EAAE,IAAI,EAAE;QAAE,OAAO,EAAE,aAAa,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAA;KAAE,GACrE,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAGxE;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,WAAW,SAAS,wBAAwB,EAAE,IAAI,EAAE;QAC5D,OAAO,EAAE,WAAW,CAAC;KACtB,GAAG,iBAAiB,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC;IAcnE;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,WAAW,CAAC,WAAW,SAAS,wBAAwB,EAAE,YAAY,GAAG,OAAO,EAAE,IAAI,EAAE;QACtF,OAAO,EAAE,WAAW,CAAC;QACrB,OAAO,EAAE,aAAa,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;KACzD,GAAG,mBAAmB,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC;IAarE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,cAAc,CAAC,WAAW,SAAS,wBAAwB,EAAE,YAAY,GAAG,OAAO,EAAE,IAAI,EAAE;QACzF,OAAO,EAAE,WAAW,CAAC;QACrB,OAAO,EAAE,aAAa,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;KACzD,GAAG,mBAAmB,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC;CAStE"}

package/dist/base/controllers/base.js

@@ -2,8 +2,70 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseController = void 0;
 const abstract_1 = require("./abstract");
+/**
+ * Base controller class with default implementations for route binding.
+ *
+ * Extends {@link AbstractController} with concrete implementations of
+ * {@link bindRoute} and {@link defineRoute}. This is the recommended
+ * base class for creating custom controllers.
+ *
+ * @typeParam RouteEnv - Hono environment type for context variables
+ * @typeParam RouteSchema - Combined schema type for all routes
+ * @typeParam BasePath - Base path prefix for the router
+ * @typeParam ConfigurableOptions - Options passed during configuration
+ * @typeParam Definitions - Route definitions map type for strongly-typed method overrides
+ *
+ * @example
+ * ```typescript
+ * class UserController extends BaseController {
+ *   async binding() {
+ *     // Define routes using defineRoute
+ *     this.defineRoute({
+ *       configs: {
+ *         path: '/',
+ *         method: 'get',
+ *         authenticate: { strategies: ['jwt'] },
+ *         responses: { 200: jsonResponse({ schema: UserSchema }) }
+ *       },
+ *       handler: async (c) => {
+ *         const users = await this.userService.findAll();
+ *         return c.json(users);
+ *       }
+ *     });
+ *
+ *     // Or use fluent bindRoute pattern
+ *     this.bindRoute({
+ *       configs: { path: '/{id}', method: 'get', ... }
+ *     }).to({
+ *       handler: (c) => c.json({ id: c.req.param('id') })
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class BaseController extends abstract_1.AbstractController {
-    // ------------------------------------------------------------------------------
+    /**
+     * Helper method to cast to Hono OpenAPI Handler
+     */
+    toHonoHandler(opts) {
+        return opts.handler;
+    }
+    /**
+     * Creates a fluent binding for registering a route.
+     *
+     * Returns an object with a `to()` method for attaching the handler.
+     * Useful for conditional binding or when you need access to the binding object.
+     *
+     * @typeParam RouteConfig - The route configuration type
+     * @param opts - Object containing route configuration
+     * @returns Binding options with `to()` method
+     *
+     * @example
+     * ```typescript
+     * const binding = this.bindRoute({ configs: myRouteConfig });
+     * binding.to({ handler: myHandler });
+     * ```
+     */
     bindRoute(opts) {
         const routeConfigs = this.getRouteConfigs({ configs: opts.configs });
         return {
@@ -11,17 +73,44 @@ class BaseController extends abstract_1.AbstractController {
             to: ({ handler }) => {
                 return {
                     configs: routeConfigs,
-                    route: this.router.openapi(routeConfigs, handler),
+                    route: this.router.openapi(routeConfigs, this.toHonoHandler({ handler })),
                 };
             },
         };
     }
-    // ------------------------------------------------------------------------------
+    /**
+     * Defines and registers a route with its handler in a single call.
+     *
+     * This is the preferred method for registering routes. It automatically:
+     * - Processes authentication strategies into middleware
+     * - Adds OpenAPI security requirements
+     * - Tags the route with the controller scope
+     *
+     * @typeParam RouteConfig - The route configuration type
+     * @param opts - Object containing route config, handler, and optional hook
+     * @returns The registered route definition
+     *
+     * @example
+     * ```typescript
+     * this.defineRoute({
+     *   configs: {
+     *     path: '/users',
+     *     method: 'get',
+     *     authenticate: { strategies: ['jwt'] },
+     *     responses: { 200: jsonResponse({ schema: z.array(UserSchema) }) }
+     *   },
+     *   handler: async (c) => {
+     *     const users = await db.select().from(usersTable);
+     *     return c.json(users, 200);
+     *   }
+     * });
+     * ```
+     */
     defineRoute(opts) {
         const routeConfigs = this.getRouteConfigs({ configs: opts.configs });
         return {
             configs: routeConfigs,
-            route: this.router.openapi(routeConfigs, opts.handler, opts.hook),
+            route: this.router.openapi(routeConfigs, this.toHonoHandler({ handler: opts.handler }), opts.hook),
         };
     }
     /**
@@ -53,6 +142,7 @@ class BaseController extends abstract_1.AbstractController {
         const routeConfigs = this.getJSXRouteConfigs({ configs: opts.configs });
         return {
             configs: routeConfigs,
+            // Cast handler: TTypedContext is a type overlay compatible at runtime
             route: this.router.openapi(routeConfigs, opts.handler, opts.hook),
         };
     }

package/dist/base/controllers/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/base/controllers/base.ts"],"names":[],"mappings":";;;AAGA,yCAAgD;AAQhD,MAAsB,cAKpB,SAAQ,6BAAwE;IAChF,iFAAiF;IACjF,SAAS,CAA2C,IAEnD;QACC,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAEzE,OAAO;YACL,OAAO,EAAE,YAAY;YACrB,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;gBAClB,OAAO;oBACL,OAAO,EAAE,YAAY;oBACrB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC;iBAClD,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC;IAED,iFAAiF;IACjF,WAAW,CAA2C,IAIrD;QACC,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAEzE,OAAO;YACL,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC;SAClE,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,cAAc,CAAqE,IAIlF;QACC,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAE5E,OAAO;YACL,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC;SAClE,CAAC;IACJ,CAAC;CACF;AA1ED,wCA0EC"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/base/controllers/base.ts"],"names":[],"mappings":";;;AAGA,yCAAgD;AAQhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAsB,cASpB,SAAQ,6BAAqF;IAC7F;;OAEG;IACH,aAAa,CAAyB,IAAwD;QAC5F,OAAO,IAAI,CAAC,OAA0D,CAAC;IACzE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAA+C,IAEvD;QACC,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAc,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAElF,OAAO;YACL,OAAO,EAAE,YAAY;YACrB,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;gBAClB,OAAO;oBACL,OAAO,EAAE,YAAY;oBACrB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;iBAC1E,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,WAAW,CAAuE,IAIjF;QACC,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAc,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAElF,OAAO;YACL,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,YAAY,EACZ,IAAI,CAAC,aAAa,CAAe,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,EAC3D,IAAI,CAAC,IAAI,CACV;SACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,cAAc,CAAuE,IAIpF;QACC,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAc,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAErF,OAAO;YACL,OAAO,EAAE,YAAY;YACrB,sEAAsE;YACtE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,OAAc,EAAE,IAAI,CAAC,IAAI,CAAC;SACzE,CAAC;IACJ,CAAC;CACF;AApID,wCAoIC"}

package/dist/base/controllers/common/constants.d.ts

@@ -1,6 +1,40 @@
+import { z } from '@hono/zod-openapi';
+import { TResponseHeaders } from './types';
+/**
+ * Standard REST API path constants for CRUD controllers.
+ *
+ * These paths are used by {@link ControllerFactory} to define consistent
+ * endpoint patterns across all generated controllers.
+ *
+ * @example
+ * ```typescript
+ * // Combined with controller basePath:
+ * // basePath: '/users'
+ * // GET /users        → find all (RestPaths.ROOT)
+ * // GET /users/count  → count (RestPaths.COUNT)
+ * // GET /users/find-one → find one (RestPaths.FIND_ONE)
+ * // GET /users/:id    → find by id
+ * ```
+ */
 export declare class RestPaths {
     static readonly ROOT = "/";
     static readonly COUNT = "/count";
     static readonly FIND_ONE = "/find-one";
 }
+export declare const trackableHeaders: z.ZodObject<{
+    "x-request-id": z.ZodOptional<z.ZodString>;
+    "x-request-channel": z.ZodOptional<z.ZodString>;
+    "x-device-info": z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const countableHeaders: z.ZodObject<{
+    "x-request-count": z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const defaultRequestHeaders: z.ZodObject<{
+    "x-request-id": z.ZodOptional<z.ZodString>;
+    "x-request-channel": z.ZodOptional<z.ZodString>;
+    "x-device-info": z.ZodOptional<z.ZodString>;
+    "x-request-count": z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const commonResponseHeaders: TResponseHeaders;
+export declare const findResponseHeaders: TResponseHeaders;
 //# sourceMappingURL=constants.d.ts.map

package/dist/base/controllers/common/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/base/controllers/common/constants.ts"],"names":[],"mappings":"AAAA,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,OAAO;IAC3B,MAAM,CAAC,QAAQ,CAAC,KAAK,YAAY;IACjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,eAAe;CACxC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/base/controllers/common/constants.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,OAAO;IAC3B,MAAM,CAAC,QAAQ,CAAC,KAAK,YAAY;IACjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,eAAe;CACxC;AAKD,eAAO,MAAM,gBAAgB;;;;iBAkB3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;iBAS3B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;iBAAkD,CAAC;AAGrF,eAAO,MAAM,qBAAqB,EAAE,gBAanC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,gBAMjC,CAAC"}

package/dist/base/controllers/common/constants.js

@@ -1,10 +1,82 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RestPaths = void 0;
+exports.findResponseHeaders = exports.commonResponseHeaders = exports.defaultRequestHeaders = exports.countableHeaders = exports.trackableHeaders = exports.RestPaths = void 0;
+const helpers_1 = require("../../../helpers");
+const zod_openapi_1 = require("@hono/zod-openapi");
+/**
+ * Standard REST API path constants for CRUD controllers.
+ *
+ * These paths are used by {@link ControllerFactory} to define consistent
+ * endpoint patterns across all generated controllers.
+ *
+ * @example
+ * ```typescript
+ * // Combined with controller basePath:
+ * // basePath: '/users'
+ * // GET /users        → find all (RestPaths.ROOT)
+ * // GET /users/count  → count (RestPaths.COUNT)
+ * // GET /users/find-one → find one (RestPaths.FIND_ONE)
+ * // GET /users/:id    → find by id
+ * ```
+ */
 class RestPaths {
     static { this.ROOT = '/'; }
     static { this.COUNT = '/count'; }
     static { this.FIND_ONE = '/find-one'; }
 }
 exports.RestPaths = RestPaths;
+// -----------------------------------------------------------------------------
+// Default Headers
+// -----------------------------------------------------------------------------
+exports.trackableHeaders = zod_openapi_1.z.object({
+    [helpers_1.HTTP.Headers.REQUEST_TRACING_ID]: zod_openapi_1.z.string().optional().openapi({
+        description: 'Optional request ID',
+    }),
+    [helpers_1.HTTP.Headers.REQUEST_CHANNEL]: zod_openapi_1.z
+        .string()
+        .optional()
+        .openapi({
+        description: 'Optional request channel',
+        examples: ['channel-1', 'web', 'spos'],
+    }),
+    [helpers_1.HTTP.Headers.REQUEST_DEVICE_INFO]: zod_openapi_1.z
+        .string()
+        .optional()
+        .openapi({
+        description: 'Optional request device info',
+        examples: ['dev-1', 'device-abc', 'd-unique-id'],
+    }),
+});
+exports.countableHeaders = zod_openapi_1.z.object({
+    [helpers_1.HTTP.Headers.REQUEST_COUNT_DATA]: zod_openapi_1.z
+        .string()
+        .optional()
+        .openapi({
+        description: 'Controls response format. When "true" (default): returns {count, data}. When "false": returns data only.',
+        examples: ['true', '1', 'false', '0'],
+    }),
+});
+exports.defaultRequestHeaders = exports.trackableHeaders.extend(exports.countableHeaders.shape);
+// Default response headers (OpenAPI Header Object format)
+exports.commonResponseHeaders = {
+    [helpers_1.HTTP.Headers.REQUEST_TRACING_ID]: {
+        description: 'Echo of the request tracing ID',
+        schema: { type: 'string' },
+    },
+    [helpers_1.HTTP.Headers.RESPONSE_COUNT_DATA]: {
+        description: 'Number of records in response',
+        schema: { type: 'string', examples: ['1', '10', '100'] },
+    },
+    [helpers_1.HTTP.Headers.RESPONSE_FORMAT]: {
+        description: 'Response format indicator',
+        schema: { type: 'string', examples: ['array', 'object'] },
+    },
+};
+exports.findResponseHeaders = {
+    ...exports.commonResponseHeaders,
+    [helpers_1.HTTP.Headers.CONTENT_RANGE]: {
+        description: 'Content range for pagination (e.g., "records 0-24/100")',
+        schema: { type: 'string', examples: ['records 0-24/100', 'records 25-49/100'] },
+    },
+};
 //# sourceMappingURL=constants.js.map

package/dist/base/controllers/common/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/base/controllers/common/constants.ts"],"names":[],"mappings":";;;AAAA,MAAa,SAAS;aACJ,SAAI,GAAG,GAAG,CAAC;aACX,UAAK,GAAG,QAAQ,CAAC;aACjB,aAAQ,GAAG,WAAW,CAAC;;AAHzC,8BAIC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/base/controllers/common/constants.ts"],"names":[],"mappings":";;;AAAA,uCAAiC;AACjC,mDAAsC;AAGtC;;;;;;;;;;;;;;;GAeG;AACH,MAAa,SAAS;aACJ,SAAI,GAAG,GAAG,CAAC;aACX,UAAK,GAAG,QAAQ,CAAC;aACjB,aAAQ,GAAG,WAAW,CAAC;;AAHzC,8BAIC;AAED,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AACnE,QAAA,gBAAgB,GAAG,eAAC,CAAC,MAAM,CAAC;IACvC,CAAC,cAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,eAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC;QAC/D,WAAW,EAAE,qBAAqB;KACnC,CAAC;IACF,CAAC,cAAI,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,eAAC;SAC9B,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CAAC;QACP,WAAW,EAAE,0BAA0B;QACvC,QAAQ,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC;KACvC,CAAC;IACJ,CAAC,cAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,eAAC;SAClC,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CAAC;QACP,WAAW,EAAE,8BAA8B;QAC3C,QAAQ,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,CAAC;KACjD,CAAC;CACL,CAAC,CAAC;AAEU,QAAA,gBAAgB,GAAG,eAAC,CAAC,MAAM,CAAC;IACvC,CAAC,cAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,eAAC;SACjC,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CAAC;QACP,WAAW,EACT,0GAA0G;QAC5G,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC;KACtC,CAAC;CACL,CAAC,CAAC;AAEU,QAAA,qBAAqB,GAAG,wBAAgB,CAAC,MAAM,CAAC,wBAAgB,CAAC,KAAK,CAAC,CAAC;AAErF,0DAA0D;AAC7C,QAAA,qBAAqB,GAAqB;IACrD,CAAC,cAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE;QACjC,WAAW,EAAE,gCAAgC;QAC7C,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC3B;IACD,CAAC,cAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE;QAClC,WAAW,EAAE,+BAA+B;QAC5C,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE;KACzD;IACD,CAAC,cAAI,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE;QAC9B,WAAW,EAAE,2BAA2B;QACxC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE;KAC1D;CACF,CAAC;AAEW,QAAA,mBAAmB,GAAqB;IACnD,GAAG,6BAAqB;IACxB,CAAC,cAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE;QAC5B,WAAW,EAAE,yDAAyD;QACtE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,EAAE;KAChF;CACF,CAAC"}