@forinda/kickjs-http 0.5.0 → 0.6.0

package/dist/application.d.ts

@@ -1,6 +1,6 @@
 import http from 'node:http';
 import { RequestHandler, Express } from 'express';
-import { AppModuleClass, AppAdapter } from '@forinda/kickjs-core';
+import { AppModuleClass, AppAdapter, KickPlugin } from '@forinda/kickjs-core';
 
 /**
  * A middleware entry in the declarative pipeline.
@@ -43,6 +43,8 @@ interface ApplicationOptions {
      *   requestId(), express.json({ limit: '100kb' })
      */
     middleware?: MiddlewareEntry[];
+    /** Plugins that bundle modules, adapters, middleware, and DI bindings */
+    plugins?: KickPlugin[];
     /** Express `trust proxy` setting */
     trustProxy?: boolean | number | string | ((ip: string, hopIndex: number) => boolean);
     /** Maximum JSON body size (only used when middleware is not provided) */
@@ -58,6 +60,7 @@ declare class Application {
     private container;
     private httpServer;
     private adapters;
+    private plugins;
     constructor(options: ApplicationOptions);
     /**
      * Full setup pipeline:

package/dist/application.js

@@ -1,6 +1,6 @@
 import {
   Application
-} from "./chunk-OKB76LY2.js";
+} from "./chunk-YRCR6Z5C.js";
 import "./chunk-35NUARK7.js";
 import "./chunk-3NEDJA3J.js";
 import "./chunk-WCQVDF3K.js";

package/dist/bootstrap.js

@@ -1,7 +1,7 @@
 import {
   bootstrap
-} from "./chunk-D76WCWAW.js";
-import "./chunk-OKB76LY2.js";
+} from "./chunk-W35YEQOE.js";
+import "./chunk-YRCR6Z5C.js";
 import "./chunk-35NUARK7.js";
 import "./chunk-3NEDJA3J.js";
 import "./chunk-WCQVDF3K.js";

package/dist/{chunk-VFVMIFNZ.js → chunk-E552HYEB.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-RPN7UFUO.js";
 import {
   RequestContext
-} from "./chunk-LQ6RSWMX.js";
+} from "./chunk-Y5ZSC2FB.js";
 import {
   __name
 } from "./chunk-WCQVDF3K.js";
@@ -66,4 +66,4 @@ export {
   getControllerPath,
   buildRoutes
 };
-//# sourceMappingURL=chunk-VFVMIFNZ.js.map
+//# sourceMappingURL=chunk-E552HYEB.js.map

package/dist/{chunk-D76WCWAW.js → chunk-W35YEQOE.js}

@@ -1,6 +1,6 @@
 import {
   Application
-} from "./chunk-OKB76LY2.js";
+} from "./chunk-YRCR6Z5C.js";
 import {
   __name,
   __require
@@ -57,4 +57,4 @@ __name(bootstrap, "bootstrap");
 export {
   bootstrap
 };
-//# sourceMappingURL=chunk-D76WCWAW.js.map
+//# sourceMappingURL=chunk-W35YEQOE.js.map

package/dist/{chunk-VXX2Y3TA.js → chunk-WYY34UWG.js}

@@ -130,4 +130,4 @@ export {
   parseQuery,
   buildQueryParams
 };
-//# sourceMappingURL=chunk-VXX2Y3TA.js.map
+//# sourceMappingURL=chunk-WYY34UWG.js.map

package/dist/chunk-WYY34UWG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/query/types.ts","../src/query/parse-query.ts"],"sourcesContent":["/** Supported filter operators for query string parsing */\nexport type FilterOperator =\n  | 'eq'\n  | 'neq'\n  | 'gt'\n  | 'gte'\n  | 'lt'\n  | 'lte'\n  | 'between'\n  | 'in'\n  | 'contains'\n  | 'starts'\n  | 'ends'\n\nexport const FILTER_OPERATORS = new Set<string>([\n  'eq',\n  'neq',\n  'gt',\n  'gte',\n  'lt',\n  'lte',\n  'between',\n  'in',\n  'contains',\n  'starts',\n  'ends',\n])\n\nexport interface FilterItem {\n  field: string\n  operator: FilterOperator\n  value: string\n}\n\nexport interface SortItem {\n  field: string\n  direction: 'asc' | 'desc'\n}\n\nexport interface PaginationParams {\n  page: number\n  limit: number\n  offset: number\n}\n\n/**\n * The result of parsing a query string. ORM-agnostic — pass this to\n * a query builder adapter (Drizzle, Prisma, Sequelize, etc.) to produce\n * database-specific query objects.\n */\nexport interface ParsedQuery {\n  filters: FilterItem[]\n  sort: SortItem[]\n  pagination: PaginationParams\n  search: string\n}\n\n/**\n * Restrict which fields can be filtered, sorted, or searched.\n * Fields not in the allow-list are silently ignored.\n */\nexport interface QueryFieldConfig {\n  filterable?: string[]\n  sortable?: string[]\n  searchable?: string[]\n}\n\n/** Standardized paginated response shape */\nexport interface PaginatedResponse<T = any> {\n  data: T[]\n  meta: {\n    page: number\n    limit: number\n    total: number\n    totalPages: number\n    hasNext: boolean\n    hasPrev: boolean\n  }\n}\n\n/**\n * Interface for ORM-specific query builder adapters.\n * Implement this to translate a `ParsedQuery` into your ORM's query format.\n *\n * @example\n * ```ts\n * // Drizzle adapter\n * class DrizzleQueryAdapter implements QueryBuilderAdapter<DrizzleQueryResult> {\n *   build(parsed: ParsedQuery, config: DrizzleConfig): DrizzleQueryResult {\n *     // Convert filters → Drizzle SQL conditions\n *     // Convert sort → Drizzle orderBy\n *     return { where, orderBy, limit, offset }\n *   }\n * }\n *\n * // Prisma adapter\n * class PrismaQueryAdapter implements QueryBuilderAdapter<PrismaQueryResult> {\n *   build(parsed: ParsedQuery, config: PrismaConfig): PrismaQueryResult {\n *     return { where, orderBy, skip, take }\n *   }\n * }\n * ```\n */\nexport interface QueryBuilderAdapter<TResult = any, TConfig = any> {\n  /** Human-readable name for debugging */\n  readonly name: string\n\n  /**\n   * Convert a ParsedQuery into an ORM-specific query object.\n   * @param parsed - The ORM-agnostic parsed query\n   * @param config - ORM-specific configuration (column maps, search columns, etc.)\n   */\n  build(parsed: ParsedQuery, config: TConfig): TResult\n}\n","import {\n  FILTER_OPERATORS,\n  type FilterItem,\n  type FilterOperator,\n  type SortItem,\n  type PaginationParams,\n  type ParsedQuery,\n  type QueryFieldConfig,\n} from './types'\n\nconst MAX_SEARCH_LENGTH = 200\nconst DEFAULT_PAGE = 1\nconst DEFAULT_LIMIT = 20\nconst MAX_LIMIT = 100\n\n// ── Individual parsers ──────────────────────────────────────────────────\n\n/** Parse filter strings like \"status:eq:active\" into structured objects */\nexport function parseFilters(\n  filterParam: string | string[] | undefined,\n  allowedFields?: string[],\n): FilterItem[] {\n  if (!filterParam) return []\n\n  const items = Array.isArray(filterParam) ? filterParam : [filterParam]\n  const results: FilterItem[] = []\n  const allowed = allowedFields ? new Set(allowedFields) : null\n\n  for (const item of items) {\n    // Split on first two colons only — value may contain colons (e.g. timestamps)\n    const firstColon = item.indexOf(':')\n    if (firstColon === -1) continue\n\n    const secondColon = item.indexOf(':', firstColon + 1)\n    if (secondColon === -1) continue\n\n    const field = item.slice(0, firstColon)\n    const operator = item.slice(firstColon + 1, secondColon)\n    const value = item.slice(secondColon + 1)\n\n    if (!field || !value) continue\n    if (!FILTER_OPERATORS.has(operator)) continue\n    if (allowed && !allowed.has(field)) continue\n\n    results.push({ field, operator: operator as FilterOperator, value })\n  }\n\n  return results\n}\n\n/** Parse sort strings like \"firstName:asc\" into structured objects */\nexport function parseSort(\n  sortParam: string | string[] | undefined,\n  allowedFields?: string[],\n): SortItem[] {\n  if (!sortParam) return []\n\n  const items = Array.isArray(sortParam) ? sortParam : [sortParam]\n  const results: SortItem[] = []\n  const allowed = allowedFields ? new Set(allowedFields) : null\n\n  for (const item of items) {\n    // Split on last colon so field names with colons work\n    const lastColon = item.lastIndexOf(':')\n    if (lastColon === -1) continue\n\n    const field = item.slice(0, lastColon)\n    const dir = item.slice(lastColon + 1).toLowerCase()\n\n    if (!field) continue\n    if (dir !== 'asc' && dir !== 'desc') continue\n    if (allowed && !allowed.has(field)) continue\n\n    results.push({ field, direction: dir })\n  }\n\n  return results\n}\n\n/** Parse page/limit into pagination with computed offset */\nexport function parsePagination(params: {\n  page?: string | number\n  limit?: string | number\n}): PaginationParams {\n  let page =\n    typeof params.page === 'string' ? parseInt(params.page, 10) : (params.page ?? DEFAULT_PAGE)\n  let limit =\n    typeof params.limit === 'string' ? parseInt(params.limit, 10) : (params.limit ?? DEFAULT_LIMIT)\n\n  if (isNaN(page) || page < 1) page = DEFAULT_PAGE\n  if (isNaN(limit) || limit < 1) limit = DEFAULT_LIMIT\n  if (limit > MAX_LIMIT) limit = MAX_LIMIT\n\n  return { page, limit, offset: (page - 1) * limit }\n}\n\n/** Sanitize and truncate search query */\nexport function parseSearchQuery(q: string | undefined): string {\n  if (!q) return ''\n  return q.trim().slice(0, MAX_SEARCH_LENGTH)\n}\n\n// ── Combined parser ─────────────────────────────────────────────────────\n\n/**\n * Parse a raw Express query object into a structured, ORM-agnostic ParsedQuery.\n *\n * @param query - Raw query string object from `req.query` or Zod-validated object\n * @param fieldConfig - Optional field restrictions (whitelist filterable/sortable/searchable)\n *\n * @example\n * ```ts\n * // In a controller\n * @Get('/')\n * async list(ctx: RequestContext) {\n *   const parsed = parseQuery(ctx.query, {\n *     filterable: ['status', 'priority'],\n *     sortable: ['createdAt', 'title'],\n *   })\n *   // Pass to your ORM query builder adapter\n *   const q = drizzleAdapter.build(parsed, { columns, searchColumns })\n * }\n * ```\n *\n * Query string format:\n * - Filters: `?filter=field:operator:value` (repeatable)\n * - Sort: `?sort=field:asc|desc` (repeatable)\n * - Pagination: `?page=1&limit=20`\n * - Search: `?q=search+term`\n *\n * Filter operators: eq, neq, gt, gte, lt, lte, between, in, contains, starts, ends\n */\nexport function parseQuery(\n  query: Record<string, any>,\n  fieldConfig?: QueryFieldConfig,\n): ParsedQuery {\n  return {\n    filters: parseFilters(query.filter, fieldConfig?.filterable),\n    sort: parseSort(query.sort, fieldConfig?.sortable),\n    pagination: parsePagination({ page: query.page, limit: query.limit }),\n    search: parseSearchQuery(query.q),\n  }\n}\n\n// ── Query URL builder (for client-side or testing) ──────────────────────\n\n/** Convert ParsedQuery back into query string parameters */\nexport function buildQueryParams(\n  parsed: Partial<ParsedQuery>,\n): Record<string, string | string[] | number> {\n  const params: Record<string, string | string[] | number> = {}\n\n  if (parsed.filters?.length) {\n    params.filter = parsed.filters.map((f) => `${f.field}:${f.operator}:${f.value}`)\n  }\n\n  if (parsed.sort?.length) {\n    params.sort = parsed.sort.map((s) => `${s.field}:${s.direction}`)\n  }\n\n  if (parsed.pagination) {\n    params.page = parsed.pagination.page\n    params.limit = parsed.pagination.limit\n  }\n\n  if (parsed.search) {\n    params.q = parsed.search\n  }\n\n  return params\n}\n"],"mappings":"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","names":["FILTER_OPERATORS","Set","MAX_SEARCH_LENGTH","DEFAULT_PAGE","DEFAULT_LIMIT","MAX_LIMIT","parseFilters","filterParam","allowedFields","items","Array","isArray","results","allowed","Set","item","firstColon","indexOf","secondColon","field","slice","operator","value","FILTER_OPERATORS","has","push","parseSort","sortParam","lastColon","lastIndexOf","dir","toLowerCase","direction","parsePagination","params","page","parseInt","limit","isNaN","offset","parseSearchQuery","q","trim","parseQuery","query","fieldConfig","filters","filter","filterable","sort","sortable","pagination","search","buildQueryParams","parsed","length","map","f","s"]}

package/dist/{chunk-LQ6RSWMX.js → chunk-Y5ZSC2FB.js}

@@ -1,6 +1,6 @@
 import {
   parseQuery
-} from "./chunk-VXX2Y3TA.js";
+} from "./chunk-WYY34UWG.js";
 import {
   __name
 } from "./chunk-WCQVDF3K.js";
