@querykitjs/class-validator 1.0.0 → 2.0.1

package/dist/index.d.ts

@@ -1,6 +1,32 @@
-import { FilterOperator, Filter, Sort, SortDirection } from '@querykitjs/core';
+import { QueryKitMessageKey, MessageArgs, QueryKitMessageCatalog } from '@querykitjs/core/internal';
+export { MessageArgs, QUERYKIT_MESSAGES_EN, QueryKitMessageCatalog, QueryKitMessageKey, formatMessage } from '@querykitjs/core/internal';
+import { FilterOperator, Filter, Sort, SortDirection, QueryLimits } from '@querykitjs/core';
+export { DEFAULT_MAX_FILTER_DEPTH } from '@querykitjs/core';
 import { ValidationOptions, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
 
+/**
+ * Xabar formatlash. Kataloglar `locales.ts`da; `formatMessage` core'da
+ * (boshqa validatorlar bilan bitta), bu yerda faqat `localizeIssue`.
+ *
+ * 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.
+ */
+
+/**
+ * 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;
+
 /**
  * Xabar kataloglari — **yagona manba**. Har bir til bir xil kalitlar to'plamini
  * to'ldiradi; kalitlarning o'zi shu yerdagi inglizcha katalogdan chiqadi.
@@ -14,34 +40,7 @@ import { ValidationOptions, ValidatorConstraintInterface, ValidationArguments }
  * 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. */
@@ -58,7 +57,7 @@ declare const QUERYKIT_LOCALES: {
         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.max_depth": "{path} exceeds maxDepth ({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";
@@ -67,6 +66,7 @@ declare const QUERYKIT_LOCALES: {
         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 "querykit.limit.exceeded": "{path} exceeds {limit} ({max})";
     };
     readonly uz: QueryKitMessageCatalog;
     readonly ru: QueryKitMessageCatalog;
@@ -75,46 +75,13 @@ declare const QUERYKIT_LOCALES: {
 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));
- * ```
+ * Sof TS validatsiya yadrosi — **framework-agnostik**. Tekshiruv mantiqi core
+ * `checkFilter`/`checkSort` da (`@querykitjs/core/internal`) — boshqa validatorlar
+ * bilan bitta; bu yerda faqat yo'l satri va xabar matni quriladi.
+ * `class-validator` dekoratorlari (`decorators.ts`) faqat yupqa o'rov, shuning
+ * uchun yadroni Nest'siz ham (Express, Hono, oddiy funksiya) ishlatish mumkin.
  */
-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**.
@@ -125,8 +92,14 @@ interface QueryFilterOptions {
     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}. */
+    /** Ildizdan bargacha tugunlar soni (ildiz 1, har `and`/`or`/`not` va shart +1). Default — core `DEFAULT_MAX_FILTER_DEPTH` (5). */
     maxDepth?: number;
+    /** Barcha guruhlardagi shartlar (barglar) soni. Default — core `DEFAULT_MAX_CONDITIONS` (30). */
+    maxConditions?: number;
+    /** Bitta massiv qiymatdagi elementlar (`in`, `notIn`, …). Default — core `DEFAULT_MAX_IN_ITEMS` (200). */
+    maxInItems?: number;
+    /** Bitta satr qiymatdagi belgilar (massiv ichida ham). Default — core `DEFAULT_MAX_STRING_LENGTH` (256). */
+    maxStringLength?: number;
     /**
      * Operator↔qiymat shakli tekshiruvi (opt-in): `in`/`notIn` massiv talab qiladi,
      * `between`/`notBetween` — aynan ikki element, `isNull`/`isNotNull` — qiymatsiz.
@@ -143,6 +116,8 @@ interface QueryFilterOptions {
 interface QuerySortOptions {
     /** Berilsa — faqat shu kalitlar bo'yicha saralashga ruxsat. */
     allowedKeys?: readonly string[];
+    /** `sort` massividagi maydonlar soni. Default — core `DEFAULT_MAX_SORT_FIELDS` (3). */
+    maxSortFields?: number;
     /** `path`ning ildizi. Default `"sort"`. Qarang: {@link QueryFilterOptions.rootPath}. */
     rootPath?: string;
 }
@@ -194,6 +169,34 @@ declare class IsQuerySortConstraint implements ValidatorConstraintInterface {
     validate(value: unknown, args?: ValidationArguments): boolean;
     defaultMessage(args?: ValidationArguments): string;
 }
+/** `@IsWithinMaxOffset()` opsiyalari. */
+interface IsWithinMaxOffsetOptions {
+    /**
+     * `"page"` — property `page`, offset `(page - 1) × perPage` (o'sha obyektning `perPage`i,
+     * yo'q bo'lsa core `DEFAULT_PER_PAGE`); `"offset"` — property qiymatining o'zi (infinite).
+     */
+    mode: "page" | "offset";
+    /** Default — core `DEFAULT_MAX_OFFSET` (10 000). `Infinity` tekshiruvni o'chiradi. */
+    maxOffset?: number;
+}
+/** `@IsWithinMaxOffset()` ortidagi konstraint. Raqam bo'lmagan qiymatni `@IsInt()` rad etadi, bu yerda o'tadi. */
+declare class IsWithinMaxOffsetConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args?: ValidationArguments): boolean;
+    defaultMessage(args?: ValidationArguments): string;
+}
+/**
+ * Sahifa chuqurligini cheklaydi: `page` uchun `(page - 1) × perPage`, infinite `offset` uchun
+ * qiymatning o'zi `maxOffset`dan oshmasin. Chuqurroq sahifalar — cursor paginatsiya.
+ *
+ * @example
+ * ```ts
+ * class ListDto {
+ *   @IsOptional() @Type(() => Number) @IsInt() @IsPositive() @IsWithinMaxOffset({ mode: "page" })
+ *   page?: number;
+ * }
+ * ```
+ */
+declare function IsWithinMaxOffset(options: IsWithinMaxOffsetOptions, validationOptions?: ValidationOptions): PropertyDecorator;
 /**
  * Property'ni querykit `Filter` kontraktiga tekshiradi: flat massiv (implicit AND),
  * nested `and`/`or`/`not` daraxti va core `FILTER_OPERATORS`ning to'liq to'plami.
@@ -217,17 +220,31 @@ declare function IsQueryFilter(options?: IsQueryFilterOptions, validationOptions
  */
 declare function IsQuerySort(options?: IsQuerySortOptions, validationOptions?: ValidationOptions): PropertyDecorator;
 
-/** Paginatsiyasiz umumiy params — `filter` + `sort`. */
+/**
+ * Paginatsiyasiz umumiy params — `filter` + `sort`.
+ *
+ * @deprecated Use `makeOffsetParamsDto` / `makeInfiniteParamsDto` / `makeCursorParamsDto` (safe defaults). Removed in the next major.
+ */
 declare class BaseParamsDto {
     filter?: Filter;
     sort?: Sort;
 }
-/** Offset (sahifali) params — `page` + `perPage` (`perPage` ≤ core cap). */
+/**
+ * Offset (sahifali) params — `page` + `perPage` (`perPage` ≤ core cap).
+ *
+ * @deprecated Use `makeOffsetParamsDto` (safe defaults). Removed in the next major.
+ */
 declare class OffsetParamsDto extends BaseParamsDto {
     page?: number;
     perPage?: number;
+    /** `false` — no count; the meta totals are `null`. */
+    withTotal?: boolean;
 }
-/** Infinite-scroll params — `limit` + `offset`. */
+/**
+ * Infinite-scroll params — `limit` + `offset`.
+ *
+ * @deprecated Use `makeInfiniteParamsDto` (safe defaults). Removed in the next major.
+ */
 declare class InfiniteParamsDto extends BaseParamsDto {
     limit?: number;
     offset?: number;
@@ -236,6 +253,8 @@ declare class InfiniteParamsDto extends BaseParamsDto {
  * 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.
+ *
+ * @deprecated Use `makeCursorParamsDto` (safe defaults). Removed in the next major.
  */
 declare class CursorParamsDto {
     filter?: Filter;
@@ -245,6 +264,7 @@ declare class CursorParamsDto {
     order?: SortDirection;
     direction?: "forward" | "backward";
 }
+
 /** Server'ga tegishli, default'da clientdan qabul qilinmaydigan maydonlar. */
 type ServerOwnedField = "columns" | "with" | "withDeleted";
 /** `allow` bilan ochiladigan maydonlarning shakli. */
@@ -267,6 +287,12 @@ interface ParamsDtoOptions {
     maxPerPage?: number;
     /** `limit` yuqori chegarasi. Default — core `DEFAULT_MAX_LIMIT` (200). */
     maxLimit?: number;
+    /**
+     * So'rov limitlari; berilmaganlari core default'ida (`DEFAULT_QUERY_LIMITS`). Aniq
+     * berilgan `filter.maxDepth`, `sort.maxSortFields`, … bundan **ustun**.
+     * `Infinity` limitni o'chiradi (⚠️ DoS yuzasi).
+     */
+    limits?: Partial<QueryLimits>;
     /** Server-owned maydonlarni **ataylab** ochish. Default — bo'sh. */
     allow?: readonly ServerOwnedField[];
 }
@@ -290,6 +316,7 @@ declare function makeOffsetParamsDto(options?: ParamsDtoOptions): {
         sort?: Sort;
         page?: number;
         perPage?: number;
+        withTotal?: boolean;
         columns?: Record<string, boolean>;
         with?: Record<string, unknown>;
         withDeleted?: boolean;
@@ -322,4 +349,5 @@ declare function makeCursorParamsDto(options?: ParamsDtoOptions): {
     };
 };
 
-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 };
+export { BaseParamsDto, CursorParamsDto, InfiniteParamsDto, IsQueryFilter, IsQueryFilterConstraint, IsQuerySort, IsQuerySortConstraint, IsWithinMaxOffset, IsWithinMaxOffsetConstraint, OffsetParamsDto, QUERYKIT_LOCALES, QUERYKIT_MESSAGES_RU, QUERYKIT_MESSAGES_UZ, localizeIssue, makeCursorParamsDto, makeInfiniteParamsDto, makeOffsetParamsDto, validateFilter, validateSort };
+export type { IsQueryFilterOptions, IsQuerySortOptions, IsWithinMaxOffsetOptions, MessageStyleOptions, ParamsDtoOptions, QueryFilterOptions, QueryKitLocale, QuerySortOptions, ServerOwnedField, ServerOwnedParams, ValidationIssue };