@forinda/kickjs-http 0.5.0 → 0.5.2

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

@@ -1,6 +1,6 @@
 import {
   parseQuery
-} from "./chunk-VXX2Y3TA.js";
+} from "./chunk-WYY34UWG.js";
 import {
   __name
 } from "./chunk-WCQVDF3K.js";
@@ -106,9 +106,51 @@ 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);
+  }
 };
 
 export {
   RequestContext
 };
-//# sourceMappingURL=chunk-LQ6RSWMX.js.map
+//# sourceMappingURL=chunk-GDMORQ2P.js.map

package/dist/chunk-GDMORQ2P.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"],"mappings":";;;;;;;;AAYO,IAAMA,iBAAN,MAAMA;EAXb,OAWaA;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;EA0BA,MAAMI,SACJC,SACA3B,aACA;AACA,UAAM4B,SAAS,KAAK7B,GAAGC,WAAAA;AACvB,UAAM,EAAES,MAAMoB,MAAK,IAAK,MAAMF,QAAQC,MAAAA;AACtC,UAAM,EAAEE,MAAMC,MAAK,IAAKH,OAAOI;AAC/B,UAAMC,aAAaC,KAAKC,KAAKN,QAAQE,KAAAA,KAAU;AAE/C,UAAMK,WAAiC;MACrC3B;MACA4B,MAAM;QACJP;QACAC;QACAF;QACAI;QACAK,SAASR,OAAOG;QAChBM,SAAST,OAAO;MAClB;IACF;AAEA,WAAO,KAAKtB,KAAK4B,QAAAA;EACnB;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","paginate","fetcher","parsed","total","page","limit","pagination","totalPages","Math","ceil","response","meta","hasNext","hasPrev"]}

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

@@ -6,7 +6,7 @@ import {
 } from "./chunk-RPN7UFUO.js";
 import {
   RequestContext
-} from "./chunk-LQ6RSWMX.js";
+} from "./chunk-GDMORQ2P.js";
 import {
   __name
 } from "./chunk-WCQVDF3K.js";
@@ -66,4 +66,4 @@ export {
   getControllerPath,
   buildRoutes
 };
-//# sourceMappingURL=chunk-VFVMIFNZ.js.map
+//# sourceMappingURL=chunk-S7DJ5HF3.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-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,34 @@ 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>>>;
 }
 
 export { RequestContext };

package/dist/context.js

@@ -1,7 +1,7 @@
 import {
   RequestContext
-} from "./chunk-LQ6RSWMX.js";
-import "./chunk-VXX2Y3TA.js";
+} from "./chunk-GDMORQ2P.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

@@ -16,11 +16,11 @@ import {
 } from "./chunk-35NUARK7.js";
 import {
   DevToolsAdapter
-} from "./chunk-CNN7JFUB.js";
+} from "./chunk-YYT24FTH.js";
 import {
   buildRoutes,
   getControllerPath
-} from "./chunk-VFVMIFNZ.js";
+} from "./chunk-S7DJ5HF3.js";
 import {
   buildUploadMiddleware,
   cleanupFiles,
@@ -32,7 +32,7 @@ import {
 } from "./chunk-RPN7UFUO.js";
 import {
   RequestContext
-} from "./chunk-LQ6RSWMX.js";
+} from "./chunk-GDMORQ2P.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-S7DJ5HF3.js";
 import "./chunk-LEILPDMW.js";
 import "./chunk-RPN7UFUO.js";
-import "./chunk-LQ6RSWMX.js";
-import "./chunk-VXX2Y3TA.js";
+import "./chunk-GDMORQ2P.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.5.2",
   "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.5.2"
   },
   "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-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"]}