@@ -106,9 +106,109 @@ var RequestContext = class {
     this.res.setHeader("Content-Type", contentType);
     return this.res.send(buffer);
   }
+  /**
+  * Parse query params and return a standardized paginated response.
+  * Calls `ctx.qs()` internally, then wraps your data with pagination meta.
+  *
+  * @param fetcher - Async function that receives ParsedQuery and returns `{ data, total }`
+  * @param fieldConfig - Optional whitelist for filterable, sortable, searchable fields
+  *
+  * @example
+  * ```ts
+  * @Get('/')
+  * async list(ctx: RequestContext) {
+  *   return ctx.paginate(
+  *     async (parsed) => {
+  *       const data = await db.select().from(users)
+  *         .where(query.where).limit(parsed.pagination.limit)
+  *         .offset(parsed.pagination.offset).all()
+  *       const total = await db.select({ count: count() }).from(users).get()
+  *       return { data, total: total?.count ?? 0 }
+  *     },
+  *     { filterable: ['name', 'role'], sortable: ['createdAt'] },
+  *   )
+  * }
+  * ```
+  */
+  async paginate(fetcher, fieldConfig) {
+    const parsed = this.qs(fieldConfig);
+    const { data, total } = await fetcher(parsed);
+    const { page, limit } = parsed.pagination;
+    const totalPages = Math.ceil(total / limit) || 1;
+    const response = {
+      data,
+      meta: {
+        page,
+        limit,
+        total,
+        totalPages,
+        hasNext: page < totalPages,
+        hasPrev: page > 1
+      }
+    };
+    return this.json(response);
+  }
+  // ── Server-Sent Events ──────────────────────────────────────────────
+  /**
+  * Start an SSE (Server-Sent Events) stream.
+  * Sets the correct headers and returns helpers to send events.
+  *
+  * @example
+  * ```ts
+  * @Get('/events')
+  * async stream(ctx: RequestContext) {
+  *   const sse = ctx.sse()
+  *
+  *   const interval = setInterval(() => {
+  *     sse.send({ time: new Date().toISOString() }, 'tick')
+  *   }, 1000)
+  *
+  *   sse.onClose(() => clearInterval(interval))
+  * }
+  * ```
+  */
+  sse() {
+    this.res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no"
+    });
+    this.res.flushHeaders();
+    const closeCallbacks = [];
+    this.req.on("close", () => {
+      for (const cb of closeCallbacks) cb();
+    });
+    return {
+      /** Send an SSE event with optional event name and id */
+      send: /* @__PURE__ */ __name((data, event, id) => {
+        if (id) this.res.write(`id: ${id}
+`);
+        if (event) this.res.write(`event: ${event}
+`);
+        this.res.write(`data: ${JSON.stringify(data)}
+
+`);
+      }, "send"),
+      /** Send a comment (keeps connection alive) */
+      comment: /* @__PURE__ */ __name((text) => {
+        this.res.write(`: ${text}
+
+`);
+      }, "comment"),
+      /** Register a callback when the client disconnects */
+      onClose: /* @__PURE__ */ __name((fn) => {
+        closeCallbacks.push(fn);
+      }, "onClose"),
+      /** End the SSE stream */
+      close: /* @__PURE__ */ __name(() => {
+        this.res.end();
+      }, "close")
+    };
+  }
 };
 
 export {
   RequestContext
 };
-//# sourceMappingURL=chunk-LQ6RSWMX.js.map
+//# sourceMappingURL=chunk-Y5ZSC2FB.js.map

