@querykitjs/class-validator 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,325 @@
+import { FilterOperator, Filter, Sort, SortDirection } from '@querykitjs/core';
+import { ValidationOptions, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+
+/**
+ * Xabar kataloglari — **yagona manba**. Har bir til bir xil kalitlar to'plamini
+ * to'ldiradi; kalitlarning o'zi shu yerdagi inglizcha katalogdan chiqadi.
+ *
+ * Paket xatoni kalit bilan qaytargani uchun tillar soni cheklanmagan: tarjima
+ * har doim iste'molchi tomonida (`nestjs-i18n` `I18nValidationPipe` yoki oddiy
+ * `formatMessage(key, args, catalog)`). Bu yerdagi uchta katalog shunchaki eng
+ * ko'p kerak bo'ladiganini qutidan beradi — hech biri majburiy emas.
+ *
+ * `QueryKitMessageCatalog` ataylab qat'iy (`Record<QueryKitMessageKey, string>`):
+ * inglizchaga yangi kalit qo'shilsa, qolgan kataloglar **compile-time**da yorilib
+ * beradi va eskirib qololmaydi.
+ */
+/**
+ * Inglizcha katalog — kalitlarning kanonik ro'yxati va default fallback.
+ * `{placeholder}` lar `formatMessage` bilan to'ldiriladi.
+ */
+declare const QUERYKIT_MESSAGES_EN: {
+    readonly "querykit.filter.invalid_node": "{path} must be a filter condition or an and/or/not group";
+    readonly "querykit.filter.missing_key": "{path} is missing the required `key` string";
+    readonly "querykit.filter.unknown_key": "{path}: `{key}` is not an allowed filter key";
+    readonly "querykit.filter.invalid_operator": "{path}: `{operation}` is not a supported filter operator";
+    readonly "querykit.filter.invalid_value": "{path} must be a string, number, boolean, null, or an array of those";
+    readonly "querykit.filter.invalid_group": "{path} must be an array of filter nodes";
+    readonly "querykit.filter.max_depth": "{path} exceeds the maximum filter depth of {max}";
+    readonly "querykit.filter.value_requires_array": "{path}: `{operation}` requires an array value";
+    readonly "querykit.filter.value_requires_tuple": "{path}: `{operation}` requires exactly two values";
+    readonly "querykit.filter.value_forbidden": "{path}: `{operation}` must not carry a value";
+    readonly "querykit.sort.not_array": "{path} must be an array of { key, direction } items";
+    readonly "querykit.sort.invalid_item": "{path} must be an object with a `key` string";
+    readonly "querykit.sort.missing_key": "{path} is missing the required `key` string";
+    readonly "querykit.sort.unknown_key": "{path}: `{key}` is not an allowed sort key";
+    readonly "querykit.sort.invalid_direction": "{path}: direction must be `asc` or `desc`";
+};
+/**
+ * Har bir validatsiya xatosining i18n kaliti. Union inglizcha katalogdan chiqadi —
+ * yangi xabar qo'shilsa tip o'zi kengayadi, qo'lda ro'yxat yuritilmaydi.
+ */
+type QueryKitMessageKey = keyof typeof QUERYKIT_MESSAGES_EN;
+/** Bitta tilning to'liq katalogi — barcha kalitlar majburiy. */
+type QueryKitMessageCatalog = Record<QueryKitMessageKey, string>;
+/** O'zbekcha katalog. Placeholder nomlari inglizchasi bilan bir xil. */
+declare const QUERYKIT_MESSAGES_UZ: QueryKitMessageCatalog;
+/** Ruscha katalog. */
+declare const QUERYKIT_MESSAGES_RU: QueryKitMessageCatalog;
+/**
+ * Til kodi → katalog. Qutidagi tillar; iste'molchi o'z katalogini shu shaklda
+ * qo'shib, `formatMessage`ga uzata oladi.
+ */
+declare const QUERYKIT_LOCALES: {
+    readonly en: {
+        readonly "querykit.filter.invalid_node": "{path} must be a filter condition or an and/or/not group";
+        readonly "querykit.filter.missing_key": "{path} is missing the required `key` string";
+        readonly "querykit.filter.unknown_key": "{path}: `{key}` is not an allowed filter key";
+        readonly "querykit.filter.invalid_operator": "{path}: `{operation}` is not a supported filter operator";
+        readonly "querykit.filter.invalid_value": "{path} must be a string, number, boolean, null, or an array of those";
+        readonly "querykit.filter.invalid_group": "{path} must be an array of filter nodes";
+        readonly "querykit.filter.max_depth": "{path} exceeds the maximum filter depth of {max}";
+        readonly "querykit.filter.value_requires_array": "{path}: `{operation}` requires an array value";
+        readonly "querykit.filter.value_requires_tuple": "{path}: `{operation}` requires exactly two values";
+        readonly "querykit.filter.value_forbidden": "{path}: `{operation}` must not carry a value";
+        readonly "querykit.sort.not_array": "{path} must be an array of { key, direction } items";
+        readonly "querykit.sort.invalid_item": "{path} must be an object with a `key` string";
+        readonly "querykit.sort.missing_key": "{path} is missing the required `key` string";
+        readonly "querykit.sort.unknown_key": "{path}: `{key}` is not an allowed sort key";
+        readonly "querykit.sort.invalid_direction": "{path}: direction must be `asc` or `desc`";
+    };
+    readonly uz: QueryKitMessageCatalog;
+    readonly ru: QueryKitMessageCatalog;
+};
+/** Qutidan chiqadigan til kodlari. */
+type QueryKitLocale = keyof typeof QUERYKIT_LOCALES;
+
+/**
+ * Xabar formatlash. Kataloglarning o'zi `locales.ts`da — bu fayl faqat
+ * `{placeholder}` interpolatsiyasini biladi va hech qanday tilga bog'lanmagan.
+ *
+ * Har bir {@link ValidationIssue} uchta narsani olib yuradi: `key` (tarjima
+ * kaliti), `message` (tayyor matn) va `args` (interpolatsiya qiymatlari). Shu
+ * sababli paket i18n'ga **majburlamaydi**, lekin unga to'liq mos.
+ */
+
+/** Shablon interpolatsiyasi argumentlari — `I18nValidationPipe`ga ham shu shaklda uzatiladi. */
+type MessageArgs = Record<string, string | number>;
+/**
+ * Kalitni matnga aylantiradi: katalogdan shablon olinadi va `{placeholder}` lar
+ * `args` bilan almashtiriladi. Mos argument topilmasa placeholder o'z holicha
+ * qoladi — xabar hech qachon bo'sh chiqmaydi.
+ *
+ * @param catalog Til katalogi. Default — inglizcha; `QUERYKIT_MESSAGES_UZ`,
+ *   `QUERYKIT_MESSAGES_RU` yoki o'zingizniki uzatilishi mumkin.
+ *
+ * @example
+ * ```ts
+ * formatMessage(issue.key, issue.args, QUERYKIT_MESSAGES_UZ);
+ * ```
+ */
+declare function formatMessage(key: QueryKitMessageKey, args?: MessageArgs, catalog?: QueryKitMessageCatalog): string;
+/**
+ * Issue'ni tanlangan tilda qayta formatlaydi — `message` inglizcha yozilgan
+ * bo'lsa ham, javobni boshqa tilda berish uchun.
+ *
+ * @example
+ * ```ts
+ * issues.map(issue => localizeIssue(issue, QUERYKIT_MESSAGES_RU));
+ * ```
+ */
+declare function localizeIssue(issue: {
+    key: QueryKitMessageKey;
+    args: MessageArgs;
+}, catalog: QueryKitMessageCatalog): string;
+
+/** Filter daraxti chuqurligi default limiti — cheklovsiz rekursiya DoS yuzasi. */
+declare const DEFAULT_MAX_FILTER_DEPTH = 5;
+interface QueryFilterOptions {
+    /**
+     * Berilsa — faqat shu kalitlarga ruxsat; noma'lum kalit **rad etiladi**.
+     * Backend adapterlari noma'lum kalitni jimgina tashlaydi, bu qatlam esa
+     * qat'iyroq: mijoz mavjud bo'lmagan maydon bo'yicha filtr yubora olmaydi.
+     * Berilmasa — istalgan string kalit o'tadi (`@querykitjs/zod` bilan parity).
+     */
+    allowedKeys?: readonly string[];
+    /** Ruxsat etilgan operatorlar. Default — core `FILTER_OPERATORS`ning hammasi. */
+    allowedOperators?: readonly FilterOperator[];
+    /** `and`/`or`/`not` tugunlarining chuqurlik limiti. Default — {@link DEFAULT_MAX_FILTER_DEPTH}. */
+    maxDepth?: number;
+    /**
+     * Operator↔qiymat shakli tekshiruvi (opt-in): `in`/`notIn` massiv talab qiladi,
+     * `between`/`notBetween` — aynan ikki element, `isNull`/`isNotNull` — qiymatsiz.
+     * Default `false`, ya'ni `@querykitjs/zod` bilan bir xil qat'iylik.
+     */
+    strictValue?: boolean;
+    /**
+     * `path`ning ildizi. Default `"filter"`. Dekorator buni DTO property nomiga
+     * qo'yadi, ya'ni `where` deb nomlangan maydon xatosi `filter.operation` emas,
+     * `where.operation` deb chiqadi.
+     */
+    rootPath?: string;
+}
+interface QuerySortOptions {
+    /** Berilsa — faqat shu kalitlar bo'yicha saralashga ruxsat. */
+    allowedKeys?: readonly string[];
+    /** `path`ning ildizi. Default `"sort"`. Qarang: {@link QueryFilterOptions.rootPath}. */
+    rootPath?: string;
+}
+/** Bitta validatsiya xatosi. */
+interface ValidationIssue {
+    /** Xato joyi, masalan `filter.and[1].or[0].value`. */
+    path: string;
+    /** i18n kaliti — iste'molchi tarjima faylida shu kalit qidiriladi. */
+    key: QueryKitMessageKey;
+    /** Tayyor inglizcha matn — tarjimasiz ham o'qiladi. */
+    message: string;
+    /** Interpolatsiya argumentlari (`path` har doim bor) — `I18nValidationPipe` uchun. */
+    args: MessageArgs;
+}
+/**
+ * Filter daraxtini core kontraktiga tekshiradi. Bo'sh massiv = valid.
+ *
+ * @example
+ * ```ts
+ * const issues = validateFilter(body.filter, { allowedKeys: ["id", "name"] });
+ * if (issues.length) throw new BadRequestException(issues);
+ * ```
+ */
+declare function validateFilter(value: unknown, options?: QueryFilterOptions): ValidationIssue[];
+/**
+ * Sort massivini core kontraktiga tekshiradi (`{ key, direction }[]`). Bo'sh massiv = valid.
+ */
+declare function validateSort(value: unknown, options?: QuerySortOptions): ValidationIssue[];
+
+/** Dekorator darajasidagi qo'shimcha — yadro buni o'qimaydi. */
+interface MessageStyleOptions {
+    /**
+     * Xato matni qanday shaklda qaytsin:
+     * - `"text"` (default) — tayyor inglizcha jumla, i18n'siz app ham o'qiydi;
+     * - `"key"` — `querykit.filter.*` kaliti, `nestjs-i18n`ning `I18nValidationPipe`i
+     *   uni so'rovning tiliga tarjima qiladi.
+     */
+    messageStyle?: "text" | "key";
+}
+type IsQueryFilterOptions = QueryFilterOptions & MessageStyleOptions;
+type IsQuerySortOptions = QuerySortOptions & MessageStyleOptions;
+/** `@IsQueryFilter()` ortidagi konstraint — test va qayta ishlatish uchun ochiq. */
+declare class IsQueryFilterConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args?: ValidationArguments): boolean;
+    defaultMessage(args?: ValidationArguments): string;
+}
+/** `@IsQuerySort()` ortidagi konstraint. */
+declare class IsQuerySortConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args?: ValidationArguments): boolean;
+    defaultMessage(args?: ValidationArguments): string;
+}
+/**
+ * Property'ni querykit `Filter` kontraktiga tekshiradi: flat massiv (implicit AND),
+ * nested `and`/`or`/`not` daraxti va core `FILTER_OPERATORS`ning to'liq to'plami.
+ *
+ * `undefined` qiymatni **rad etmaydi** — maydonni ixtiyoriy qilish uchun
+ * `@IsOptional()` bilan birga ishlating (DTO'lardagi kabi).
+ *
+ * @example
+ * ```ts
+ * class ListUsersDto extends OffsetParamsDto {
+ *   @IsOptional()
+ *   @IsQueryFilter({ allowedKeys: ["id", "name", "createdAt"] })
+ *   declare filter?: Filter;
+ * }
+ * ```
+ */
+declare function IsQueryFilter(options?: IsQueryFilterOptions, validationOptions?: ValidationOptions): PropertyDecorator;
+/**
+ * Property'ni querykit `Sort` kontraktiga tekshiradi — `{ key, direction }[]`.
+ * Qarang: {@link IsQueryFilter}.
+ */
+declare function IsQuerySort(options?: IsQuerySortOptions, validationOptions?: ValidationOptions): PropertyDecorator;
+
+/** Paginatsiyasiz umumiy params — `filter` + `sort`. */
+declare class BaseParamsDto {
+    filter?: Filter;
+    sort?: Sort;
+}
+/** Offset (sahifali) params — `page` + `perPage` (`perPage` ≤ core cap). */
+declare class OffsetParamsDto extends BaseParamsDto {
+    page?: number;
+    perPage?: number;
+}
+/** Infinite-scroll params — `limit` + `offset`. */
+declare class InfiniteParamsDto extends BaseParamsDto {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Cursor (keyset) params. `sort` **yo'q**: tartib `order` + `direction` bilan
+ * boshqariladi. Shu sababli `BaseParamsDto`dan meros olinmaydi — aks holda
+ * `sort` kontraktga qarshi ravishda meros bo'lib qolardi.
+ */
+declare class CursorParamsDto {
+    filter?: Filter;
+    limit?: number;
+    cursor?: string | null;
+    cursorKey?: string;
+    order?: SortDirection;
+    direction?: "forward" | "backward";
+}
+/** Server'ga tegishli, default'da clientdan qabul qilinmaydigan maydonlar. */
+type ServerOwnedField = "columns" | "with" | "withDeleted";
+/** `allow` bilan ochiladigan maydonlarning shakli. */
+interface ServerOwnedParams {
+    columns?: Record<string, boolean>;
+    with?: Record<string, unknown>;
+    withDeleted?: boolean;
+}
+interface ParamsDtoOptions {
+    /** `filter` uchun to'liq opsiyalar — `allowedKeys`, `allowedOperators`, `maxDepth`, `strictValue`, `messageStyle`. */
+    filter?: IsQueryFilterOptions;
+    /** `sort` uchun opsiyalar — `allowedKeys`, `messageStyle`. */
+    sort?: IsQuerySortOptions;
+    /**
+     * `filter` va `sort` uchun umumiy allowlist qisqartmasi — odatda ikkalasi bir xil.
+     * Aniq berilgan `filter.allowedKeys` / `sort.allowedKeys` bundan **ustun**.
+     */
+    allowedKeys?: readonly string[];
+    /** `perPage` yuqori chegarasi. Default — core `DEFAULT_MAX_PER_PAGE` (200). `Infinity` — cap yo'q (⚠️ DoS). */
+    maxPerPage?: number;
+    /** `limit` yuqori chegarasi. Default — core `DEFAULT_MAX_LIMIT` (200). */
+    maxLimit?: number;
+    /** Server-owned maydonlarni **ataylab** ochish. Default — bo'sh. */
+    allow?: readonly ServerOwnedField[];
+}
+/**
+ * Offset (sahifali) params DTO'si — `allowedKeys` va cap'lar bilan.
+ *
+ * @example
+ * ```ts
+ * const ListBuyersDto = makeOffsetParamsDto({ allowedKeys: ["buyerName", "createdAt"] });
+ * type ListBuyersDto = InstanceType<typeof ListBuyersDto>;
+ *
+ * @Post("list")
+ * list(@Body() params: ListBuyersDto) {
+ *   return this.buyersRepository.findList(params);
+ * }
+ * ```
+ */
+declare function makeOffsetParamsDto(options?: ParamsDtoOptions): {
+    new (): {
+        filter?: Filter;
+        sort?: Sort;
+        page?: number;
+        perPage?: number;
+        columns?: Record<string, boolean>;
+        with?: Record<string, unknown>;
+        withDeleted?: boolean;
+    };
+};
+/** Infinite-scroll params DTO'si. Qarang: {@link makeOffsetParamsDto}. */
+declare function makeInfiniteParamsDto(options?: ParamsDtoOptions): {
+    new (): {
+        filter?: Filter;
+        sort?: Sort;
+        limit?: number;
+        offset?: number;
+        columns?: Record<string, boolean>;
+        with?: Record<string, unknown>;
+        withDeleted?: boolean;
+    };
+};
+/** Cursor (keyset) params DTO'si — `sort` yo'q. Qarang: {@link makeOffsetParamsDto}. */
+declare function makeCursorParamsDto(options?: ParamsDtoOptions): {
+    new (): {
+        filter?: Filter;
+        limit?: number;
+        cursor?: string | null;
+        cursorKey?: string;
+        order?: SortDirection;
+        direction?: "forward" | "backward";
+        columns?: Record<string, boolean>;
+        with?: Record<string, unknown>;
+        withDeleted?: boolean;
+    };
+};
+
+export { BaseParamsDto, CursorParamsDto, DEFAULT_MAX_FILTER_DEPTH, InfiniteParamsDto, IsQueryFilter, IsQueryFilterConstraint, type IsQueryFilterOptions, IsQuerySort, IsQuerySortConstraint, type IsQuerySortOptions, type MessageArgs, type MessageStyleOptions, OffsetParamsDto, type ParamsDtoOptions, QUERYKIT_LOCALES, QUERYKIT_MESSAGES_EN, QUERYKIT_MESSAGES_RU, QUERYKIT_MESSAGES_UZ, type QueryFilterOptions, type QueryKitLocale, type QueryKitMessageCatalog, type QueryKitMessageKey, type QuerySortOptions, type ServerOwnedField, type ServerOwnedParams, type ValidationIssue, formatMessage, localizeIssue, makeCursorParamsDto, makeInfiniteParamsDto, makeOffsetParamsDto, validateFilter, validateSort };

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+import { FilterOperator, Filter, Sort, SortDirection } from '@querykitjs/core';
+import { ValidationOptions, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+
+/**
+ * Xabar kataloglari — **yagona manba**. Har bir til bir xil kalitlar to'plamini
+ * to'ldiradi; kalitlarning o'zi shu yerdagi inglizcha katalogdan chiqadi.
+ *
+ * Paket xatoni kalit bilan qaytargani uchun tillar soni cheklanmagan: tarjima
+ * har doim iste'molchi tomonida (`nestjs-i18n` `I18nValidationPipe` yoki oddiy
+ * `formatMessage(key, args, catalog)`). Bu yerdagi uchta katalog shunchaki eng
+ * ko'p kerak bo'ladiganini qutidan beradi — hech biri majburiy emas.
+ *
+ * `QueryKitMessageCatalog` ataylab qat'iy (`Record<QueryKitMessageKey, string>`):
+ * inglizchaga yangi kalit qo'shilsa, qolgan kataloglar **compile-time**da yorilib
+ * beradi va eskirib qololmaydi.
+ */
+/**
+ * Inglizcha katalog — kalitlarning kanonik ro'yxati va default fallback.
+ * `{placeholder}` lar `formatMessage` bilan to'ldiriladi.
+ */
+declare const QUERYKIT_MESSAGES_EN: {
+    readonly "querykit.filter.invalid_node": "{path} must be a filter condition or an and/or/not group";
+    readonly "querykit.filter.missing_key": "{path} is missing the required `key` string";
+    readonly "querykit.filter.unknown_key": "{path}: `{key}` is not an allowed filter key";
+    readonly "querykit.filter.invalid_operator": "{path}: `{operation}` is not a supported filter operator";
+    readonly "querykit.filter.invalid_value": "{path} must be a string, number, boolean, null, or an array of those";
+    readonly "querykit.filter.invalid_group": "{path} must be an array of filter nodes";
+    readonly "querykit.filter.max_depth": "{path} exceeds the maximum filter depth of {max}";
+    readonly "querykit.filter.value_requires_array": "{path}: `{operation}` requires an array value";
+    readonly "querykit.filter.value_requires_tuple": "{path}: `{operation}` requires exactly two values";
+    readonly "querykit.filter.value_forbidden": "{path}: `{operation}` must not carry a value";
+    readonly "querykit.sort.not_array": "{path} must be an array of { key, direction } items";
+    readonly "querykit.sort.invalid_item": "{path} must be an object with a `key` string";
+    readonly "querykit.sort.missing_key": "{path} is missing the required `key` string";
+    readonly "querykit.sort.unknown_key": "{path}: `{key}` is not an allowed sort key";
+    readonly "querykit.sort.invalid_direction": "{path}: direction must be `asc` or `desc`";
+};
+/**
+ * Har bir validatsiya xatosining i18n kaliti. Union inglizcha katalogdan chiqadi —
+ * yangi xabar qo'shilsa tip o'zi kengayadi, qo'lda ro'yxat yuritilmaydi.
+ */
+type QueryKitMessageKey = keyof typeof QUERYKIT_MESSAGES_EN;
+/** Bitta tilning to'liq katalogi — barcha kalitlar majburiy. */
+type QueryKitMessageCatalog = Record<QueryKitMessageKey, string>;
+/** O'zbekcha katalog. Placeholder nomlari inglizchasi bilan bir xil. */
+declare const QUERYKIT_MESSAGES_UZ: QueryKitMessageCatalog;
+/** Ruscha katalog. */
+declare const QUERYKIT_MESSAGES_RU: QueryKitMessageCatalog;
+/**
+ * Til kodi → katalog. Qutidagi tillar; iste'molchi o'z katalogini shu shaklda
+ * qo'shib, `formatMessage`ga uzata oladi.
+ */
+declare const QUERYKIT_LOCALES: {
+    readonly en: {
+        readonly "querykit.filter.invalid_node": "{path} must be a filter condition or an and/or/not group";
+        readonly "querykit.filter.missing_key": "{path} is missing the required `key` string";
+        readonly "querykit.filter.unknown_key": "{path}: `{key}` is not an allowed filter key";
+        readonly "querykit.filter.invalid_operator": "{path}: `{operation}` is not a supported filter operator";
+        readonly "querykit.filter.invalid_value": "{path} must be a string, number, boolean, null, or an array of those";
+        readonly "querykit.filter.invalid_group": "{path} must be an array of filter nodes";
+        readonly "querykit.filter.max_depth": "{path} exceeds the maximum filter depth of {max}";
+        readonly "querykit.filter.value_requires_array": "{path}: `{operation}` requires an array value";
+        readonly "querykit.filter.value_requires_tuple": "{path}: `{operation}` requires exactly two values";
+        readonly "querykit.filter.value_forbidden": "{path}: `{operation}` must not carry a value";
+        readonly "querykit.sort.not_array": "{path} must be an array of { key, direction } items";
+        readonly "querykit.sort.invalid_item": "{path} must be an object with a `key` string";
+        readonly "querykit.sort.missing_key": "{path} is missing the required `key` string";
+        readonly "querykit.sort.unknown_key": "{path}: `{key}` is not an allowed sort key";
+        readonly "querykit.sort.invalid_direction": "{path}: direction must be `asc` or `desc`";
+    };
+    readonly uz: QueryKitMessageCatalog;
+    readonly ru: QueryKitMessageCatalog;
+};
+/** Qutidan chiqadigan til kodlari. */
+type QueryKitLocale = keyof typeof QUERYKIT_LOCALES;
+
+/**
+ * Xabar formatlash. Kataloglarning o'zi `locales.ts`da — bu fayl faqat
+ * `{placeholder}` interpolatsiyasini biladi va hech qanday tilga bog'lanmagan.
+ *
+ * Har bir {@link ValidationIssue} uchta narsani olib yuradi: `key` (tarjima
+ * kaliti), `message` (tayyor matn) va `args` (interpolatsiya qiymatlari). Shu
+ * sababli paket i18n'ga **majburlamaydi**, lekin unga to'liq mos.
+ */
+
+/** Shablon interpolatsiyasi argumentlari — `I18nValidationPipe`ga ham shu shaklda uzatiladi. */
+type MessageArgs = Record<string, string | number>;
+/**
+ * Kalitni matnga aylantiradi: katalogdan shablon olinadi va `{placeholder}` lar
+ * `args` bilan almashtiriladi. Mos argument topilmasa placeholder o'z holicha
+ * qoladi — xabar hech qachon bo'sh chiqmaydi.
+ *
+ * @param catalog Til katalogi. Default — inglizcha; `QUERYKIT_MESSAGES_UZ`,
+ *   `QUERYKIT_MESSAGES_RU` yoki o'zingizniki uzatilishi mumkin.
+ *
+ * @example
+ * ```ts
+ * formatMessage(issue.key, issue.args, QUERYKIT_MESSAGES_UZ);
+ * ```
+ */
+declare function formatMessage(key: QueryKitMessageKey, args?: MessageArgs, catalog?: QueryKitMessageCatalog): string;
+/**
+ * Issue'ni tanlangan tilda qayta formatlaydi — `message` inglizcha yozilgan
+ * bo'lsa ham, javobni boshqa tilda berish uchun.
+ *
+ * @example
+ * ```ts
+ * issues.map(issue => localizeIssue(issue, QUERYKIT_MESSAGES_RU));
+ * ```
+ */
+declare function localizeIssue(issue: {
+    key: QueryKitMessageKey;
+    args: MessageArgs;
+}, catalog: QueryKitMessageCatalog): string;
+
+/** Filter daraxti chuqurligi default limiti — cheklovsiz rekursiya DoS yuzasi. */
+declare const DEFAULT_MAX_FILTER_DEPTH = 5;
+interface QueryFilterOptions {
+    /**
+     * Berilsa — faqat shu kalitlarga ruxsat; noma'lum kalit **rad etiladi**.
+     * Backend adapterlari noma'lum kalitni jimgina tashlaydi, bu qatlam esa
+     * qat'iyroq: mijoz mavjud bo'lmagan maydon bo'yicha filtr yubora olmaydi.
+     * Berilmasa — istalgan string kalit o'tadi (`@querykitjs/zod` bilan parity).
+     */
+    allowedKeys?: readonly string[];
+    /** Ruxsat etilgan operatorlar. Default — core `FILTER_OPERATORS`ning hammasi. */
+    allowedOperators?: readonly FilterOperator[];
+    /** `and`/`or`/`not` tugunlarining chuqurlik limiti. Default — {@link DEFAULT_MAX_FILTER_DEPTH}. */
+    maxDepth?: number;
+    /**
+     * Operator↔qiymat shakli tekshiruvi (opt-in): `in`/`notIn` massiv talab qiladi,
+     * `between`/`notBetween` — aynan ikki element, `isNull`/`isNotNull` — qiymatsiz.
+     * Default `false`, ya'ni `@querykitjs/zod` bilan bir xil qat'iylik.
+     */
+    strictValue?: boolean;
+    /**
+     * `path`ning ildizi. Default `"filter"`. Dekorator buni DTO property nomiga
+     * qo'yadi, ya'ni `where` deb nomlangan maydon xatosi `filter.operation` emas,
+     * `where.operation` deb chiqadi.
+     */
+    rootPath?: string;
+}
+interface QuerySortOptions {
+    /** Berilsa — faqat shu kalitlar bo'yicha saralashga ruxsat. */
+    allowedKeys?: readonly string[];
+    /** `path`ning ildizi. Default `"sort"`. Qarang: {@link QueryFilterOptions.rootPath}. */
+    rootPath?: string;
+}
+/** Bitta validatsiya xatosi. */
+interface ValidationIssue {
+    /** Xato joyi, masalan `filter.and[1].or[0].value`. */
+    path: string;
+    /** i18n kaliti — iste'molchi tarjima faylida shu kalit qidiriladi. */
+    key: QueryKitMessageKey;
+    /** Tayyor inglizcha matn — tarjimasiz ham o'qiladi. */
+    message: string;
+    /** Interpolatsiya argumentlari (`path` har doim bor) — `I18nValidationPipe` uchun. */
+    args: MessageArgs;
+}
+/**
+ * Filter daraxtini core kontraktiga tekshiradi. Bo'sh massiv = valid.
+ *
+ * @example
+ * ```ts
+ * const issues = validateFilter(body.filter, { allowedKeys: ["id", "name"] });
+ * if (issues.length) throw new BadRequestException(issues);
+ * ```
+ */
+declare function validateFilter(value: unknown, options?: QueryFilterOptions): ValidationIssue[];
+/**
+ * Sort massivini core kontraktiga tekshiradi (`{ key, direction }[]`). Bo'sh massiv = valid.
+ */
+declare function validateSort(value: unknown, options?: QuerySortOptions): ValidationIssue[];
+
+/** Dekorator darajasidagi qo'shimcha — yadro buni o'qimaydi. */
+interface MessageStyleOptions {
+    /**
+     * Xato matni qanday shaklda qaytsin:
+     * - `"text"` (default) — tayyor inglizcha jumla, i18n'siz app ham o'qiydi;
+     * - `"key"` — `querykit.filter.*` kaliti, `nestjs-i18n`ning `I18nValidationPipe`i
+     *   uni so'rovning tiliga tarjima qiladi.
+     */
+    messageStyle?: "text" | "key";
+}
+type IsQueryFilterOptions = QueryFilterOptions & MessageStyleOptions;
+type IsQuerySortOptions = QuerySortOptions & MessageStyleOptions;
+/** `@IsQueryFilter()` ortidagi konstraint — test va qayta ishlatish uchun ochiq. */
+declare class IsQueryFilterConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args?: ValidationArguments): boolean;
+    defaultMessage(args?: ValidationArguments): string;
+}
+/** `@IsQuerySort()` ortidagi konstraint. */
+declare class IsQuerySortConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args?: ValidationArguments): boolean;
+    defaultMessage(args?: ValidationArguments): string;
+}
+/**
+ * Property'ni querykit `Filter` kontraktiga tekshiradi: flat massiv (implicit AND),
+ * nested `and`/`or`/`not` daraxti va core `FILTER_OPERATORS`ning to'liq to'plami.
+ *
+ * `undefined` qiymatni **rad etmaydi** — maydonni ixtiyoriy qilish uchun
+ * `@IsOptional()` bilan birga ishlating (DTO'lardagi kabi).
+ *
+ * @example
+ * ```ts
+ * class ListUsersDto extends OffsetParamsDto {
+ *   @IsOptional()
+ *   @IsQueryFilter({ allowedKeys: ["id", "name", "createdAt"] })
+ *   declare filter?: Filter;
+ * }
+ * ```
+ */
+declare function IsQueryFilter(options?: IsQueryFilterOptions, validationOptions?: ValidationOptions): PropertyDecorator;
+/**
+ * Property'ni querykit `Sort` kontraktiga tekshiradi — `{ key, direction }[]`.
+ * Qarang: {@link IsQueryFilter}.
+ */
+declare function IsQuerySort(options?: IsQuerySortOptions, validationOptions?: ValidationOptions): PropertyDecorator;
+
+/** Paginatsiyasiz umumiy params — `filter` + `sort`. */
+declare class BaseParamsDto {
+    filter?: Filter;
+    sort?: Sort;
+}
+/** Offset (sahifali) params — `page` + `perPage` (`perPage` ≤ core cap). */
+declare class OffsetParamsDto extends BaseParamsDto {
+    page?: number;
+    perPage?: number;
+}
+/** Infinite-scroll params — `limit` + `offset`. */
+declare class InfiniteParamsDto extends BaseParamsDto {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Cursor (keyset) params. `sort` **yo'q**: tartib `order` + `direction` bilan
+ * boshqariladi. Shu sababli `BaseParamsDto`dan meros olinmaydi — aks holda
+ * `sort` kontraktga qarshi ravishda meros bo'lib qolardi.
+ */
+declare class CursorParamsDto {
+    filter?: Filter;
+    limit?: number;
+    cursor?: string | null;
+    cursorKey?: string;
+    order?: SortDirection;
+    direction?: "forward" | "backward";
+}
+/** Server'ga tegishli, default'da clientdan qabul qilinmaydigan maydonlar. */
+type ServerOwnedField = "columns" | "with" | "withDeleted";
+/** `allow` bilan ochiladigan maydonlarning shakli. */
+interface ServerOwnedParams {
+    columns?: Record<string, boolean>;
+    with?: Record<string, unknown>;
+    withDeleted?: boolean;
+}
+interface ParamsDtoOptions {
+    /** `filter` uchun to'liq opsiyalar — `allowedKeys`, `allowedOperators`, `maxDepth`, `strictValue`, `messageStyle`. */
+    filter?: IsQueryFilterOptions;
+    /** `sort` uchun opsiyalar — `allowedKeys`, `messageStyle`. */
+    sort?: IsQuerySortOptions;
+    /**
+     * `filter` va `sort` uchun umumiy allowlist qisqartmasi — odatda ikkalasi bir xil.
+     * Aniq berilgan `filter.allowedKeys` / `sort.allowedKeys` bundan **ustun**.
+     */
+    allowedKeys?: readonly string[];
+    /** `perPage` yuqori chegarasi. Default — core `DEFAULT_MAX_PER_PAGE` (200). `Infinity` — cap yo'q (⚠️ DoS). */
+    maxPerPage?: number;
+    /** `limit` yuqori chegarasi. Default — core `DEFAULT_MAX_LIMIT` (200). */
+    maxLimit?: number;
+    /** Server-owned maydonlarni **ataylab** ochish. Default — bo'sh. */
+    allow?: readonly ServerOwnedField[];
+}
+/**
+ * Offset (sahifali) params DTO'si — `allowedKeys` va cap'lar bilan.
+ *
+ * @example
+ * ```ts
+ * const ListBuyersDto = makeOffsetParamsDto({ allowedKeys: ["buyerName", "createdAt"] });
+ * type ListBuyersDto = InstanceType<typeof ListBuyersDto>;
+ *
+ * @Post("list")
+ * list(@Body() params: ListBuyersDto) {
+ *   return this.buyersRepository.findList(params);
+ * }
+ * ```
+ */
+declare function makeOffsetParamsDto(options?: ParamsDtoOptions): {
+    new (): {
+        filter?: Filter;
+        sort?: Sort;
+        page?: number;
+        perPage?: number;
+        columns?: Record<string, boolean>;
+        with?: Record<string, unknown>;
+        withDeleted?: boolean;
+    };
+};
+/** Infinite-scroll params DTO'si. Qarang: {@link makeOffsetParamsDto}. */
+declare function makeInfiniteParamsDto(options?: ParamsDtoOptions): {
+    new (): {
+        filter?: Filter;
+        sort?: Sort;
+        limit?: number;
+        offset?: number;
+        columns?: Record<string, boolean>;
+        with?: Record<string, unknown>;
+        withDeleted?: boolean;
+    };
+};
+/** Cursor (keyset) params DTO'si — `sort` yo'q. Qarang: {@link makeOffsetParamsDto}. */
+declare function makeCursorParamsDto(options?: ParamsDtoOptions): {
+    new (): {
+        filter?: Filter;
+        limit?: number;
+        cursor?: string | null;
+        cursorKey?: string;
+        order?: SortDirection;
+        direction?: "forward" | "backward";
+        columns?: Record<string, boolean>;
+        with?: Record<string, unknown>;
+        withDeleted?: boolean;
+    };
+};
+
+export { BaseParamsDto, CursorParamsDto, DEFAULT_MAX_FILTER_DEPTH, InfiniteParamsDto, IsQueryFilter, IsQueryFilterConstraint, type IsQueryFilterOptions, IsQuerySort, IsQuerySortConstraint, type IsQuerySortOptions, type MessageArgs, type MessageStyleOptions, OffsetParamsDto, type ParamsDtoOptions, QUERYKIT_LOCALES, QUERYKIT_MESSAGES_EN, QUERYKIT_MESSAGES_RU, QUERYKIT_MESSAGES_UZ, type QueryFilterOptions, type QueryKitLocale, type QueryKitMessageCatalog, type QueryKitMessageKey, type QuerySortOptions, type ServerOwnedField, type ServerOwnedParams, type ValidationIssue, formatMessage, localizeIssue, makeCursorParamsDto, makeInfiniteParamsDto, makeOffsetParamsDto, validateFilter, validateSort };