package/dist/chunk-Y5ZSC2FB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts"],"sourcesContent":["import type { Request, Response, NextFunction } from 'express'\nimport {\n  parseQuery,\n  type ParsedQuery,\n  type QueryFieldConfig,\n  type PaginatedResponse,\n} from './query'\n\n/**\n * Unified request/response abstraction passed to every controller method.\n * Shields handlers from raw Express objects and provides convenience methods.\n */\nexport class RequestContext<TBody = any, TParams = any, TQuery = any> {\n  private metadata = new Map<string, any>()\n\n  constructor(\n    public readonly req: Request,\n    public readonly res: Response,\n    public readonly next: NextFunction,\n  ) {}\n\n  // ── Request Data ────────────────────────────────────────────────────\n\n  get body(): TBody {\n    return this.req.body as TBody\n  }\n\n  get params(): TParams {\n    return this.req.params as TParams\n  }\n\n  get query(): TQuery {\n    return this.req.query as TQuery\n  }\n\n  get headers() {\n    return this.req.headers\n  }\n\n  get requestId(): string | undefined {\n    return (this.req as any).requestId ?? (this.req.headers['x-request-id'] as string | undefined)\n  }\n\n  /** Session data (requires session middleware) */\n  get session(): any {\n    return (this.req as any).session\n  }\n\n  // ── Query String Parsing ───────────────────────────────────────────\n\n  /**\n   * Parse the request query string into structured filters, sort, pagination, and search.\n   * Pass the result to an ORM query builder adapter (Drizzle, Prisma, Sequelize, etc.).\n   *\n   * @param fieldConfig - Optional whitelist for filterable, sortable, and searchable fields\n   *\n   * @example\n   * ```ts\n   * @Get('/')\n   * async list(ctx: RequestContext) {\n   *   const parsed = ctx.qs({\n   *     filterable: ['status', 'priority'],\n   *     sortable: ['createdAt', 'title'],\n   *   })\n   *   const q = drizzleAdapter.build(parsed, { columns })\n   *   // ... use q.where, q.orderBy, q.limit, q.offset\n   * }\n   * ```\n   */\n  qs(fieldConfig?: QueryFieldConfig): ParsedQuery {\n    return parseQuery(this.req.query as Record<string, any>, fieldConfig)\n  }\n\n  // ── File Uploads ────────────────────────────────────────────────────\n\n  /** Single uploaded file (requires @FileUpload({ mode: 'single' })) */\n  get file(): any {\n    return (this.req as any).file\n  }\n\n  /** Array of uploaded files (requires @FileUpload({ mode: 'array' })) */\n  get files(): any[] | undefined {\n    return (this.req as any).files\n  }\n\n  // ── Metadata Store ──────────────────────────────────────────────────\n\n  get<T = any>(key: string): T | undefined {\n    return this.metadata.get(key) as T | undefined\n  }\n\n  set(key: string, value: any): void {\n    this.metadata.set(key, value)\n  }\n\n  // ── Response Helpers ────────────────────────────────────────────────\n\n  json(data: any, status = 200) {\n    return this.res.status(status).json(data)\n  }\n\n  created(data: any) {\n    return this.res.status(201).json(data)\n  }\n\n  noContent() {\n    return this.res.status(204).end()\n  }\n\n  notFound(message = 'Not Found') {\n    return this.res.status(404).json({ message })\n  }\n\n  badRequest(message: string) {\n    return this.res.status(400).json({ message })\n  }\n\n  html(content: string, status = 200) {\n    return this.res.status(status).type('html').send(content)\n  }\n\n  download(buffer: Buffer, filename: string, contentType = 'application/octet-stream') {\n    this.res.setHeader('Content-Disposition', `attachment; filename=\"${filename}\"`)\n    this.res.setHeader('Content-Type', contentType)\n    return this.res.send(buffer)\n  }\n\n  /**\n   * Parse query params and return a standardized paginated response.\n   * Calls `ctx.qs()` internally, then wraps your data with pagination meta.\n   *\n   * @param fetcher - Async function that receives ParsedQuery and returns `{ data, total }`\n   * @param fieldConfig - Optional whitelist for filterable, sortable, searchable fields\n   *\n   * @example\n   * ```ts\n   * @Get('/')\n   * async list(ctx: RequestContext) {\n   *   return ctx.paginate(\n   *     async (parsed) => {\n   *       const data = await db.select().from(users)\n   *         .where(query.where).limit(parsed.pagination.limit)\n   *         .offset(parsed.pagination.offset).all()\n   *       const total = await db.select({ count: count() }).from(users).get()\n   *       return { data, total: total?.count ?? 0 }\n   *     },\n   *     { filterable: ['name', 'role'], sortable: ['createdAt'] },\n   *   )\n   * }\n   * ```\n   */\n  async paginate<T>(\n    fetcher: (parsed: ParsedQuery) => Promise<{ data: T[]; total: number }>,\n    fieldConfig?: QueryFieldConfig,\n  ) {\n    const parsed = this.qs(fieldConfig)\n    const { data, total } = await fetcher(parsed)\n    const { page, limit } = parsed.pagination\n    const totalPages = Math.ceil(total / limit) || 1\n\n    const response: PaginatedResponse<T> = {\n      data,\n      meta: {\n        page,\n        limit,\n        total,\n        totalPages,\n        hasNext: page < totalPages,\n        hasPrev: page > 1,\n      },\n    }\n\n    return this.json(response)\n  }\n\n  // ── Server-Sent Events ──────────────────────────────────────────────\n\n  /**\n   * Start an SSE (Server-Sent Events) stream.\n   * Sets the correct headers and returns helpers to send events.\n   *\n   * @example\n   * ```ts\n   * @Get('/events')\n   * async stream(ctx: RequestContext) {\n   *   const sse = ctx.sse()\n   *\n   *   const interval = setInterval(() => {\n   *     sse.send({ time: new Date().toISOString() }, 'tick')\n   *   }, 1000)\n   *\n   *   sse.onClose(() => clearInterval(interval))\n   * }\n   * ```\n   */\n  sse() {\n    this.res.writeHead(200, {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n      'X-Accel-Buffering': 'no',\n    })\n    this.res.flushHeaders()\n\n    const closeCallbacks: Array<() => void> = []\n\n    this.req.on('close', () => {\n      for (const cb of closeCallbacks) cb()\n    })\n\n    return {\n      /** Send an SSE event with optional event name and id */\n      send: (data: any, event?: string, id?: string) => {\n        if (id) this.res.write(`id: ${id}\\n`)\n        if (event) this.res.write(`event: ${event}\\n`)\n        this.res.write(`data: ${JSON.stringify(data)}\\n\\n`)\n      },\n      /** Send a comment (keeps connection alive) */\n      comment: (text: string) => {\n        this.res.write(`: ${text}\\n\\n`)\n      },\n      /** Register a callback when the client disconnects */\n      onClose: (fn: () => void) => {\n        closeCallbacks.push(fn)\n      },\n      /** End the SSE stream */\n      close: () => {\n        this.res.end()\n      },\n    }\n  }\n}\n"],"mappings":"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","names":["RequestContext","metadata","Map","req","res","next","body","params","query","headers","requestId","session","qs","fieldConfig","parseQuery","file","files","get","key","set","value","json","data","status","created","noContent","end","notFound","message","badRequest","html","content","type","send","download","buffer","filename","contentType","setHeader","paginate","fetcher","parsed","total","page","limit","pagination","totalPages","Math","ceil","response","meta","hasNext","hasPrev","sse","writeHead","Connection","flushHeaders","closeCallbacks","on","cb","event","id","write","JSON","stringify","comment","text","onClose","fn","push","close"]}

package/dist/{chunk-OKB76LY2.js → chunk-YRCR6Z5C.js}

@@ -23,11 +23,17 @@ var Application = class {
   container;
   httpServer = null;
   adapters;
+  plugins;
   constructor(options) {
     this.options = options;
     this.app = express();
     this.container = Container.getInstance();
-    this.adapters = options.adapters ?? [];
+    this.plugins = options.plugins ?? [];
+    this.adapters = [
+      // Plugin adapters first
+      ...this.plugins.flatMap((p) => p.adapters?.() ?? []),
+      ...options.adapters ?? []
+    ];
   }
   /**
   * Full setup pipeline:
@@ -51,6 +57,15 @@ var Application = class {
     this.app.disable("x-powered-by");
     this.app.set("trust proxy", this.options.trustProxy ?? false);
     this.mountMiddlewareList(adapterMw.beforeGlobal);
+    for (const plugin of this.plugins) {
+      plugin.register?.(this.container);
+    }
+    for (const plugin of this.plugins) {
+      const mw = plugin.middleware?.() ?? [];
+      for (const handler of mw) {
+        this.app.use(handler);
+      }
+    }
     if (this.options.middleware) {
       for (const entry of this.options.middleware) {
         this.mountMiddlewareEntry(entry);
@@ -62,7 +77,11 @@ var Application = class {
       }));
     }
     this.mountMiddlewareList(adapterMw.afterGlobal);
-    const modules = this.options.modules.map((ModuleClass) => {
+    const allModuleClasses = [
+      ...this.plugins.flatMap((p) => p.modules?.() ?? []),
+      ...this.options.modules
+    ];
+    const modules = allModuleClasses.map((ModuleClass) => {
       const mod = new ModuleClass();
       mod.register(this.container);
       return mod;
@@ -109,11 +128,14 @@ var Application = class {
       }
       throw err;
     });
-    this.httpServer.listen(port, () => {
+    this.httpServer.listen(port, async () => {
       log.info(`Server running on http://localhost:${port}`);
       for (const adapter of this.adapters) {
         adapter.afterStart?.(this.httpServer, this.container);
       }
+      for (const plugin of this.plugins) {
+        await plugin.onReady?.(this.container);
+      }
     });
   }
   /** HMR rebuild: swap Express handler without restarting the server */
@@ -131,7 +153,10 @@ var Application = class {
   /** Graceful shutdown — runs all adapter shutdowns in parallel, resilient to failures */
   async shutdown() {
     log.info("Shutting down...");
-    const results = await Promise.allSettled(this.adapters.map((adapter) => Promise.resolve(adapter.shutdown?.())));
+    const results = await Promise.allSettled([
+      ...this.plugins.map((plugin) => Promise.resolve(plugin.shutdown?.())),
+      ...this.adapters.map((adapter) => Promise.resolve(adapter.shutdown?.()))
+    ]);
     for (const result of results) {
       if (result.status === "rejected") {
         log.error({
@@ -187,4 +212,4 @@ var Application = class {
 export {
   Application
 };
-//# sourceMappingURL=chunk-OKB76LY2.js.map
+//# sourceMappingURL=chunk-YRCR6Z5C.js.map

package/dist/chunk-YRCR6Z5C.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/application.ts"],"sourcesContent":["import http from 'node:http'\nimport express, { type Express, type RequestHandler } from 'express'\nimport {\n  Container,\n  createLogger,\n  type AppModuleClass,\n  type AppAdapter,\n  type AdapterMiddleware,\n  type KickPlugin,\n} from '@forinda/kickjs-core'\nimport { buildRoutes } from './router-builder'\nimport { requestId } from './middleware/request-id'\nimport { notFoundHandler, errorHandler } from './middleware/error-handler'\n\nconst log = createLogger('Application')\n\n/**\n * A middleware entry in the declarative pipeline.\n * Can be a bare handler or an object with path scoping.\n */\nexport type MiddlewareEntry = RequestHandler | { path: string; handler: RequestHandler }\n\nexport interface ApplicationOptions {\n  /** Feature modules to load */\n  modules: AppModuleClass[]\n  /** Adapters that hook into the lifecycle (DB, Redis, Swagger, etc.) */\n  adapters?: AppAdapter[]\n  /** Server port (falls back to PORT env var, then 3000) */\n  port?: number\n  /** Global API prefix (default: '/api') */\n  apiPrefix?: string\n  /** Default API version (default: 1) — routes become /{prefix}/v{version}/{path} */\n  defaultVersion?: number\n\n  /**\n   * Global middleware pipeline. Declared in order.\n   * Replaces the hardcoded middleware stack — you control exactly what runs.\n   *\n   * @example\n   * ```ts\n   * bootstrap({\n   *   modules,\n   *   middleware: [\n   *     helmet(),\n   *     cors(),\n   *     compression(),\n   *     morgan('dev'),\n   *     express.json({ limit: '1mb' }),\n   *   ],\n   * })\n   * ```\n   *\n   * If omitted, a sensible default is applied:\n   *   requestId(), express.json({ limit: '100kb' })\n   */\n  middleware?: MiddlewareEntry[]\n\n  /** Plugins that bundle modules, adapters, middleware, and DI bindings */\n  plugins?: KickPlugin[]\n\n  /** Express `trust proxy` setting */\n  trustProxy?: boolean | number | string | ((ip: string, hopIndex: number) => boolean)\n  /** Maximum JSON body size (only used when middleware is not provided) */\n  jsonLimit?: string | number\n}\n\n/**\n * The main application class. Wires together Express, the DI container,\n * feature modules, adapters, and the middleware pipeline.\n */\nexport class Application {\n  private app: Express\n  private container: Container\n  private httpServer: http.Server | null = null\n  private adapters: AppAdapter[]\n\n  private plugins: KickPlugin[]\n\n  constructor(private readonly options: ApplicationOptions) {\n    this.app = express()\n    this.container = Container.getInstance()\n    this.plugins = options.plugins ?? []\n    this.adapters = [\n      // Plugin adapters first\n      ...this.plugins.flatMap((p) => p.adapters?.() ?? []),\n      ...(options.adapters ?? []),\n    ]\n  }\n\n  /**\n   * Full setup pipeline:\n   * 1. Adapter beforeMount hooks (early routes — docs, health)\n   * 2. Adapter middleware (phase: beforeGlobal)\n   * 3. Global middleware (user-declared or defaults)\n   * 4. Adapter middleware (phase: afterGlobal)\n   * 5. Module registration + DI bootstrap\n   * 6. Adapter middleware (phase: beforeRoutes)\n   * 7. Module route mounting\n   * 8. Adapter middleware (phase: afterRoutes)\n   * 9. Error handlers (notFound + global)\n   * 10. Adapter beforeStart hooks\n   */\n  setup(): void {\n    log.info('Bootstrapping application...')\n\n    // Collect adapter middleware by phase\n    const adapterMw = this.collectAdapterMiddleware()\n\n    // ── 1. Adapter beforeMount hooks ──────────────────────────────────\n    for (const adapter of this.adapters) {\n      adapter.beforeMount?.(this.app, this.container)\n    }\n\n    // ── 2. Hardened defaults ──────────────────────────────────────────\n    this.app.disable('x-powered-by')\n    this.app.set('trust proxy', this.options.trustProxy ?? false)\n\n    // ── 3. Adapter middleware: beforeGlobal ───────────────────────────\n    this.mountMiddlewareList(adapterMw.beforeGlobal)\n\n    // ── 3b. Plugin registration ──────────────────────────────────────\n    for (const plugin of this.plugins) {\n      plugin.register?.(this.container)\n    }\n\n    // ── 3c. Plugin middleware ─────────────────────────────────────────\n    for (const plugin of this.plugins) {\n      const mw = plugin.middleware?.() ?? []\n      for (const handler of mw) {\n        this.app.use(handler)\n      }\n    }\n\n    // ── 4. Global middleware ─────────────────────────────────────────\n    if (this.options.middleware) {\n      // User-declared pipeline — full control\n      for (const entry of this.options.middleware) {\n        this.mountMiddlewareEntry(entry)\n      }\n    } else {\n      // Sensible defaults when no middleware declared\n      this.app.use(requestId())\n      this.app.use(express.json({ limit: this.options.jsonLimit ?? '100kb' }))\n    }\n\n    // ── 5. Adapter middleware: afterGlobal ────────────────────────────\n    this.mountMiddlewareList(adapterMw.afterGlobal)\n\n    // ── 6. Module registration + DI bootstrap ────────────────────────\n    // Plugin modules first, then user modules\n    const allModuleClasses = [\n      ...this.plugins.flatMap((p) => p.modules?.() ?? []),\n      ...this.options.modules,\n    ]\n    const modules = allModuleClasses.map((ModuleClass) => {\n      const mod = new ModuleClass()\n      mod.register(this.container)\n      return mod\n    })\n    this.container.bootstrap()\n\n    // ── 7. Adapter middleware: beforeRoutes ───────────────────────────\n    this.mountMiddlewareList(adapterMw.beforeRoutes)\n\n    // ── 8. Mount module routes with versioning ───────────────────────\n    const apiPrefix = this.options.apiPrefix ?? '/api'\n    const defaultVersion = this.options.defaultVersion ?? 1\n\n    for (const mod of modules) {\n      const result = mod.routes()\n      const routeSets = Array.isArray(result) ? result : [result]\n\n      for (const route of routeSets) {\n        const version = route.version ?? defaultVersion\n        const mountPath = `${apiPrefix}/v${version}${route.path}`\n        this.app.use(mountPath, route.router)\n\n        // Notify adapters (e.g. SwaggerAdapter for OpenAPI spec generation)\n        if (route.controller) {\n          for (const adapter of this.adapters) {\n            adapter.onRouteMount?.(route.controller, mountPath)\n          }\n        }\n      }\n    }\n\n    // ── 9. Adapter middleware: afterRoutes ────────────────────────────\n    this.mountMiddlewareList(adapterMw.afterRoutes)\n\n    // ── 10. Error handlers ───────────────────────────────────────────\n    this.app.use(notFoundHandler())\n    this.app.use(errorHandler())\n\n    // ── 11. Adapter beforeStart hooks ────────────────────────────────\n    for (const adapter of this.adapters) {\n      adapter.beforeStart?.(this.app, this.container)\n    }\n  }\n\n  /** Start the HTTP server — fails fast if port is in use */\n  start(): void {\n    this.setup()\n\n    const port = this.options.port ?? parseInt(process.env.PORT || '3000', 10)\n    this.httpServer = http.createServer(this.app)\n\n    this.httpServer.on('error', (err: NodeJS.ErrnoException) => {\n      if (err.code === 'EADDRINUSE') {\n        log.error(\n          `Port ${port} is already in use. Kill the existing process or use a different port:\\n` +\n            `  PORT=${port + 1} kick dev\\n` +\n            `  lsof -i :${port}   # find what's using it\\n` +\n            `  kill <PID>          # stop it`,\n        )\n        process.exit(1)\n      }\n      throw err\n    })\n\n    this.httpServer.listen(port, async () => {\n      log.info(`Server running on http://localhost:${port}`)\n\n      for (const adapter of this.adapters) {\n        adapter.afterStart?.(this.httpServer!, this.container)\n      }\n\n      // Plugin onReady hooks\n      for (const plugin of this.plugins) {\n        await plugin.onReady?.(this.container)\n      }\n    })\n  }\n\n  /** HMR rebuild: swap Express handler without restarting the server */\n  rebuild(): void {\n    // Reset the DI container so singletons are re-created with fresh code\n    Container.reset()\n    this.container = Container.getInstance()\n\n    this.app = express()\n    this.setup()\n\n    if (this.httpServer) {\n      this.httpServer.removeAllListeners('request')\n      this.httpServer.on('request', this.app)\n      log.info('HMR: Express app rebuilt and swapped')\n    }\n  }\n\n  /** Graceful shutdown — runs all adapter shutdowns in parallel, resilient to failures */\n  async shutdown(): Promise<void> {\n    log.info('Shutting down...')\n\n    // Run all plugin + adapter shutdowns concurrently\n    const results = await Promise.allSettled([\n      ...this.plugins.map((plugin) => Promise.resolve(plugin.shutdown?.())),\n      ...this.adapters.map((adapter) => Promise.resolve(adapter.shutdown?.())),\n    ])\n    for (const result of results) {\n      if (result.status === 'rejected') {\n        log.error({ err: result.reason }, 'Adapter shutdown failed')\n      }\n    }\n\n    if (this.httpServer) {\n      await new Promise<void>((resolve) => this.httpServer!.close(() => resolve()))\n    }\n  }\n\n  getExpressApp(): Express {\n    return this.app\n  }\n\n  getHttpServer(): http.Server | null {\n    return this.httpServer\n  }\n\n  // ── Internal helpers ────────────────────────────────────────────────\n\n  private collectAdapterMiddleware() {\n    const result = {\n      beforeGlobal: [] as AdapterMiddleware[],\n      afterGlobal: [] as AdapterMiddleware[],\n      beforeRoutes: [] as AdapterMiddleware[],\n      afterRoutes: [] as AdapterMiddleware[],\n    }\n\n    for (const adapter of this.adapters) {\n      const entries = adapter.middleware?.() ?? []\n      for (const entry of entries) {\n        const phase = entry.phase ?? 'afterGlobal'\n        result[phase].push(entry)\n      }\n    }\n\n    return result\n  }\n\n  private mountMiddlewareList(entries: AdapterMiddleware[]): void {\n    for (const entry of entries) {\n      if (entry.path) {\n        this.app.use(entry.path, entry.handler)\n      } else {\n        this.app.use(entry.handler)\n      }\n    }\n  }\n\n  private mountMiddlewareEntry(entry: MiddlewareEntry): void {\n    if (typeof entry === 'function') {\n      this.app.use(entry)\n    } else {\n      this.app.use(entry.path, entry.handler)\n    }\n  }\n}\n"],"mappings":"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","names":["http","express","Container","createLogger","log","createLogger","Application","app","container","httpServer","adapters","plugins","options","express","Container","getInstance","flatMap","p","setup","info","adapterMw","collectAdapterMiddleware","adapter","beforeMount","disable","set","trustProxy","mountMiddlewareList","beforeGlobal","plugin","register","mw","middleware","handler","use","entry","mountMiddlewareEntry","requestId","json","limit","jsonLimit","afterGlobal","allModuleClasses","modules","map","ModuleClass","mod","bootstrap","beforeRoutes","apiPrefix","defaultVersion","result","routes","routeSets","Array","isArray","route","version","mountPath","path","router","controller","onRouteMount","afterRoutes","notFoundHandler","errorHandler","beforeStart","start","port","parseInt","process","env","PORT","http","createServer","on","err","code","error","exit","listen","afterStart","onReady","rebuild","reset","removeAllListeners","shutdown","results","Promise","allSettled","resolve","status","reason","close","getExpressApp","getHttpServer","entries","phase","push"]}

package/dist/{chunk-CNN7JFUB.js → chunk-YYT24FTH.js}

@@ -75,6 +75,8 @@ var DevToolsAdapter = class {
     if (!this.enabled) return;
     this.container = container;
     this.startedAt.value = Date.now();
+    this.routes = [];
+    this.adapterStatuses[this.name] = "running";
     const router = Router();
     router.get("/routes", (_req, res) => {
       res.json({
@@ -190,11 +192,6 @@ var DevToolsAdapter = class {
       }
     ];
   }
-  beforeStart(_app, _container) {
-    if (!this.enabled) return;
-    this.routes = [];
-    this.adapterStatuses[this.name] = "running";
-  }
   onRouteMount(controllerClass, mountPath) {
     if (!this.enabled) return;
     const routes = Reflect.getMetadata(METADATA.ROUTES, controllerClass) ?? [];
@@ -226,4 +223,4 @@ var DevToolsAdapter = class {
 export {
   DevToolsAdapter
 };
-//# sourceMappingURL=chunk-CNN7JFUB.js.map
+//# sourceMappingURL=chunk-YYT24FTH.js.map

package/dist/chunk-YYT24FTH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/devtools.ts"],"sourcesContent":["import type { Request, Response, NextFunction } from 'express'\nimport { Router } from 'express'\nimport {\n  type AppAdapter,\n  type AdapterMiddleware,\n  type Container,\n  METADATA,\n  ref,\n  computed,\n  reactive,\n  watch,\n  createLogger,\n  type Ref,\n  type ComputedRef,\n} from '@forinda/kickjs-core'\n\nconst log = createLogger('DevTools')\n\n/** Route metadata collected during mount */\ninterface RouteInfo {\n  method: string\n  path: string\n  controller: string\n  handler: string\n  middleware: string[]\n}\n\n/** Per-route latency stats */\ninterface RouteStats {\n  count: number\n  totalMs: number\n  minMs: number\n  maxMs: number\n}\n\nexport interface DevToolsOptions {\n  /** Base path for debug endpoints (default: '/_debug') */\n  basePath?: string\n  /** Only enable when this is true (default: process.env.NODE_ENV !== 'production') */\n  enabled?: boolean\n  /** Include environment variables (sanitized) at /_debug/config (default: false) */\n  exposeConfig?: boolean\n  /** Env var prefixes to expose (default: ['APP_', 'NODE_ENV']). Others are redacted. */\n  configPrefixes?: string[]\n  /** Callback when error rate exceeds threshold */\n  onErrorRateExceeded?: (rate: number) => void\n  /** Error rate threshold (default: 0.5 = 50%) */\n  errorRateThreshold?: number\n  /** Other adapters to discover stats from (e.g., WsAdapter) */\n  adapters?: any[]\n}\n\n/**\n * DevToolsAdapter — Vue-style reactive introspection for KickJS applications.\n *\n * Exposes debug endpoints powered by reactive state (ref, computed, watch):\n * - `GET /_debug/routes`    — all registered routes with middleware\n * - `GET /_debug/container` — DI registry with scopes and instantiation status\n * - `GET /_debug/metrics`   — live request/error counts, error rate, uptime\n * - `GET /_debug/health`    — deep health check with adapter status\n * - `GET /_debug/config`    — sanitized environment variables (opt-in)\n * - `GET /_debug/state`     — full reactive state snapshot\n *\n * @example\n * ```ts\n * import { DevToolsAdapter } from '@forinda/kickjs-http/devtools'\n *\n * bootstrap({\n *   modules: [UserModule],\n *   adapters: [\n *     new DevToolsAdapter({\n *       enabled: process.env.NODE_ENV !== 'production',\n *       exposeConfig: true,\n *       configPrefixes: ['APP_', 'DATABASE_'],\n *     }),\n *   ],\n * })\n * ```\n */\nexport class DevToolsAdapter implements AppAdapter {\n  readonly name = 'DevToolsAdapter'\n\n  private basePath: string\n  private enabled: boolean\n  private exposeConfig: boolean\n  private configPrefixes: string[]\n  private errorRateThreshold: number\n\n  // ── Reactive State ───────────────────────────────────────────────────\n  /** Total requests received */\n  readonly requestCount: Ref<number>\n  /** Total responses with status >= 500 */\n  readonly errorCount: Ref<number>\n  /** Total responses with status >= 400 and < 500 */\n  readonly clientErrorCount: Ref<number>\n  /** Server start time */\n  readonly startedAt: Ref<number>\n  /** Computed error rate (server errors / total requests) */\n  readonly errorRate: ComputedRef<number>\n  /** Computed uptime in seconds */\n  readonly uptimeSeconds: ComputedRef<number>\n  /** Per-route latency tracking */\n  readonly routeLatency: Record<string, RouteStats>\n\n  // ── Internal State ───────────────────────────────────────────────────\n  private routes: RouteInfo[] = []\n  private container: Container | null = null\n  private adapterStatuses: Record<string, string> = {}\n  private stopErrorWatch: (() => void) | null = null\n  private peerAdapters: any[] = []\n\n  constructor(options: DevToolsOptions = {}) {\n    this.basePath = options.basePath ?? '/_debug'\n    this.enabled = options.enabled ?? process.env.NODE_ENV !== 'production'\n    this.exposeConfig = options.exposeConfig ?? false\n    this.configPrefixes = options.configPrefixes ?? ['APP_', 'NODE_ENV']\n    this.errorRateThreshold = options.errorRateThreshold ?? 0.5\n    this.peerAdapters = options.adapters ?? []\n\n    // Initialize reactive state\n    this.requestCount = ref(0)\n    this.errorCount = ref(0)\n    this.clientErrorCount = ref(0)\n    this.startedAt = ref(Date.now())\n    this.routeLatency = reactive({})\n\n    this.errorRate = computed(() =>\n      this.requestCount.value > 0 ? this.errorCount.value / this.requestCount.value : 0,\n    )\n\n    this.uptimeSeconds = computed(() => Math.floor((Date.now() - this.startedAt.value) / 1000))\n\n    // Watch error rate — log warnings when elevated\n    if (options.onErrorRateExceeded) {\n      const callback = options.onErrorRateExceeded\n      const threshold = this.errorRateThreshold\n      this.stopErrorWatch = watch(this.errorRate, (rate) => {\n        if (rate > threshold) {\n          callback(rate)\n        }\n      })\n    } else {\n      this.stopErrorWatch = watch(this.errorRate, (rate) => {\n        if (rate > this.errorRateThreshold) {\n          log.warn(`Error rate elevated: ${(rate * 100).toFixed(1)}%`)\n        }\n      })\n    }\n  }\n\n  // ── Adapter Lifecycle ────────────────────────────────────────────────\n\n  beforeMount(app: any, container: Container): void {\n    if (!this.enabled) return\n\n    this.container = container\n    this.startedAt.value = Date.now()\n    // Clear routes on rebuild/restart to prevent HMR duplication\n    this.routes = []\n    this.adapterStatuses[this.name] = 'running'\n\n    const router = Router()\n\n    router.get('/routes', (_req: Request, res: Response) => {\n      res.json({ routes: this.routes })\n    })\n\n    router.get('/container', (_req: Request, res: Response) => {\n      const registrations = this.container?.getRegistrations() ?? []\n      res.json({ registrations, count: registrations.length })\n    })\n\n    router.get('/metrics', (_req: Request, res: Response) => {\n      res.json({\n        requests: this.requestCount.value,\n        serverErrors: this.errorCount.value,\n        clientErrors: this.clientErrorCount.value,\n        errorRate: this.errorRate.value,\n        uptimeSeconds: this.uptimeSeconds.value,\n        startedAt: new Date(this.startedAt.value).toISOString(),\n        routeLatency: this.routeLatency,\n      })\n    })\n\n    router.get('/health', (_req: Request, res: Response) => {\n      const healthy = this.errorRate.value < this.errorRateThreshold\n      const status = healthy ? 'healthy' : 'degraded'\n\n      res.status(healthy ? 200 : 503).json({\n        status,\n        errorRate: this.errorRate.value,\n        uptime: this.uptimeSeconds.value,\n        adapters: this.adapterStatuses,\n      })\n    })\n\n    router.get('/state', (_req: Request, res: Response) => {\n      const wsAdapter = this.peerAdapters.find(\n        (a) => a.name === 'WsAdapter' && typeof a.getStats === 'function',\n      )\n      res.json({\n        reactive: {\n          requestCount: this.requestCount.value,\n          errorCount: this.errorCount.value,\n          clientErrorCount: this.clientErrorCount.value,\n          errorRate: this.errorRate.value,\n          uptimeSeconds: this.uptimeSeconds.value,\n          startedAt: new Date(this.startedAt.value).toISOString(),\n        },\n        routes: this.routes.length,\n        container: this.container?.getRegistrations().length ?? 0,\n        routeLatency: this.routeLatency,\n        ...(wsAdapter ? { ws: wsAdapter.getStats() } : {}),\n      })\n    })\n\n    router.get('/ws', (_req: Request, res: Response) => {\n      const wsAdapter = this.peerAdapters.find(\n        (a) => a.name === 'WsAdapter' && typeof a.getStats === 'function',\n      )\n      if (!wsAdapter) {\n        res.json({ enabled: false, message: 'WsAdapter not found' })\n        return\n      }\n      res.json({ enabled: true, ...wsAdapter.getStats() })\n    })\n\n    if (this.exposeConfig) {\n      router.get('/config', (_req: Request, res: Response) => {\n        const config: Record<string, string> = {}\n        for (const [key, value] of Object.entries(process.env)) {\n          if (value === undefined) continue\n          const allowed = this.configPrefixes.some((prefix) => key.startsWith(prefix))\n          config[key] = allowed ? value : '[REDACTED]'\n        }\n        res.json({ config })\n      })\n    }\n\n    app.use(this.basePath, router)\n    log.info(`DevTools mounted at ${this.basePath}`)\n  }\n\n  middleware(): AdapterMiddleware[] {\n    if (!this.enabled) return []\n\n    return [\n      {\n        handler: (req: Request, res: Response, next: NextFunction) => {\n          const start = Date.now()\n          this.requestCount.value++\n\n          res.on('finish', () => {\n            if (res.statusCode >= 500) this.errorCount.value++\n            else if (res.statusCode >= 400) this.clientErrorCount.value++\n\n            // Track per-route latency\n            const routeKey = `${req.method} ${req.route?.path ?? req.path}`\n            const elapsed = Date.now() - start\n\n            if (!this.routeLatency[routeKey]) {\n              this.routeLatency[routeKey] = {\n                count: 0,\n                totalMs: 0,\n                minMs: Infinity,\n                maxMs: 0,\n              }\n            }\n            const stats = this.routeLatency[routeKey]\n            stats.count++\n            stats.totalMs += elapsed\n            stats.minMs = Math.min(stats.minMs, elapsed)\n            stats.maxMs = Math.max(stats.maxMs, elapsed)\n          })\n\n          next()\n        },\n        phase: 'beforeGlobal',\n      },\n    ]\n  }\n\n  onRouteMount(controllerClass: any, mountPath: string): void {\n    if (!this.enabled) return\n\n    const routes: Array<{ method: string; path: string; handlerName: string }> =\n      Reflect.getMetadata(METADATA.ROUTES, controllerClass) ?? []\n\n    const classMiddleware: any[] =\n      Reflect.getMetadata(METADATA.CLASS_MIDDLEWARES, controllerClass) ?? []\n\n    for (const route of routes) {\n      const methodMiddleware: any[] =\n        Reflect.getMetadata(\n          METADATA.METHOD_MIDDLEWARES,\n          controllerClass.prototype,\n          route.handlerName,\n        ) ?? []\n\n      this.routes.push({\n        method: route.method.toUpperCase(),\n        path: `${mountPath}${route.path === '/' ? '' : route.path}`,\n        controller: controllerClass.name,\n        handler: route.handlerName,\n        middleware: [\n          ...classMiddleware.map((m: any) => m.name || 'anonymous'),\n          ...methodMiddleware.map((m: any) => m.name || 'anonymous'),\n        ],\n      })\n    }\n  }\n\n  afterStart(_server: any, _container: Container): void {\n    if (!this.enabled) return\n    log.info(\n      `DevTools ready — ${this.routes.length} routes tracked, ` +\n        `${this.container?.getRegistrations().length ?? 0} DI bindings`,\n    )\n  }\n\n  shutdown(): void {\n    this.stopErrorWatch?.()\n    this.adapterStatuses[this.name] = 'stopped'\n  }\n}\n"],"mappings":"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","names":["Router","METADATA","ref","computed","reactive","watch","createLogger","log","createLogger","DevToolsAdapter","name","basePath","enabled","exposeConfig","configPrefixes","errorRateThreshold","requestCount","errorCount","clientErrorCount","startedAt","errorRate","uptimeSeconds","routeLatency","routes","container","adapterStatuses","stopErrorWatch","peerAdapters","options","process","env","NODE_ENV","adapters","ref","Date","now","reactive","computed","value","Math","floor","onErrorRateExceeded","callback","threshold","watch","rate","warn","toFixed","beforeMount","app","router","Router","get","_req","res","json","registrations","getRegistrations","count","length","requests","serverErrors","clientErrors","toISOString","healthy","status","uptime","wsAdapter","find","a","getStats","ws","message","config","key","Object","entries","undefined","allowed","some","prefix","startsWith","use","info","middleware","handler","req","next","start","on","statusCode","routeKey","method","route","path","elapsed","totalMs","minMs","Infinity","maxMs","stats","min","max","phase","onRouteMount","controllerClass","mountPath","Reflect","getMetadata","METADATA","ROUTES","classMiddleware","CLASS_MIDDLEWARES","methodMiddleware","METHOD_MIDDLEWARES","prototype","handlerName","push","toUpperCase","controller","map","m","afterStart","_server","_container","shutdown"]}

package/dist/context.d.ts

@@ -1,6 +1,6 @@
 import * as http from 'http';
 import { Request, Response, NextFunction } from 'express';
-import { d as QueryFieldConfig, c as ParsedQuery } from './types-Doz6f3AB.js';
+import { e as QueryFieldConfig, d as ParsedQuery } from './types-DsbCdE8f.js';
 
 /**
  * Unified request/response abstraction passed to every controller method.
@@ -52,6 +52,62 @@ declare class RequestContext<TBody = any, TParams = any, TQuery = any> {
     badRequest(message: string): Response<any, Record<string, any>>;
     html(content: string, status?: number): Response<any, Record<string, any>>;
     download(buffer: Buffer, filename: string, contentType?: string): Response<any, Record<string, any>>;
+    /**
+     * Parse query params and return a standardized paginated response.
+     * Calls `ctx.qs()` internally, then wraps your data with pagination meta.
+     *
+     * @param fetcher - Async function that receives ParsedQuery and returns `{ data, total }`
+     * @param fieldConfig - Optional whitelist for filterable, sortable, searchable fields
+     *
+     * @example
+     * ```ts
+     * @Get('/')
+     * async list(ctx: RequestContext) {
+     *   return ctx.paginate(
+     *     async (parsed) => {
+     *       const data = await db.select().from(users)
+     *         .where(query.where).limit(parsed.pagination.limit)
+     *         .offset(parsed.pagination.offset).all()
+     *       const total = await db.select({ count: count() }).from(users).get()
+     *       return { data, total: total?.count ?? 0 }
+     *     },
+     *     { filterable: ['name', 'role'], sortable: ['createdAt'] },
+     *   )
+     * }
+     * ```
+     */
+    paginate<T>(fetcher: (parsed: ParsedQuery) => Promise<{
+        data: T[];
+        total: number;
+    }>, fieldConfig?: QueryFieldConfig): Promise<Response<any, Record<string, any>>>;
+    /**
+     * Start an SSE (Server-Sent Events) stream.
+     * Sets the correct headers and returns helpers to send events.
+     *
+     * @example
+     * ```ts
+     * @Get('/events')
+     * async stream(ctx: RequestContext) {
+     *   const sse = ctx.sse()
+     *
+     *   const interval = setInterval(() => {
+     *     sse.send({ time: new Date().toISOString() }, 'tick')
+     *   }, 1000)
+     *
+     *   sse.onClose(() => clearInterval(interval))
+     * }
+     * ```
+     */
+    sse(): {
+        /** Send an SSE event with optional event name and id */
+        send: (data: any, event?: string, id?: string) => void;
+        /** Send a comment (keeps connection alive) */
+        comment: (text: string) => void;
+        /** Register a callback when the client disconnects */
+        onClose: (fn: () => void) => void;
+        /** End the SSE stream */
+        close: () => void;
+    };
 }
 
 export { RequestContext };

package/dist/context.js

@@ -1,7 +1,7 @@
 import {
   RequestContext
-} from "./chunk-LQ6RSWMX.js";
-import "./chunk-VXX2Y3TA.js";
+} from "./chunk-Y5ZSC2FB.js";
+import "./chunk-WYY34UWG.js";
 import "./chunk-WCQVDF3K.js";
 export {
   RequestContext

package/dist/devtools.d.ts

@@ -79,7 +79,6 @@ declare class DevToolsAdapter implements AppAdapter {
     constructor(options?: DevToolsOptions);
     beforeMount(app: any, container: Container): void;
     middleware(): AdapterMiddleware[];
-    beforeStart(_app: any, _container: Container): void;
     onRouteMount(controllerClass: any, mountPath: string): void;
     afterStart(_server: any, _container: Container): void;
     shutdown(): void;

package/dist/devtools.js

@@ -1,6 +1,6 @@
 import {
   DevToolsAdapter
-} from "./chunk-CNN7JFUB.js";
+} from "./chunk-YYT24FTH.js";
 import "./chunk-WCQVDF3K.js";
 export {
   DevToolsAdapter

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { Session, SessionData, SessionOptions, SessionStore, session } from './m
 export { UploadOptions, buildUploadMiddleware, cleanupFiles, resolveMimeTypes, upload } from './middleware/upload.js';
 export { DevToolsAdapter, DevToolsOptions } from './devtools.js';
 export { buildQueryParams, parseFilters, parsePagination, parseQuery, parseSearchQuery, parseSort } from './query/index.js';
-export { F as FILTER_OPERATORS, a as FilterItem, b as FilterOperator, P as PaginationParams, c as ParsedQuery, Q as QueryBuilderAdapter, d as QueryFieldConfig, S as SortItem } from './types-Doz6f3AB.js';
+export { F as FILTER_OPERATORS, a as FilterItem, b as FilterOperator, P as PaginatedResponse, c as PaginationParams, d as ParsedQuery, Q as QueryBuilderAdapter, e as QueryFieldConfig, S as SortItem } from './types-DsbCdE8f.js';
 import 'node:http';
 import 'express';
 import '@forinda/kickjs-core';

package/dist/index.js

@@ -6,21 +6,21 @@ import {
 } from "./chunk-NQJNMKW5.js";
 import {
   bootstrap
-} from "./chunk-D76WCWAW.js";
+} from "./chunk-W35YEQOE.js";
 import {
   Application
-} from "./chunk-OKB76LY2.js";
+} from "./chunk-YRCR6Z5C.js";
 import {
   REQUEST_ID_HEADER,
   requestId
 } from "./chunk-35NUARK7.js";
 import {
   DevToolsAdapter
-} from "./chunk-CNN7JFUB.js";
+} from "./chunk-YYT24FTH.js";
 import {
   buildRoutes,
   getControllerPath
-} from "./chunk-VFVMIFNZ.js";
+} from "./chunk-E552HYEB.js";
 import {
   buildUploadMiddleware,
   cleanupFiles,
@@ -32,7 +32,7 @@ import {
 } from "./chunk-RPN7UFUO.js";
 import {
   RequestContext
-} from "./chunk-LQ6RSWMX.js";
+} from "./chunk-Y5ZSC2FB.js";
 import {
   FILTER_OPERATORS,
   buildQueryParams,
@@ -41,7 +41,7 @@ import {
   parseQuery,
   parseSearchQuery,
   parseSort
-} from "./chunk-VXX2Y3TA.js";
+} from "./chunk-WYY34UWG.js";
 import {
   csrf
 } from "./chunk-I32MVBEG.js";

package/dist/query/index.d.ts

@@ -1,5 +1,5 @@
-import { c as ParsedQuery, a as FilterItem, P as PaginationParams, d as QueryFieldConfig, S as SortItem } from '../types-Doz6f3AB.js';
-export { F as FILTER_OPERATORS, b as FilterOperator, Q as QueryBuilderAdapter } from '../types-Doz6f3AB.js';
+import { d as ParsedQuery, a as FilterItem, c as PaginationParams, e as QueryFieldConfig, S as SortItem } from '../types-DsbCdE8f.js';
+export { F as FILTER_OPERATORS, b as FilterOperator, P as PaginatedResponse, Q as QueryBuilderAdapter } from '../types-DsbCdE8f.js';
 
 /** Parse filter strings like "status:eq:active" into structured objects */
 declare function parseFilters(filterParam: string | string[] | undefined, allowedFields?: string[]): FilterItem[];

package/dist/query/index.js

@@ -6,7 +6,7 @@ import {
   parseQuery,
   parseSearchQuery,
   parseSort
-} from "../chunk-VXX2Y3TA.js";
+} from "../chunk-WYY34UWG.js";
 import "../chunk-WCQVDF3K.js";
 export {
   FILTER_OPERATORS,

package/dist/router-builder.js

@@ -1,11 +1,11 @@
 import {
   buildRoutes,
   getControllerPath
-} from "./chunk-VFVMIFNZ.js";
+} from "./chunk-E552HYEB.js";
 import "./chunk-LEILPDMW.js";
 import "./chunk-RPN7UFUO.js";
-import "./chunk-LQ6RSWMX.js";
-import "./chunk-VXX2Y3TA.js";
+import "./chunk-Y5ZSC2FB.js";
+import "./chunk-WYY34UWG.js";
 import "./chunk-WCQVDF3K.js";
 export {
   buildRoutes,

package/dist/{types-Doz6f3AB.d.ts → types-DsbCdE8f.d.ts}

@@ -35,6 +35,18 @@ interface QueryFieldConfig {
     sortable?: string[];
     searchable?: string[];
 }
+/** Standardized paginated response shape */
+interface PaginatedResponse<T = any> {
+    data: T[];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasNext: boolean;
+        hasPrev: boolean;
+    };
+}
 /**
  * Interface for ORM-specific query builder adapters.
  * Implement this to translate a `ParsedQuery` into your ORM's query format.
@@ -69,4 +81,4 @@ interface QueryBuilderAdapter<TResult = any, TConfig = any> {
     build(parsed: ParsedQuery, config: TConfig): TResult;
 }
 
-export { FILTER_OPERATORS as F, type PaginationParams as P, type QueryBuilderAdapter as Q, type SortItem as S, type FilterItem as a, type FilterOperator as b, type ParsedQuery as c, type QueryFieldConfig as d };
+export { FILTER_OPERATORS as F, type PaginatedResponse as P, type QueryBuilderAdapter as Q, type SortItem as S, type FilterItem as a, type FilterOperator as b, type PaginationParams as c, type ParsedQuery as d, type QueryFieldConfig as e };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forinda/kickjs-http",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Express 5 integration, router builder, RequestContext, and middleware for KickJS",
   "keywords": [
     "kickjs",
@@ -98,7 +98,7 @@
     "cookie-parser": "^1.4.7",
     "multer": "^2.1.1",
     "reflect-metadata": "^0.2.2",
-    "@forinda/kickjs-core": "0.5.0"
+    "@forinda/kickjs-core": "0.6.0"
   },
   "peerDependencies": {
     "express": "^5.1.0"

package/dist/chunk-CNN7JFUB.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/devtools.ts"],"sourcesContent":["import type { Request, Response, NextFunction } from 'express'\nimport { Router } from 'express'\nimport {\n  type AppAdapter,\n  type AdapterMiddleware,\n  type Container,\n  METADATA,\n  ref,\n  computed,\n  reactive,\n  watch,\n  createLogger,\n  type Ref,\n  type ComputedRef,\n} from '@forinda/kickjs-core'\n\nconst log = createLogger('DevTools')\n\n/** Route metadata collected during mount */\ninterface RouteInfo {\n  method: string\n  path: string\n  controller: string\n  handler: string\n  middleware: string[]\n}\n\n/** Per-route latency stats */\ninterface RouteStats {\n  count: number\n  totalMs: number\n  minMs: number\n  maxMs: number\n}\n\nexport interface DevToolsOptions {\n  /** Base path for debug endpoints (default: '/_debug') */\n  basePath?: string\n  /** Only enable when this is true (default: process.env.NODE_ENV !== 'production') */\n  enabled?: boolean\n  /** Include environment variables (sanitized) at /_debug/config (default: false) */\n  exposeConfig?: boolean\n  /** Env var prefixes to expose (default: ['APP_', 'NODE_ENV']). Others are redacted. */\n  configPrefixes?: string[]\n  /** Callback when error rate exceeds threshold */\n  onErrorRateExceeded?: (rate: number) => void\n  /** Error rate threshold (default: 0.5 = 50%) */\n  errorRateThreshold?: number\n  /** Other adapters to discover stats from (e.g., WsAdapter) */\n  adapters?: any[]\n}\n\n/**\n * DevToolsAdapter — Vue-style reactive introspection for KickJS applications.\n *\n * Exposes debug endpoints powered by reactive state (ref, computed, watch):\n * - `GET /_debug/routes`    — all registered routes with middleware\n * - `GET /_debug/container` — DI registry with scopes and instantiation status\n * - `GET /_debug/metrics`   — live request/error counts, error rate, uptime\n * - `GET /_debug/health`    — deep health check with adapter status\n * - `GET /_debug/config`    — sanitized environment variables (opt-in)\n * - `GET /_debug/state`     — full reactive state snapshot\n *\n * @example\n * ```ts\n * import { DevToolsAdapter } from '@forinda/kickjs-http/devtools'\n *\n * bootstrap({\n *   modules: [UserModule],\n *   adapters: [\n *     new DevToolsAdapter({\n *       enabled: process.env.NODE_ENV !== 'production',\n *       exposeConfig: true,\n *       configPrefixes: ['APP_', 'DATABASE_'],\n *     }),\n *   ],\n * })\n * ```\n */\nexport class DevToolsAdapter implements AppAdapter {\n  readonly name = 'DevToolsAdapter'\n\n  private basePath: string\n  private enabled: boolean\n  private exposeConfig: boolean\n  private configPrefixes: string[]\n  private errorRateThreshold: number\n\n  // ── Reactive State ───────────────────────────────────────────────────\n  /** Total requests received */\n  readonly requestCount: Ref<number>\n  /** Total responses with status >= 500 */\n  readonly errorCount: Ref<number>\n  /** Total responses with status >= 400 and < 500 */\n  readonly clientErrorCount: Ref<number>\n  /** Server start time */\n  readonly startedAt: Ref<number>\n  /** Computed error rate (server errors / total requests) */\n  readonly errorRate: ComputedRef<number>\n  /** Computed uptime in seconds */\n  readonly uptimeSeconds: ComputedRef<number>\n  /** Per-route latency tracking */\n  readonly routeLatency: Record<string, RouteStats>\n\n  // ── Internal State ───────────────────────────────────────────────────\n  private routes: RouteInfo[] = []\n  private container: Container | null = null\n  private adapterStatuses: Record<string, string> = {}\n  private stopErrorWatch: (() => void) | null = null\n  private peerAdapters: any[] = []\n\n  constructor(options: DevToolsOptions = {}) {\n    this.basePath = options.basePath ?? '/_debug'\n    this.enabled = options.enabled ?? process.env.NODE_ENV !== 'production'\n    this.exposeConfig = options.exposeConfig ?? false\n    this.configPrefixes = options.configPrefixes ?? ['APP_', 'NODE_ENV']\n    this.errorRateThreshold = options.errorRateThreshold ?? 0.5\n    this.peerAdapters = options.adapters ?? []\n\n    // Initialize reactive state\n    this.requestCount = ref(0)\n    this.errorCount = ref(0)\n    this.clientErrorCount = ref(0)\n    this.startedAt = ref(Date.now())\n    this.routeLatency = reactive({})\n\n    this.errorRate = computed(() =>\n      this.requestCount.value > 0 ? this.errorCount.value / this.requestCount.value : 0,\n    )\n\n    this.uptimeSeconds = computed(() => Math.floor((Date.now() - this.startedAt.value) / 1000))\n\n    // Watch error rate — log warnings when elevated\n    if (options.onErrorRateExceeded) {\n      const callback = options.onErrorRateExceeded\n      const threshold = this.errorRateThreshold\n      this.stopErrorWatch = watch(this.errorRate, (rate) => {\n        if (rate > threshold) {\n          callback(rate)\n        }\n      })\n    } else {\n      this.stopErrorWatch = watch(this.errorRate, (rate) => {\n        if (rate > this.errorRateThreshold) {\n          log.warn(`Error rate elevated: ${(rate * 100).toFixed(1)}%`)\n        }\n      })\n    }\n  }\n\n  // ── Adapter Lifecycle ────────────────────────────────────────────────\n\n  beforeMount(app: any, container: Container): void {\n    if (!this.enabled) return\n\n    this.container = container\n    this.startedAt.value = Date.now()\n\n    const router = Router()\n\n    router.get('/routes', (_req: Request, res: Response) => {\n      res.json({ routes: this.routes })\n    })\n\n    router.get('/container', (_req: Request, res: Response) => {\n      const registrations = this.container?.getRegistrations() ?? []\n      res.json({ registrations, count: registrations.length })\n    })\n\n    router.get('/metrics', (_req: Request, res: Response) => {\n      res.json({\n        requests: this.requestCount.value,\n        serverErrors: this.errorCount.value,\n        clientErrors: this.clientErrorCount.value,\n        errorRate: this.errorRate.value,\n        uptimeSeconds: this.uptimeSeconds.value,\n        startedAt: new Date(this.startedAt.value).toISOString(),\n        routeLatency: this.routeLatency,\n      })\n    })\n\n    router.get('/health', (_req: Request, res: Response) => {\n      const healthy = this.errorRate.value < this.errorRateThreshold\n      const status = healthy ? 'healthy' : 'degraded'\n\n      res.status(healthy ? 200 : 503).json({\n        status,\n        errorRate: this.errorRate.value,\n        uptime: this.uptimeSeconds.value,\n        adapters: this.adapterStatuses,\n      })\n    })\n\n    router.get('/state', (_req: Request, res: Response) => {\n      const wsAdapter = this.peerAdapters.find(\n        (a) => a.name === 'WsAdapter' && typeof a.getStats === 'function',\n      )\n      res.json({\n        reactive: {\n          requestCount: this.requestCount.value,\n          errorCount: this.errorCount.value,\n          clientErrorCount: this.clientErrorCount.value,\n          errorRate: this.errorRate.value,\n          uptimeSeconds: this.uptimeSeconds.value,\n          startedAt: new Date(this.startedAt.value).toISOString(),\n        },\n        routes: this.routes.length,\n        container: this.container?.getRegistrations().length ?? 0,\n        routeLatency: this.routeLatency,\n        ...(wsAdapter ? { ws: wsAdapter.getStats() } : {}),\n      })\n    })\n\n    router.get('/ws', (_req: Request, res: Response) => {\n      const wsAdapter = this.peerAdapters.find(\n        (a) => a.name === 'WsAdapter' && typeof a.getStats === 'function',\n      )\n      if (!wsAdapter) {\n        res.json({ enabled: false, message: 'WsAdapter not found' })\n        return\n      }\n      res.json({ enabled: true, ...wsAdapter.getStats() })\n    })\n\n    if (this.exposeConfig) {\n      router.get('/config', (_req: Request, res: Response) => {\n        const config: Record<string, string> = {}\n        for (const [key, value] of Object.entries(process.env)) {\n          if (value === undefined) continue\n          const allowed = this.configPrefixes.some((prefix) => key.startsWith(prefix))\n          config[key] = allowed ? value : '[REDACTED]'\n        }\n        res.json({ config })\n      })\n    }\n\n    app.use(this.basePath, router)\n    log.info(`DevTools mounted at ${this.basePath}`)\n  }\n\n  middleware(): AdapterMiddleware[] {\n    if (!this.enabled) return []\n\n    return [\n      {\n        handler: (req: Request, res: Response, next: NextFunction) => {\n          const start = Date.now()\n          this.requestCount.value++\n\n          res.on('finish', () => {\n            if (res.statusCode >= 500) this.errorCount.value++\n            else if (res.statusCode >= 400) this.clientErrorCount.value++\n\n            // Track per-route latency\n            const routeKey = `${req.method} ${req.route?.path ?? req.path}`\n            const elapsed = Date.now() - start\n\n            if (!this.routeLatency[routeKey]) {\n              this.routeLatency[routeKey] = {\n                count: 0,\n                totalMs: 0,\n                minMs: Infinity,\n                maxMs: 0,\n              }\n            }\n            const stats = this.routeLatency[routeKey]\n            stats.count++\n            stats.totalMs += elapsed\n            stats.minMs = Math.min(stats.minMs, elapsed)\n            stats.maxMs = Math.max(stats.maxMs, elapsed)\n          })\n\n          next()\n        },\n        phase: 'beforeGlobal',\n      },\n    ]\n  }\n\n  beforeStart(_app: any, _container: Container): void {\n    if (!this.enabled) return\n    // Clear routes on rebuild/restart to prevent duplication\n    this.routes = []\n    this.adapterStatuses[this.name] = 'running'\n  }\n\n  onRouteMount(controllerClass: any, mountPath: string): void {\n    if (!this.enabled) return\n\n    const routes: Array<{ method: string; path: string; handlerName: string }> =\n      Reflect.getMetadata(METADATA.ROUTES, controllerClass) ?? []\n\n    const classMiddleware: any[] =\n      Reflect.getMetadata(METADATA.CLASS_MIDDLEWARES, controllerClass) ?? []\n\n    for (const route of routes) {\n      const methodMiddleware: any[] =\n        Reflect.getMetadata(\n          METADATA.METHOD_MIDDLEWARES,\n          controllerClass.prototype,\n          route.handlerName,\n        ) ?? []\n\n      this.routes.push({\n        method: route.method.toUpperCase(),\n        path: `${mountPath}${route.path === '/' ? '' : route.path}`,\n        controller: controllerClass.name,\n        handler: route.handlerName,\n        middleware: [\n          ...classMiddleware.map((m: any) => m.name || 'anonymous'),\n          ...methodMiddleware.map((m: any) => m.name || 'anonymous'),\n        ],\n      })\n    }\n  }\n\n  afterStart(_server: any, _container: Container): void {\n    if (!this.enabled) return\n    log.info(\n      `DevTools ready — ${this.routes.length} routes tracked, ` +\n        `${this.container?.getRegistrations().length ?? 0} DI bindings`,\n    )\n  }\n\n  shutdown(): void {\n    this.stopErrorWatch?.()\n    this.adapterStatuses[this.name] = 'stopped'\n  }\n}\n"],"mappings":"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","names":["Router","METADATA","ref","computed","reactive","watch","createLogger","log","createLogger","DevToolsAdapter","name","basePath","enabled","exposeConfig","configPrefixes","errorRateThreshold","requestCount","errorCount","clientErrorCount","startedAt","errorRate","uptimeSeconds","routeLatency","routes","container","adapterStatuses","stopErrorWatch","peerAdapters","options","process","env","NODE_ENV","adapters","ref","Date","now","reactive","computed","value","Math","floor","onErrorRateExceeded","callback","threshold","watch","rate","warn","toFixed","beforeMount","app","router","Router","get","_req","res","json","registrations","getRegistrations","count","length","requests","serverErrors","clientErrors","toISOString","healthy","status","uptime","wsAdapter","find","a","getStats","ws","message","config","key","Object","entries","undefined","allowed","some","prefix","startsWith","use","info","middleware","handler","req","next","start","on","statusCode","routeKey","method","route","path","elapsed","totalMs","minMs","Infinity","maxMs","stats","min","max","phase","beforeStart","_app","_container","onRouteMount","controllerClass","mountPath","Reflect","getMetadata","METADATA","ROUTES","classMiddleware","CLASS_MIDDLEWARES","methodMiddleware","METHOD_MIDDLEWARES","prototype","handlerName","push","toUpperCase","controller","map","m","afterStart","_server","shutdown"]}

package/dist/chunk-LQ6RSWMX.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/context.ts"],"sourcesContent":["import type { Request, Response, NextFunction } from 'express'\nimport { parseQuery, type ParsedQuery, type QueryFieldConfig } from './query'\n\n/**\n * Unified request/response abstraction passed to every controller method.\n * Shields handlers from raw Express objects and provides convenience methods.\n */\nexport class RequestContext<TBody = any, TParams = any, TQuery = any> {\n  private metadata = new Map<string, any>()\n\n  constructor(\n    public readonly req: Request,\n    public readonly res: Response,\n    public readonly next: NextFunction,\n  ) {}\n\n  // ── Request Data ────────────────────────────────────────────────────\n\n  get body(): TBody {\n    return this.req.body as TBody\n  }\n\n  get params(): TParams {\n    return this.req.params as TParams\n  }\n\n  get query(): TQuery {\n    return this.req.query as TQuery\n  }\n\n  get headers() {\n    return this.req.headers\n  }\n\n  get requestId(): string | undefined {\n    return (this.req as any).requestId ?? (this.req.headers['x-request-id'] as string | undefined)\n  }\n\n  /** Session data (requires session middleware) */\n  get session(): any {\n    return (this.req as any).session\n  }\n\n  // ── Query String Parsing ───────────────────────────────────────────\n\n  /**\n   * Parse the request query string into structured filters, sort, pagination, and search.\n   * Pass the result to an ORM query builder adapter (Drizzle, Prisma, Sequelize, etc.).\n   *\n   * @param fieldConfig - Optional whitelist for filterable, sortable, and searchable fields\n   *\n   * @example\n   * ```ts\n   * @Get('/')\n   * async list(ctx: RequestContext) {\n   *   const parsed = ctx.qs({\n   *     filterable: ['status', 'priority'],\n   *     sortable: ['createdAt', 'title'],\n   *   })\n   *   const q = drizzleAdapter.build(parsed, { columns })\n   *   // ... use q.where, q.orderBy, q.limit, q.offset\n   * }\n   * ```\n   */\n  qs(fieldConfig?: QueryFieldConfig): ParsedQuery {\n    return parseQuery(this.req.query as Record<string, any>, fieldConfig)\n  }\n\n  // ── File Uploads ────────────────────────────────────────────────────\n\n  /** Single uploaded file (requires @FileUpload({ mode: 'single' })) */\n  get file(): any {\n    return (this.req as any).file\n  }\n\n  /** Array of uploaded files (requires @FileUpload({ mode: 'array' })) */\n  get files(): any[] | undefined {\n    return (this.req as any).files\n  }\n\n  // ── Metadata Store ──────────────────────────────────────────────────\n\n  get<T = any>(key: string): T | undefined {\n    return this.metadata.get(key) as T | undefined\n  }\n\n  set(key: string, value: any): void {\n    this.metadata.set(key, value)\n  }\n\n  // ── Response Helpers ────────────────────────────────────────────────\n\n  json(data: any, status = 200) {\n    return this.res.status(status).json(data)\n  }\n\n  created(data: any) {\n    return this.res.status(201).json(data)\n  }\n\n  noContent() {\n    return this.res.status(204).end()\n  }\n\n  notFound(message = 'Not Found') {\n    return this.res.status(404).json({ message })\n  }\n\n  badRequest(message: string) {\n    return this.res.status(400).json({ message })\n  }\n\n  html(content: string, status = 200) {\n    return this.res.status(status).type('html').send(content)\n  }\n\n  download(buffer: Buffer, filename: string, contentType = 'application/octet-stream') {\n    this.res.setHeader('Content-Disposition', `attachment; filename=\"${filename}\"`)\n    this.res.setHeader('Content-Type', contentType)\n    return this.res.send(buffer)\n  }\n}\n"],"mappings":";;;;;;;;AAOO,IAAMA,iBAAN,MAAMA;EANb,OAMaA;;;;;;EACHC,WAAW,oBAAIC,IAAAA;EAEvB,YACkBC,KACAC,KACAC,MAChB;SAHgBF,MAAAA;SACAC,MAAAA;SACAC,OAAAA;EACf;;EAIH,IAAIC,OAAc;AAChB,WAAO,KAAKH,IAAIG;EAClB;EAEA,IAAIC,SAAkB;AACpB,WAAO,KAAKJ,IAAII;EAClB;EAEA,IAAIC,QAAgB;AAClB,WAAO,KAAKL,IAAIK;EAClB;EAEA,IAAIC,UAAU;AACZ,WAAO,KAAKN,IAAIM;EAClB;EAEA,IAAIC,YAAgC;AAClC,WAAQ,KAAKP,IAAYO,aAAc,KAAKP,IAAIM,QAAQ,cAAA;EAC1D;;EAGA,IAAIE,UAAe;AACjB,WAAQ,KAAKR,IAAYQ;EAC3B;;;;;;;;;;;;;;;;;;;;;EAuBAC,GAAGC,aAA6C;AAC9C,WAAOC,WAAW,KAAKX,IAAIK,OAA8BK,WAAAA;EAC3D;;;EAKA,IAAIE,OAAY;AACd,WAAQ,KAAKZ,IAAYY;EAC3B;;EAGA,IAAIC,QAA2B;AAC7B,WAAQ,KAAKb,IAAYa;EAC3B;;EAIAC,IAAaC,KAA4B;AACvC,WAAO,KAAKjB,SAASgB,IAAIC,GAAAA;EAC3B;EAEAC,IAAID,KAAaE,OAAkB;AACjC,SAAKnB,SAASkB,IAAID,KAAKE,KAAAA;EACzB;;EAIAC,KAAKC,MAAWC,SAAS,KAAK;AAC5B,WAAO,KAAKnB,IAAImB,OAAOA,MAAAA,EAAQF,KAAKC,IAAAA;EACtC;EAEAE,QAAQF,MAAW;AACjB,WAAO,KAAKlB,IAAImB,OAAO,GAAA,EAAKF,KAAKC,IAAAA;EACnC;EAEAG,YAAY;AACV,WAAO,KAAKrB,IAAImB,OAAO,GAAA,EAAKG,IAAG;EACjC;EAEAC,SAASC,UAAU,aAAa;AAC9B,WAAO,KAAKxB,IAAImB,OAAO,GAAA,EAAKF,KAAK;MAAEO;IAAQ,CAAA;EAC7C;EAEAC,WAAWD,SAAiB;AAC1B,WAAO,KAAKxB,IAAImB,OAAO,GAAA,EAAKF,KAAK;MAAEO;IAAQ,CAAA;EAC7C;EAEAE,KAAKC,SAAiBR,SAAS,KAAK;AAClC,WAAO,KAAKnB,IAAImB,OAAOA,MAAAA,EAAQS,KAAK,MAAA,EAAQC,KAAKF,OAAAA;EACnD;EAEAG,SAASC,QAAgBC,UAAkBC,cAAc,4BAA4B;AACnF,SAAKjC,IAAIkC,UAAU,uBAAuB,yBAAyBF,QAAAA,GAAW;AAC9E,SAAKhC,IAAIkC,UAAU,gBAAgBD,WAAAA;AACnC,WAAO,KAAKjC,IAAI6B,KAAKE,MAAAA;EACvB;AACF;","names":["RequestContext","metadata","Map","req","res","next","body","params","query","headers","requestId","session","qs","fieldConfig","parseQuery","file","files","get","key","set","value","json","data","status","created","noContent","end","notFound","message","badRequest","html","content","type","send","download","buffer","filename","contentType","setHeader"]}

package/dist/chunk-OKB76LY2.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/application.ts"],"sourcesContent":["import http from 'node:http'\nimport express, { type Express, type RequestHandler } from 'express'\nimport {\n  Container,\n  createLogger,\n  type AppModuleClass,\n  type AppAdapter,\n  type AdapterMiddleware,\n} from '@forinda/kickjs-core'\nimport { buildRoutes } from './router-builder'\nimport { requestId } from './middleware/request-id'\nimport { notFoundHandler, errorHandler } from './middleware/error-handler'\n\nconst log = createLogger('Application')\n\n/**\n * A middleware entry in the declarative pipeline.\n * Can be a bare handler or an object with path scoping.\n */\nexport type MiddlewareEntry = RequestHandler | { path: string; handler: RequestHandler }\n\nexport interface ApplicationOptions {\n  /** Feature modules to load */\n  modules: AppModuleClass[]\n  /** Adapters that hook into the lifecycle (DB, Redis, Swagger, etc.) */\n  adapters?: AppAdapter[]\n  /** Server port (falls back to PORT env var, then 3000) */\n  port?: number\n  /** Global API prefix (default: '/api') */\n  apiPrefix?: string\n  /** Default API version (default: 1) — routes become /{prefix}/v{version}/{path} */\n  defaultVersion?: number\n\n  /**\n   * Global middleware pipeline. Declared in order.\n   * Replaces the hardcoded middleware stack — you control exactly what runs.\n   *\n   * @example\n   * ```ts\n   * bootstrap({\n   *   modules,\n   *   middleware: [\n   *     helmet(),\n   *     cors(),\n   *     compression(),\n   *     morgan('dev'),\n   *     express.json({ limit: '1mb' }),\n   *   ],\n   * })\n   * ```\n   *\n   * If omitted, a sensible default is applied:\n   *   requestId(), express.json({ limit: '100kb' })\n   */\n  middleware?: MiddlewareEntry[]\n\n  /** Express `trust proxy` setting */\n  trustProxy?: boolean | number | string | ((ip: string, hopIndex: number) => boolean)\n  /** Maximum JSON body size (only used when middleware is not provided) */\n  jsonLimit?: string | number\n}\n\n/**\n * The main application class. Wires together Express, the DI container,\n * feature modules, adapters, and the middleware pipeline.\n */\nexport class Application {\n  private app: Express\n  private container: Container\n  private httpServer: http.Server | null = null\n  private adapters: AppAdapter[]\n\n  constructor(private readonly options: ApplicationOptions) {\n    this.app = express()\n    this.container = Container.getInstance()\n    this.adapters = options.adapters ?? []\n  }\n\n  /**\n   * Full setup pipeline:\n   * 1. Adapter beforeMount hooks (early routes — docs, health)\n   * 2. Adapter middleware (phase: beforeGlobal)\n   * 3. Global middleware (user-declared or defaults)\n   * 4. Adapter middleware (phase: afterGlobal)\n   * 5. Module registration + DI bootstrap\n   * 6. Adapter middleware (phase: beforeRoutes)\n   * 7. Module route mounting\n   * 8. Adapter middleware (phase: afterRoutes)\n   * 9. Error handlers (notFound + global)\n   * 10. Adapter beforeStart hooks\n   */\n  setup(): void {\n    log.info('Bootstrapping application...')\n\n    // Collect adapter middleware by phase\n    const adapterMw = this.collectAdapterMiddleware()\n\n    // ── 1. Adapter beforeMount hooks ──────────────────────────────────\n    for (const adapter of this.adapters) {\n      adapter.beforeMount?.(this.app, this.container)\n    }\n\n    // ── 2. Hardened defaults ──────────────────────────────────────────\n    this.app.disable('x-powered-by')\n    this.app.set('trust proxy', this.options.trustProxy ?? false)\n\n    // ── 3. Adapter middleware: beforeGlobal ───────────────────────────\n    this.mountMiddlewareList(adapterMw.beforeGlobal)\n\n    // ── 4. Global middleware ─────────────────────────────────────────\n    if (this.options.middleware) {\n      // User-declared pipeline — full control\n      for (const entry of this.options.middleware) {\n        this.mountMiddlewareEntry(entry)\n      }\n    } else {\n      // Sensible defaults when no middleware declared\n      this.app.use(requestId())\n      this.app.use(express.json({ limit: this.options.jsonLimit ?? '100kb' }))\n    }\n\n    // ── 5. Adapter middleware: afterGlobal ────────────────────────────\n    this.mountMiddlewareList(adapterMw.afterGlobal)\n\n    // ── 6. Module registration + DI bootstrap ────────────────────────\n    const modules = this.options.modules.map((ModuleClass) => {\n      const mod = new ModuleClass()\n      mod.register(this.container)\n      return mod\n    })\n    this.container.bootstrap()\n\n    // ── 7. Adapter middleware: beforeRoutes ───────────────────────────\n    this.mountMiddlewareList(adapterMw.beforeRoutes)\n\n    // ── 8. Mount module routes with versioning ───────────────────────\n    const apiPrefix = this.options.apiPrefix ?? '/api'\n    const defaultVersion = this.options.defaultVersion ?? 1\n\n    for (const mod of modules) {\n      const result = mod.routes()\n      const routeSets = Array.isArray(result) ? result : [result]\n\n      for (const route of routeSets) {\n        const version = route.version ?? defaultVersion\n        const mountPath = `${apiPrefix}/v${version}${route.path}`\n        this.app.use(mountPath, route.router)\n\n        // Notify adapters (e.g. SwaggerAdapter for OpenAPI spec generation)\n        if (route.controller) {\n          for (const adapter of this.adapters) {\n            adapter.onRouteMount?.(route.controller, mountPath)\n          }\n        }\n      }\n    }\n\n    // ── 9. Adapter middleware: afterRoutes ────────────────────────────\n    this.mountMiddlewareList(adapterMw.afterRoutes)\n\n    // ── 10. Error handlers ───────────────────────────────────────────\n    this.app.use(notFoundHandler())\n    this.app.use(errorHandler())\n\n    // ── 11. Adapter beforeStart hooks ────────────────────────────────\n    for (const adapter of this.adapters) {\n      adapter.beforeStart?.(this.app, this.container)\n    }\n  }\n\n  /** Start the HTTP server — fails fast if port is in use */\n  start(): void {\n    this.setup()\n\n    const port = this.options.port ?? parseInt(process.env.PORT || '3000', 10)\n    this.httpServer = http.createServer(this.app)\n\n    this.httpServer.on('error', (err: NodeJS.ErrnoException) => {\n      if (err.code === 'EADDRINUSE') {\n        log.error(\n          `Port ${port} is already in use. Kill the existing process or use a different port:\\n` +\n            `  PORT=${port + 1} kick dev\\n` +\n            `  lsof -i :${port}   # find what's using it\\n` +\n            `  kill <PID>          # stop it`,\n        )\n        process.exit(1)\n      }\n      throw err\n    })\n\n    this.httpServer.listen(port, () => {\n      log.info(`Server running on http://localhost:${port}`)\n\n      for (const adapter of this.adapters) {\n        adapter.afterStart?.(this.httpServer!, this.container)\n      }\n    })\n  }\n\n  /** HMR rebuild: swap Express handler without restarting the server */\n  rebuild(): void {\n    // Reset the DI container so singletons are re-created with fresh code\n    Container.reset()\n    this.container = Container.getInstance()\n\n    this.app = express()\n    this.setup()\n\n    if (this.httpServer) {\n      this.httpServer.removeAllListeners('request')\n      this.httpServer.on('request', this.app)\n      log.info('HMR: Express app rebuilt and swapped')\n    }\n  }\n\n  /** Graceful shutdown — runs all adapter shutdowns in parallel, resilient to failures */\n  async shutdown(): Promise<void> {\n    log.info('Shutting down...')\n\n    // Run all adapter shutdowns concurrently — don't let one failure block the rest\n    const results = await Promise.allSettled(\n      this.adapters.map((adapter) => Promise.resolve(adapter.shutdown?.())),\n    )\n    for (const result of results) {\n      if (result.status === 'rejected') {\n        log.error({ err: result.reason }, 'Adapter shutdown failed')\n      }\n    }\n\n    if (this.httpServer) {\n      await new Promise<void>((resolve) => this.httpServer!.close(() => resolve()))\n    }\n  }\n\n  getExpressApp(): Express {\n    return this.app\n  }\n\n  getHttpServer(): http.Server | null {\n    return this.httpServer\n  }\n\n  // ── Internal helpers ────────────────────────────────────────────────\n\n  private collectAdapterMiddleware() {\n    const result = {\n      beforeGlobal: [] as AdapterMiddleware[],\n      afterGlobal: [] as AdapterMiddleware[],\n      beforeRoutes: [] as AdapterMiddleware[],\n      afterRoutes: [] as AdapterMiddleware[],\n    }\n\n    for (const adapter of this.adapters) {\n      const entries = adapter.middleware?.() ?? []\n      for (const entry of entries) {\n        const phase = entry.phase ?? 'afterGlobal'\n        result[phase].push(entry)\n      }\n    }\n\n    return result\n  }\n\n  private mountMiddlewareList(entries: AdapterMiddleware[]): void {\n    for (const entry of entries) {\n      if (entry.path) {\n        this.app.use(entry.path, entry.handler)\n      } else {\n        this.app.use(entry.handler)\n      }\n    }\n  }\n\n  private mountMiddlewareEntry(entry: MiddlewareEntry): void {\n    if (typeof entry === 'function') {\n      this.app.use(entry)\n    } else {\n      this.app.use(entry.path, entry.handler)\n    }\n  }\n}\n"],"mappings":"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","names":["http","express","Container","createLogger","log","createLogger","Application","app","container","httpServer","adapters","options","express","Container","getInstance","setup","info","adapterMw","collectAdapterMiddleware","adapter","beforeMount","disable","set","trustProxy","mountMiddlewareList","beforeGlobal","middleware","entry","mountMiddlewareEntry","use","requestId","json","limit","jsonLimit","afterGlobal","modules","map","ModuleClass","mod","register","bootstrap","beforeRoutes","apiPrefix","defaultVersion","result","routes","routeSets","Array","isArray","route","version","mountPath","path","router","controller","onRouteMount","afterRoutes","notFoundHandler","errorHandler","beforeStart","start","port","parseInt","process","env","PORT","http","createServer","on","err","code","error","exit","listen","afterStart","rebuild","reset","removeAllListeners","shutdown","results","Promise","allSettled","resolve","status","reason","close","getExpressApp","getHttpServer","entries","phase","push","handler"]}

package/dist/chunk-VXX2Y3TA.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/query/types.ts","../src/query/parse-query.ts"],"sourcesContent":["/** Supported filter operators for query string parsing */\nexport type FilterOperator =\n  | 'eq'\n  | 'neq'\n  | 'gt'\n  | 'gte'\n  | 'lt'\n  | 'lte'\n  | 'between'\n  | 'in'\n  | 'contains'\n  | 'starts'\n  | 'ends'\n\nexport const FILTER_OPERATORS = new Set<string>([\n  'eq',\n  'neq',\n  'gt',\n  'gte',\n  'lt',\n  'lte',\n  'between',\n  'in',\n  'contains',\n  'starts',\n  'ends',\n])\n\nexport interface FilterItem {\n  field: string\n  operator: FilterOperator\n  value: string\n}\n\nexport interface SortItem {\n  field: string\n  direction: 'asc' | 'desc'\n}\n\nexport interface PaginationParams {\n  page: number\n  limit: number\n  offset: number\n}\n\n/**\n * The result of parsing a query string. ORM-agnostic — pass this to\n * a query builder adapter (Drizzle, Prisma, Sequelize, etc.) to produce\n * database-specific query objects.\n */\nexport interface ParsedQuery {\n  filters: FilterItem[]\n  sort: SortItem[]\n  pagination: PaginationParams\n  search: string\n}\n\n/**\n * Restrict which fields can be filtered, sorted, or searched.\n * Fields not in the allow-list are silently ignored.\n */\nexport interface QueryFieldConfig {\n  filterable?: string[]\n  sortable?: string[]\n  searchable?: string[]\n}\n\n/**\n * Interface for ORM-specific query builder adapters.\n * Implement this to translate a `ParsedQuery` into your ORM's query format.\n *\n * @example\n * ```ts\n * // Drizzle adapter\n * class DrizzleQueryAdapter implements QueryBuilderAdapter<DrizzleQueryResult> {\n *   build(parsed: ParsedQuery, config: DrizzleConfig): DrizzleQueryResult {\n *     // Convert filters → Drizzle SQL conditions\n *     // Convert sort → Drizzle orderBy\n *     return { where, orderBy, limit, offset }\n *   }\n * }\n *\n * // Prisma adapter\n * class PrismaQueryAdapter implements QueryBuilderAdapter<PrismaQueryResult> {\n *   build(parsed: ParsedQuery, config: PrismaConfig): PrismaQueryResult {\n *     return { where, orderBy, skip, take }\n *   }\n * }\n * ```\n */\nexport interface QueryBuilderAdapter<TResult = any, TConfig = any> {\n  /** Human-readable name for debugging */\n  readonly name: string\n\n  /**\n   * Convert a ParsedQuery into an ORM-specific query object.\n   * @param parsed - The ORM-agnostic parsed query\n   * @param config - ORM-specific configuration (column maps, search columns, etc.)\n   */\n  build(parsed: ParsedQuery, config: TConfig): TResult\n}\n","import {\n  FILTER_OPERATORS,\n  type FilterItem,\n  type FilterOperator,\n  type SortItem,\n  type PaginationParams,\n  type ParsedQuery,\n  type QueryFieldConfig,\n} from './types'\n\nconst MAX_SEARCH_LENGTH = 200\nconst DEFAULT_PAGE = 1\nconst DEFAULT_LIMIT = 20\nconst MAX_LIMIT = 100\n\n// ── Individual parsers ──────────────────────────────────────────────────\n\n/** Parse filter strings like \"status:eq:active\" into structured objects */\nexport function parseFilters(\n  filterParam: string | string[] | undefined,\n  allowedFields?: string[],\n): FilterItem[] {\n  if (!filterParam) return []\n\n  const items = Array.isArray(filterParam) ? filterParam : [filterParam]\n  const results: FilterItem[] = []\n  const allowed = allowedFields ? new Set(allowedFields) : null\n\n  for (const item of items) {\n    // Split on first two colons only — value may contain colons (e.g. timestamps)\n    const firstColon = item.indexOf(':')\n    if (firstColon === -1) continue\n\n    const secondColon = item.indexOf(':', firstColon + 1)\n    if (secondColon === -1) continue\n\n    const field = item.slice(0, firstColon)\n    const operator = item.slice(firstColon + 1, secondColon)\n    const value = item.slice(secondColon + 1)\n\n    if (!field || !value) continue\n    if (!FILTER_OPERATORS.has(operator)) continue\n    if (allowed && !allowed.has(field)) continue\n\n    results.push({ field, operator: operator as FilterOperator, value })\n  }\n\n  return results\n}\n\n/** Parse sort strings like \"firstName:asc\" into structured objects */\nexport function parseSort(\n  sortParam: string | string[] | undefined,\n  allowedFields?: string[],\n): SortItem[] {\n  if (!sortParam) return []\n\n  const items = Array.isArray(sortParam) ? sortParam : [sortParam]\n  const results: SortItem[] = []\n  const allowed = allowedFields ? new Set(allowedFields) : null\n\n  for (const item of items) {\n    // Split on last colon so field names with colons work\n    const lastColon = item.lastIndexOf(':')\n    if (lastColon === -1) continue\n\n    const field = item.slice(0, lastColon)\n    const dir = item.slice(lastColon + 1).toLowerCase()\n\n    if (!field) continue\n    if (dir !== 'asc' && dir !== 'desc') continue\n    if (allowed && !allowed.has(field)) continue\n\n    results.push({ field, direction: dir })\n  }\n\n  return results\n}\n\n/** Parse page/limit into pagination with computed offset */\nexport function parsePagination(params: {\n  page?: string | number\n  limit?: string | number\n}): PaginationParams {\n  let page =\n    typeof params.page === 'string' ? parseInt(params.page, 10) : (params.page ?? DEFAULT_PAGE)\n  let limit =\n    typeof params.limit === 'string' ? parseInt(params.limit, 10) : (params.limit ?? DEFAULT_LIMIT)\n\n  if (isNaN(page) || page < 1) page = DEFAULT_PAGE\n  if (isNaN(limit) || limit < 1) limit = DEFAULT_LIMIT\n  if (limit > MAX_LIMIT) limit = MAX_LIMIT\n\n  return { page, limit, offset: (page - 1) * limit }\n}\n\n/** Sanitize and truncate search query */\nexport function parseSearchQuery(q: string | undefined): string {\n  if (!q) return ''\n  return q.trim().slice(0, MAX_SEARCH_LENGTH)\n}\n\n// ── Combined parser ─────────────────────────────────────────────────────\n\n/**\n * Parse a raw Express query object into a structured, ORM-agnostic ParsedQuery.\n *\n * @param query - Raw query string object from `req.query` or Zod-validated object\n * @param fieldConfig - Optional field restrictions (whitelist filterable/sortable/searchable)\n *\n * @example\n * ```ts\n * // In a controller\n * @Get('/')\n * async list(ctx: RequestContext) {\n *   const parsed = parseQuery(ctx.query, {\n *     filterable: ['status', 'priority'],\n *     sortable: ['createdAt', 'title'],\n *   })\n *   // Pass to your ORM query builder adapter\n *   const q = drizzleAdapter.build(parsed, { columns, searchColumns })\n * }\n * ```\n *\n * Query string format:\n * - Filters: `?filter=field:operator:value` (repeatable)\n * - Sort: `?sort=field:asc|desc` (repeatable)\n * - Pagination: `?page=1&limit=20`\n * - Search: `?q=search+term`\n *\n * Filter operators: eq, neq, gt, gte, lt, lte, between, in, contains, starts, ends\n */\nexport function parseQuery(\n  query: Record<string, any>,\n  fieldConfig?: QueryFieldConfig,\n): ParsedQuery {\n  return {\n    filters: parseFilters(query.filter, fieldConfig?.filterable),\n    sort: parseSort(query.sort, fieldConfig?.sortable),\n    pagination: parsePagination({ page: query.page, limit: query.limit }),\n    search: parseSearchQuery(query.q),\n  }\n}\n\n// ── Query URL builder (for client-side or testing) ──────────────────────\n\n/** Convert ParsedQuery back into query string parameters */\nexport function buildQueryParams(\n  parsed: Partial<ParsedQuery>,\n): Record<string, string | string[] | number> {\n  const params: Record<string, string | string[] | number> = {}\n\n  if (parsed.filters?.length) {\n    params.filter = parsed.filters.map((f) => `${f.field}:${f.operator}:${f.value}`)\n  }\n\n  if (parsed.sort?.length) {\n    params.sort = parsed.sort.map((s) => `${s.field}:${s.direction}`)\n  }\n\n  if (parsed.pagination) {\n    params.page = parsed.pagination.page\n    params.limit = parsed.pagination.limit\n  }\n\n  if (parsed.search) {\n    params.q = parsed.search\n  }\n\n  return params\n}\n"],"mappings":"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","names":["FILTER_OPERATORS","Set","MAX_SEARCH_LENGTH","DEFAULT_PAGE","DEFAULT_LIMIT","MAX_LIMIT","parseFilters","filterParam","allowedFields","items","Array","isArray","results","allowed","Set","item","firstColon","indexOf","secondColon","field","slice","operator","value","FILTER_OPERATORS","has","push","parseSort","sortParam","lastColon","lastIndexOf","dir","toLowerCase","direction","parsePagination","params","page","parseInt","limit","isNaN","offset","parseSearchQuery","q","trim","parseQuery","query","fieldConfig","filters","filter","filterable","sort","sortable","pagination","search","buildQueryParams","parsed","length","map","f","s"]}