nestjs-paginate-client 0.0.1

package/LICENSE.md

@@ -0,0 +1,20 @@
+# MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# nestjs-paginate-client
+
+[![CI](https://github.com/M0D1xD/nestjs-paginate-client/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/M0D1xD/nestjs-paginate-client/actions/workflows/ci.yaml)
+[![npm version](https://img.shields.io/npm/v/nestjs-paginate-client.svg)](https://www.npmjs.com/package/nestjs-paginate-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Type-safe query string builder for backends that use [nestjs-paginate](https://github.com/ppetzold/nestjs-paginate). Build `page`, `limit`, `sortBy`, `search`, `searchBy`, `select`, and `filter` query params with TypeScript types so column names match your frontend types.
+
+## Installation
+
+```bash
+npm install nestjs-paginate-client
+```
+
+## Compatibility
+
+Generated query strings match the format expected by nestjs-paginate:
+
+- **Pagination:** `page`, `limit`
+- **Sort:** `sortBy=column:ASC` or `sortBy=column:DESC` (multiple allowed)
+- **Search:** `search`, `searchBy` (array of column names)
+- **Select:** `select=col1,col2,...`
+- **Filter:** `filter.<column>=<token>` where token format is `[comparator]:[suffix]:[operator]:value`
+- **Cursor:** `cursor`, `withDeleted`
+
+### Filter operators
+
+| Operator              | Token       | Example / value       |
+| --------------------- | ----------- | --------------------- |
+| Equals                | `$eq`       | `$eq:John`            |
+| Not                   | `$not`      | prefix: `$not:$eq:x`  |
+| Greater than          | `$gt`       | `$gt:5`               |
+| Greater or equal      | `$gte`      | `$gte:3`              |
+| Less than             | `$lt`       | `$lt:10`              |
+| Less or equal         | `$lte`      | `$lte:7`              |
+| In list               | `$in`       | `$in:a,b,c`           |
+| Is null               | `$null`     | no value              |
+| Between               | `$btw`      | `$btw:1,10`           |
+| Case-insensitive like | `$ilike`    | `$ilike:term`         |
+| Starts with           | `$sw`       | `$sw:prefix`          |
+| Array contains        | `$contains` | `$contains:a,b`       |
+| OR                    | `$or`       | prefix: `$or:$eq:foo` |
+
+Nested/relation columns use dot notation: `offers.name`, `offers.price`.
+
+## Usage
+
+Define your types and use the builder with typed column paths:
+
+```ts
+import { createPaginateParams, eq, gte, in as filterIn } from 'nestjs-paginate-client';
+
+type Offer = { name: string; price: number };
+type User = { name: string; email: string; offers: Offer[] };
+
+const params = createPaginateParams<User>()
+  .page(1)
+  .limit(10)
+  .sortBy('name', 'ASC')
+  .sortBy('email', 'DESC')
+  .search('john')
+  .searchBy(['name', 'email'])
+  .filter('name', eq('John'))
+  .filter('offers.price', gte(100))
+  .filter('offers.name', filterIn(['A', 'B']));
+
+// Query string for URL
+const queryString = params.toQueryString();
+// e.g. ?page=1&limit=10&sortBy=name%3AASC&sortBy=email%3ADESC&search=john&...
+
+// Params object for axios/fetch
+const obj = params.toParams();
+// { page: '1', limit: '10', sortBy: ['name:ASC', 'email:DESC'], 'filter.name': '$eq:John', ... }
+```
+
+### Filter helpers
+
+- `eq(value)`, `gt(value)`, `gte(value)`, `lt(value)`, `lte(value)`
+- `inOp(values)` / `in(values)` — in list
+- `nullOp()` — is null
+- `btw(min, max)` — between
+- `ilike(value)`, `sw(value)` — string match
+- `contains(values)` — array contains
+- `not(token)` — negate (e.g. `not(eq('x'))` → `$not:$eq:x`)
+- `or(token)` — OR comparator (e.g. `or(eq('foo'))` → `$or:$eq:foo`)
+
+For full control use `buildFilterToken({ comparator, suffix, operator, value })` from the package.
+
+## API
+
+- **createPaginateParams&lt;T&gt;()** — returns a `PaginateQueryBuilder<T>`.
+- **PaginateQueryBuilder&lt;T&gt;** — fluent builder with:
+  - `.page(n)`, `.limit(n)`, `.sortBy(column, 'ASC'|'DESC')`, `.search(term)`, `.searchBy(columns)`, `.select(columns)`, `.filter(column, token)`, `.cursor(c)`, `.withDeleted(bool)`
+  - `.toParams()` — `Record<string, string | string[]>`
+  - `.toQueryString()` — `?key=value&...`
+- **ColumnPath&lt;T&gt;** — type of allowed column paths for `T` (including nested, e.g. `offers.price`).
+- **toQueryString(params)** — serialize a params object to a query string.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines and [DEVELOPMENT.md](.github/DEVELOPMENT.md) for local setup and scripts.
+
+Releases to npm are automated via [semantic-release](https://github.com/semantic-release/semantic-release) on the default branch. For token setup and release flow, see [docs/RELEASE_AND_TOKENS.md](docs/RELEASE_AND_TOKENS.md).
+
+## Credits
+
+This library was inspired by [nestjs-paginate](https://github.com/ppetzold/nestjs-paginate/tree/master) by [ppetzold](https://github.com/ppetzold). The query string format (pagination, sort, search, filter, etc.) is designed to work with backends using that package.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { Column, ColumnPath, FilterComparator, FilterOperator, FilterSuffix, PaginateParamsInput, PaginateParamsRaw, SortDirection } from "./lib/types.mjs";
+import { PaginateQueryBuilder, createPaginateParams } from "./lib/builder.mjs";
+import { FilterTokenOptions, btw, buildFilterToken, contains, eq, gt, gte, ilike, inOp, lt, lte, not, nullOp, or, sw } from "./lib/filter.mjs";
+import { toQueryString } from "./lib/query-string.mjs";
+export { type Column, type ColumnPath, FilterComparator, FilterOperator, FilterSuffix, type FilterTokenOptions, type PaginateParamsInput, type PaginateParamsRaw, PaginateQueryBuilder, type SortDirection, btw, buildFilterToken, contains, createPaginateParams, eq, gt, gte, ilike, inOp as in, inOp, lt, lte, not, nullOp, or, sw, toQueryString };

package/dist/index.mjs

@@ -0,0 +1,6 @@
+import { toQueryString } from "./lib/query-string.mjs";
+import { PaginateQueryBuilder, createPaginateParams } from "./lib/builder.mjs";
+import { FilterComparator, FilterOperator, FilterSuffix } from "./lib/types.mjs";
+import { btw, buildFilterToken, contains, eq, gt, gte, ilike, inOp, lt, lte, not, nullOp, or, sw } from "./lib/filter.mjs";
+
+export { FilterComparator, FilterOperator, FilterSuffix, PaginateQueryBuilder, btw, buildFilterToken, contains, createPaginateParams, eq, gt, gte, ilike, inOp as in, inOp, lt, lte, not, nullOp, or, sw, toQueryString };

package/dist/lib/builder.d.mts

@@ -0,0 +1,127 @@
+import { ColumnPath, PaginateParamsRaw, SortDirection } from "./types.mjs";
+
+//#region src/lib/builder.d.ts
+/**
+ * Fluent builder for nestjs-paginate query parameters.
+ * Use {@link createPaginateParams} to create an instance, then chain methods and call
+ * {@link PaginateQueryBuilder.toParams} or {@link PaginateQueryBuilder.toQueryString} to get the result.
+ *
+ * @typeParam T - The entity type (e.g. `User`). Column names are constrained to {@link ColumnPath}<T>.
+ */
+declare class PaginateQueryBuilder<T> {
+  private _page?;
+  private _limit?;
+  private _sortBy;
+  private _search?;
+  private _searchBy;
+  private _select;
+  private _filter;
+  private _cursor?;
+  private _withDeleted?;
+  /**
+   * Set the page number to retrieve.
+   * If invalid, the backend will apply its default (usually 1).
+   *
+   * @param n - Page number (1-based).
+   * @returns This builder for chaining.
+   */
+  page(n: number): this;
+  /**
+   * Set the number of records per page.
+   * Backend may cap this to its configured max limit.
+   *
+   * @param n - Items per page.
+   * @returns This builder for chaining.
+   */
+  limit(n: number): this;
+  /**
+   * Add a sort rule. Call multiple times to sort by several columns; order of calls defines sort priority.
+   *
+   * @param column - Column path to sort by (must be in {@link ColumnPath}<T>).
+   * @param direction - `'ASC'` or `'DESC'`.
+   * @returns This builder for chaining.
+   */
+  sortBy(column: ColumnPath<T>, direction: SortDirection): this;
+  /**
+   * Set the search term to filter results across searchable columns.
+   *
+   * @param term - Search string (e.g. user-typed query).
+   * @returns This builder for chaining.
+   */
+  search(term: string): this;
+  /**
+   * Set which columns to search when using {@link PaginateQueryBuilder.search}.
+   * When not set, the backend uses all configured searchable columns.
+   *
+   * @param columns - Column paths to search in.
+   * @returns This builder for chaining.
+   */
+  searchBy(columns: ColumnPath<T>[]): this;
+  /**
+   * Set the list of fields to select (sparse fieldsets). When not set, the backend returns all fields.
+   *
+   * @param columns - Column paths to include in the response.
+   * @returns This builder for chaining.
+   */
+  select(columns: ColumnPath<T>[]): this;
+  /**
+   * Add a filter on a column. Use filter helpers (e.g. {@link eq}, {@link gte}, {@link inOp}) to build token strings.
+   * Call multiple times for the same column to add multiple conditions (e.g. OR filters).
+   *
+   * @param column - Column path to filter on (must be in {@link ColumnPath}<T>).
+   * @param token - Filter token string or array of tokens (e.g. `eq('John')`, `[or(eq('A')), or(eq('B'))]`).
+   * @returns This builder for chaining.
+   */
+  filter(column: ColumnPath<T>, token: string | string[]): this;
+  /**
+   * Set the cursor for cursor-based pagination (next/previous page).
+   * Use the value from the previous response (e.g. `meta.cursor` or `links.next` query string).
+   *
+   * @param c - Opaque cursor string from the backend.
+   * @returns This builder for chaining.
+   */
+  cursor(c: string): this;
+  /**
+   * Include soft-deleted records when the backend supports it.
+   *
+   * @param value - `true` to include deleted records.
+   * @returns This builder for chaining.
+   */
+  withDeleted(value: boolean): this;
+  /**
+   * Build a params object suitable for `URLSearchParams`, axios `params`, or fetch query string.
+   * Keys match nestjs-paginate: `page`, `limit`, `sortBy` (array), `search`, `searchBy`, `select`, `filter.<column>`, `cursor`, `withDeleted`.
+   *
+   * @returns Record of query parameter names to string or string[] values.
+   */
+  toParams(): PaginateParamsRaw;
+  /**
+   * Build a query string (e.g. `?page=1&limit=10&sortBy=name:ASC`) compatible with nestjs-paginate.
+   * Values are encoded with `encodeURIComponent`; repeated keys (sortBy, searchBy) are emitted as multiple key=value pairs.
+   *
+   * @returns Query string including leading `?`, or empty string if no params.
+   */
+  toQueryString(): string;
+}
+/**
+ * Create a new paginate query builder for entity type `T`.
+ * Column names in `sortBy`, `searchBy`, `select`, and `filter` will be type-checked against {@link ColumnPath}<T>.
+ *
+ * @typeParam T - The entity type (e.g. `User`, `Offer`).
+ * @returns A new {@link PaginateQueryBuilder} instance.
+ *
+ * @example
+ * ```ts
+ * type User = { name: string; email: string };
+ * const params = createPaginateParams<User>()
+ *   .page(1)
+ *   .limit(10)
+ *   .sortBy('name', 'ASC')
+ *   .filter('email', eq('a@b.com'))
+ *   .toQueryString();
+ * ```
+ */
+declare function createPaginateParams<T>(): PaginateQueryBuilder<T>;
+//#endregion
+export { PaginateQueryBuilder, createPaginateParams };
+//# sourceMappingURL=builder.d.mts.map

package/dist/lib/builder.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.mts","names":[],"sources":["../../src/lib/builder.ts"],"mappings":";;;;;AAUA;;;;;cAAa,oBAAA;EAAA,QACH,KAAA;EAAA,QACA,MAAA;EAAA,QACA,OAAA;EAAA,QACA,OAAA;EAAA,QACA,SAAA;EAAA,QACA,OAAA;EAAA,QACA,OAAA;EAAA,QACA,OAAA;EAAA,QACA,YAAA;EATwB;;;;;;;EAkBhC,IAAA,CAAK,CAAA;EAVG;;;;;;;EAsBR,KAAA,CAAM,CAAA;EAYoB;;;;;;;EAA1B,MAAA,CAAO,MAAA,EAAQ,UAAA,CAAW,CAAA,GAAI,SAAA,EAAW,aAAA;EAuBZ;;;;;;EAZ7B,MAAA,CAAO,IAAA;EAoCQ;;;;;;;EAxBf,QAAA,CAAS,OAAA,EAAS,UAAA,CAAW,CAAA;EAiE7B;;;;;AA2CF;EAjGE,MAAA,CAAO,OAAA,EAAS,UAAA,CAAW,CAAA;EAiGO;;;;;;;;EApFlC,MAAA,CAAO,MAAA,EAAQ,UAAA,CAAW,CAAA,GAAI,KAAA;;;;;;;;EAmB9B,MAAA,CAAO,CAAA;;;;;;;EAWP,WAAA,CAAY,KAAA;;;;;;;EAWZ,QAAA,CAAA,GAAY,iBAAA;;;;;;;EAoBZ,aAAA,CAAA;AAAA;;;;;;;;;;;;;;;;;;;iBAuBc,oBAAA,GAAA,CAAA,GAA2B,oBAAA,CAAqB,CAAA"}

package/dist/lib/builder.mjs

@@ -0,0 +1,171 @@
+import { toQueryString } from "./query-string.mjs";
+
+//#region src/lib/builder.ts
+/**
+* Fluent builder for nestjs-paginate query parameters.
+* Use {@link createPaginateParams} to create an instance, then chain methods and call
+* {@link PaginateQueryBuilder.toParams} or {@link PaginateQueryBuilder.toQueryString} to get the result.
+*
+* @typeParam T - The entity type (e.g. `User`). Column names are constrained to {@link ColumnPath}<T>.
+*/
+var PaginateQueryBuilder = class {
+	constructor() {
+		this._sortBy = [];
+		this._searchBy = [];
+		this._select = [];
+		this._filter = {};
+	}
+	/**
+	* Set the page number to retrieve.
+	* If invalid, the backend will apply its default (usually 1).
+	*
+	* @param n - Page number (1-based).
+	* @returns This builder for chaining.
+	*/
+	page(n) {
+		this._page = n;
+		return this;
+	}
+	/**
+	* Set the number of records per page.
+	* Backend may cap this to its configured max limit.
+	*
+	* @param n - Items per page.
+	* @returns This builder for chaining.
+	*/
+	limit(n) {
+		this._limit = n;
+		return this;
+	}
+	/**
+	* Add a sort rule. Call multiple times to sort by several columns; order of calls defines sort priority.
+	*
+	* @param column - Column path to sort by (must be in {@link ColumnPath}<T>).
+	* @param direction - `'ASC'` or `'DESC'`.
+	* @returns This builder for chaining.
+	*/
+	sortBy(column, direction) {
+		this._sortBy.push([column, direction]);
+		return this;
+	}
+	/**
+	* Set the search term to filter results across searchable columns.
+	*
+	* @param term - Search string (e.g. user-typed query).
+	* @returns This builder for chaining.
+	*/
+	search(term) {
+		this._search = term;
+		return this;
+	}
+	/**
+	* Set which columns to search when using {@link PaginateQueryBuilder.search}.
+	* When not set, the backend uses all configured searchable columns.
+	*
+	* @param columns - Column paths to search in.
+	* @returns This builder for chaining.
+	*/
+	searchBy(columns) {
+		this._searchBy = columns.slice();
+		return this;
+	}
+	/**
+	* Set the list of fields to select (sparse fieldsets). When not set, the backend returns all fields.
+	*
+	* @param columns - Column paths to include in the response.
+	* @returns This builder for chaining.
+	*/
+	select(columns) {
+		this._select = columns.slice();
+		return this;
+	}
+	/**
+	* Add a filter on a column. Use filter helpers (e.g. {@link eq}, {@link gte}, {@link inOp}) to build token strings.
+	* Call multiple times for the same column to add multiple conditions (e.g. OR filters).
+	*
+	* @param column - Column path to filter on (must be in {@link ColumnPath}<T>).
+	* @param token - Filter token string or array of tokens (e.g. `eq('John')`, `[or(eq('A')), or(eq('B'))]`).
+	* @returns This builder for chaining.
+	*/
+	filter(column, token) {
+		const key = column;
+		const existing = this._filter[key];
+		const next = Array.isArray(token) ? token : [token];
+		this._filter[key] = existing ? [...Array.isArray(existing) ? existing : [existing], ...next] : next.length === 1 ? next[0] : next;
+		return this;
+	}
+	/**
+	* Set the cursor for cursor-based pagination (next/previous page).
+	* Use the value from the previous response (e.g. `meta.cursor` or `links.next` query string).
+	*
+	* @param c - Opaque cursor string from the backend.
+	* @returns This builder for chaining.
+	*/
+	cursor(c) {
+		this._cursor = c;
+		return this;
+	}
+	/**
+	* Include soft-deleted records when the backend supports it.
+	*
+	* @param value - `true` to include deleted records.
+	* @returns This builder for chaining.
+	*/
+	withDeleted(value) {
+		this._withDeleted = value;
+		return this;
+	}
+	/**
+	* Build a params object suitable for `URLSearchParams`, axios `params`, or fetch query string.
+	* Keys match nestjs-paginate: `page`, `limit`, `sortBy` (array), `search`, `searchBy`, `select`, `filter.<column>`, `cursor`, `withDeleted`.
+	*
+	* @returns Record of query parameter names to string or string[] values.
+	*/
+	toParams() {
+		const raw = {};
+		if (this._page !== void 0) raw.page = String(this._page);
+		if (this._limit !== void 0) raw.limit = String(this._limit);
+		if (this._sortBy.length) raw.sortBy = this._sortBy.map(([col, dir]) => `${col}:${dir}`);
+		if (this._search !== void 0 && this._search !== "") raw.search = this._search;
+		if (this._searchBy.length) raw.searchBy = this._searchBy;
+		if (this._select.length) raw.select = this._select.join(",");
+		if (this._cursor !== void 0) raw.cursor = this._cursor;
+		if (this._withDeleted !== void 0) raw.withDeleted = String(this._withDeleted);
+		for (const [column, value] of Object.entries(this._filter)) raw[`filter.${column}`] = value;
+		return raw;
+	}
+	/**
+	* Build a query string (e.g. `?page=1&limit=10&sortBy=name:ASC`) compatible with nestjs-paginate.
+	* Values are encoded with `encodeURIComponent`; repeated keys (sortBy, searchBy) are emitted as multiple key=value pairs.
+	*
+	* @returns Query string including leading `?`, or empty string if no params.
+	*/
+	toQueryString() {
+		return toQueryString(this.toParams());
+	}
+};
+/**
+* Create a new paginate query builder for entity type `T`.
+* Column names in `sortBy`, `searchBy`, `select`, and `filter` will be type-checked against {@link ColumnPath}<T>.
+*
+* @typeParam T - The entity type (e.g. `User`, `Offer`).
+* @returns A new {@link PaginateQueryBuilder} instance.
+*
+* @example
+* ```ts
+* type User = { name: string; email: string };
+* const params = createPaginateParams<User>()
+*   .page(1)
+*   .limit(10)
+*   .sortBy('name', 'ASC')
+*   .filter('email', eq('a@b.com'))
+*   .toQueryString();
+* ```
+*/
+function createPaginateParams() {
+	return new PaginateQueryBuilder();
+}
+
+//#endregion
+export { PaginateQueryBuilder, createPaginateParams };
+//# sourceMappingURL=builder.mjs.map

package/dist/lib/builder.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.mjs","names":[],"sources":["../../src/lib/builder.ts"],"sourcesContent":["import type { ColumnPath, PaginateParamsRaw, SortDirection } from './types';\nimport { toQueryString } from './query-string';\n\n/**\n * Fluent builder for nestjs-paginate query parameters.\n * Use {@link createPaginateParams} to create an instance, then chain methods and call\n * {@link PaginateQueryBuilder.toParams} or {@link PaginateQueryBuilder.toQueryString} to get the result.\n *\n * @typeParam T - The entity type (e.g. `User`). Column names are constrained to {@link ColumnPath}<T>.\n */\nexport class PaginateQueryBuilder<T> {\n  private _page?: number;\n  private _limit?: number;\n  private _sortBy: [string, SortDirection][] = [];\n  private _search?: string;\n  private _searchBy: string[] = [];\n  private _select: string[] = [];\n  private _filter: Record<string, string | string[]> = {};\n  private _cursor?: string;\n  private _withDeleted?: boolean;\n\n  /**\n   * Set the page number to retrieve.\n   * If invalid, the backend will apply its default (usually 1).\n   *\n   * @param n - Page number (1-based).\n   * @returns This builder for chaining.\n   */\n  page(n: number): this {\n    this._page = n;\n    return this;\n  }\n\n  /**\n   * Set the number of records per page.\n   * Backend may cap this to its configured max limit.\n   *\n   * @param n - Items per page.\n   * @returns This builder for chaining.\n   */\n  limit(n: number): this {\n    this._limit = n;\n    return this;\n  }\n\n  /**\n   * Add a sort rule. Call multiple times to sort by several columns; order of calls defines sort priority.\n   *\n   * @param column - Column path to sort by (must be in {@link ColumnPath}<T>).\n   * @param direction - `'ASC'` or `'DESC'`.\n   * @returns This builder for chaining.\n   */\n  sortBy(column: ColumnPath<T>, direction: SortDirection): this {\n    this._sortBy.push([column, direction]);\n    return this;\n  }\n\n  /**\n   * Set the search term to filter results across searchable columns.\n   *\n   * @param term - Search string (e.g. user-typed query).\n   * @returns This builder for chaining.\n   */\n  search(term: string): this {\n    this._search = term;\n    return this;\n  }\n\n  /**\n   * Set which columns to search when using {@link PaginateQueryBuilder.search}.\n   * When not set, the backend uses all configured searchable columns.\n   *\n   * @param columns - Column paths to search in.\n   * @returns This builder for chaining.\n   */\n  searchBy(columns: ColumnPath<T>[]): this {\n    this._searchBy = columns.slice();\n    return this;\n  }\n\n  /**\n   * Set the list of fields to select (sparse fieldsets). When not set, the backend returns all fields.\n   *\n   * @param columns - Column paths to include in the response.\n   * @returns This builder for chaining.\n   */\n  select(columns: ColumnPath<T>[]): this {\n    this._select = columns.slice();\n    return this;\n  }\n\n  /**\n   * Add a filter on a column. Use filter helpers (e.g. {@link eq}, {@link gte}, {@link inOp}) to build token strings.\n   * Call multiple times for the same column to add multiple conditions (e.g. OR filters).\n   *\n   * @param column - Column path to filter on (must be in {@link ColumnPath}<T>).\n   * @param token - Filter token string or array of tokens (e.g. `eq('John')`, `[or(eq('A')), or(eq('B'))]`).\n   * @returns This builder for chaining.\n   */\n  filter(column: ColumnPath<T>, token: string | string[]): this {\n    const key = column as string;\n    const existing = this._filter[key];\n    const next = Array.isArray(token) ? token : [token];\n    this._filter[key] = existing\n      ? [...(Array.isArray(existing) ? existing : [existing]), ...next]\n      : next.length === 1\n        ? next[0]\n        : next;\n    return this;\n  }\n\n  /**\n   * Set the cursor for cursor-based pagination (next/previous page).\n   * Use the value from the previous response (e.g. `meta.cursor` or `links.next` query string).\n   *\n   * @param c - Opaque cursor string from the backend.\n   * @returns This builder for chaining.\n   */\n  cursor(c: string): this {\n    this._cursor = c;\n    return this;\n  }\n\n  /**\n   * Include soft-deleted records when the backend supports it.\n   *\n   * @param value - `true` to include deleted records.\n   * @returns This builder for chaining.\n   */\n  withDeleted(value: boolean): this {\n    this._withDeleted = value;\n    return this;\n  }\n\n  /**\n   * Build a params object suitable for `URLSearchParams`, axios `params`, or fetch query string.\n   * Keys match nestjs-paginate: `page`, `limit`, `sortBy` (array), `search`, `searchBy`, `select`, `filter.<column>`, `cursor`, `withDeleted`.\n   *\n   * @returns Record of query parameter names to string or string[] values.\n   */\n  toParams(): PaginateParamsRaw {\n    const raw: PaginateParamsRaw = {};\n    if (this._page !== undefined) raw.page = String(this._page);\n    if (this._limit !== undefined) raw.limit = String(this._limit);\n    if (this._sortBy.length) raw.sortBy = this._sortBy.map(([col, dir]) => `${col}:${dir}`);\n    if (this._search !== undefined && this._search !== '') raw.search = this._search;\n    if (this._searchBy.length) raw.searchBy = this._searchBy;\n    if (this._select.length) raw.select = this._select.join(',');\n    if (this._cursor !== undefined) raw.cursor = this._cursor;\n    if (this._withDeleted !== undefined) raw.withDeleted = String(this._withDeleted);\n    for (const [column, value] of Object.entries(this._filter)) raw[`filter.${column}`] = value;\n    return raw;\n  }\n\n  /**\n   * Build a query string (e.g. `?page=1&limit=10&sortBy=name:ASC`) compatible with nestjs-paginate.\n   * Values are encoded with `encodeURIComponent`; repeated keys (sortBy, searchBy) are emitted as multiple key=value pairs.\n   *\n   * @returns Query string including leading `?`, or empty string if no params.\n   */\n  toQueryString(): string {\n    return toQueryString(this.toParams());\n  }\n}\n\n/**\n * Create a new paginate query builder for entity type `T`.\n * Column names in `sortBy`, `searchBy`, `select`, and `filter` will be type-checked against {@link ColumnPath}<T>.\n *\n * @typeParam T - The entity type (e.g. `User`, `Offer`).\n * @returns A new {@link PaginateQueryBuilder} instance.\n *\n * @example\n * ```ts\n * type User = { name: string; email: string };\n * const params = createPaginateParams<User>()\n *   .page(1)\n *   .limit(10)\n *   .sortBy('name', 'ASC')\n *   .filter('email', eq('a@b.com'))\n *   .toQueryString();\n * ```\n */\nexport function createPaginateParams<T>(): PaginateQueryBuilder<T> {\n  return new PaginateQueryBuilder<T>();\n}\n"],"mappings":";;;;;;;;;;AAUA,IAAa,uBAAb,MAAqC;;iBAGU,EAAE;mBAEjB,EAAE;iBACJ,EAAE;iBACuB,EAAE;;;;;;;;;CAWvD,KAAK,GAAiB;AACpB,OAAK,QAAQ;AACb,SAAO;;;;;;;;;CAUT,MAAM,GAAiB;AACrB,OAAK,SAAS;AACd,SAAO;;;;;;;;;CAUT,OAAO,QAAuB,WAAgC;AAC5D,OAAK,QAAQ,KAAK,CAAC,QAAQ,UAAU,CAAC;AACtC,SAAO;;;;;;;;CAST,OAAO,MAAoB;AACzB,OAAK,UAAU;AACf,SAAO;;;;;;;;;CAUT,SAAS,SAAgC;AACvC,OAAK,YAAY,QAAQ,OAAO;AAChC,SAAO;;;;;;;;CAST,OAAO,SAAgC;AACrC,OAAK,UAAU,QAAQ,OAAO;AAC9B,SAAO;;;;;;;;;;CAWT,OAAO,QAAuB,OAAgC;EAC5D,MAAM,MAAM;EACZ,MAAM,WAAW,KAAK,QAAQ;EAC9B,MAAM,OAAO,MAAM,QAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM;AACnD,OAAK,QAAQ,OAAO,WAChB,CAAC,GAAI,MAAM,QAAQ,SAAS,GAAG,WAAW,CAAC,SAAS,EAAG,GAAG,KAAK,GAC/D,KAAK,WAAW,IACd,KAAK,KACL;AACN,SAAO;;;;;;;;;CAUT,OAAO,GAAiB;AACtB,OAAK,UAAU;AACf,SAAO;;;;;;;;CAST,YAAY,OAAsB;AAChC,OAAK,eAAe;AACpB,SAAO;;;;;;;;CAST,WAA8B;EAC5B,MAAM,MAAyB,EAAE;AACjC,MAAI,KAAK,UAAU,OAAW,KAAI,OAAO,OAAO,KAAK,MAAM;AAC3D,MAAI,KAAK,WAAW,OAAW,KAAI,QAAQ,OAAO,KAAK,OAAO;AAC9D,MAAI,KAAK,QAAQ,OAAQ,KAAI,SAAS,KAAK,QAAQ,KAAK,CAAC,KAAK,SAAS,GAAG,IAAI,GAAG,MAAM;AACvF,MAAI,KAAK,YAAY,UAAa,KAAK,YAAY,GAAI,KAAI,SAAS,KAAK;AACzE,MAAI,KAAK,UAAU,OAAQ,KAAI,WAAW,KAAK;AAC/C,MAAI,KAAK,QAAQ,OAAQ,KAAI,SAAS,KAAK,QAAQ,KAAK,IAAI;AAC5D,MAAI,KAAK,YAAY,OAAW,KAAI,SAAS,KAAK;AAClD,MAAI,KAAK,iBAAiB,OAAW,KAAI,cAAc,OAAO,KAAK,aAAa;AAChF,OAAK,MAAM,CAAC,QAAQ,UAAU,OAAO,QAAQ,KAAK,QAAQ,CAAE,KAAI,UAAU,YAAY;AACtF,SAAO;;;;;;;;CAST,gBAAwB;AACtB,SAAO,cAAc,KAAK,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;AAsBzC,SAAgB,uBAAmD;AACjE,QAAO,IAAI,sBAAyB"}

package/dist/lib/filter.d.mts

@@ -0,0 +1,123 @@
+import { FilterComparator, FilterOperator, FilterSuffix } from "./types.mjs";
+
+//#region src/lib/filter.d.ts
+/**
+ * Options for building a single filter token string.
+ * Used by `buildFilterToken` to produce nestjs-paginate–compatible filter values.
+ */
+interface FilterTokenOptions {
+  /** Logical grouping: `$and` (default) or `$or`. Omitted when `$and`. */
+  comparator?: FilterComparator;
+  /** Negate the condition, e.g. `$not`. */
+  suffix?: FilterSuffix;
+  /** The filter operator (e.g. `$eq`, `$gte`, `$in`). */
+  operator: FilterOperator;
+  /** Value for the operator. Omit for `$null`; use `[min, max]` for `$btw`; comma-separated string or array for `$in`/`$contains`. */
+  value?: string | number | [number, number];
+}
+/**
+ * Builds a single filter token string compatible with nestjs-paginate.
+ *
+ * Token format: `[comparator]:[suffix]:[operator]:value`
+ * - `$null` has no value.
+ * - `$in` and `$contains` use a comma-separated value.
+ * - `$btw` uses a two-element array `[min, max]`.
+ *
+ * @param options - Token options (comparator, suffix, operator, value).
+ * @returns The filter token string (e.g. `$eq:5`, `$gte:3`, `$or:$eq:foo`).
+ */
+declare function buildFilterToken(options: FilterTokenOptions): string;
+/**
+ * Equals. Produces a token like `$eq:value`.
+ *
+ * @param value - The value to match (string or number).
+ * @returns Filter token string.
+ */
+declare function eq(value: string | number): string;
+/**
+ * Greater than. Produces a token like `$gt:value`.
+ *
+ * @param value - The numeric lower bound (exclusive).
+ * @returns Filter token string.
+ */
+declare function gt(value: number): string;
+/**
+ * Greater than or equal. Produces a token like `$gte:value`.
+ *
+ * @param value - The numeric lower bound (inclusive).
+ * @returns Filter token string.
+ */
+declare function gte(value: number): string;
+/**
+ * Less than. Produces a token like `$lt:value`.
+ *
+ * @param value - The numeric upper bound (exclusive).
+ * @returns Filter token string.
+ */
+declare function lt(value: number): string;
+/**
+ * Less than or equal. Produces a token like `$lte:value`.
+ *
+ * @param value - The numeric upper bound (inclusive).
+ * @returns Filter token string.
+ */
+declare function lte(value: number): string;
+/**
+ * In list. Produces a token like `$in:a,b,c` for “column value is one of these”.
+ *
+ * @param values - Array of allowed values (strings or numbers).
+ * @returns Filter token string.
+ */
+declare function inOp(values: (string | number)[]): string;
+/**
+ * Is null. Produces the token `$null` (no value).
+ *
+ * @returns Filter token string.
+ */
+declare function nullOp(): string;
+/**
+ * Between (inclusive). Produces a token like `$btw:min,max`.
+ *
+ * @param min - Lower bound (inclusive).
+ * @param max - Upper bound (inclusive).
+ * @returns Filter token string.
+ */
+declare function btw(min: number, max: number): string;
+/**
+ * Case-insensitive like. Produces a token like `$ilike:value` (backend typically wraps in `%` for substring match).
+ *
+ * @param value - The string to match.
+ * @returns Filter token string.
+ */
+declare function ilike(value: string): string;
+/**
+ * Starts with. Produces a token like `$sw:value` (backend typically appends `%`).
+ *
+ * @param value - The prefix string.
+ * @returns Filter token string.
+ */
+declare function sw(value: string): string;
+/**
+ * Array contains. Produces a token like `$contains:a,b` for array columns.
+ *
+ * @param values - Values that must be contained in the array.
+ * @returns Filter token string.
+ */
+declare function contains(values: (string | number)[]): string;
+/**
+ * Negate a filter token. Prepends `$not:` to the given token (e.g. `not(eq('x'))` → `$not:$eq:x`).
+ *
+ * @param token - A filter token string from another helper (e.g. `eq('x')`, `nullOp()`).
+ * @returns Filter token string.
+ */
+declare function not(token: string): string;
+/**
+ * OR comparator. Prepends `$or:` to the given token so the condition is combined with OR (e.g. `or(eq('foo'))` → `$or:$eq:foo`).
+ *
+ * @param token - A filter token string.
+ * @returns Filter token string.
+ */
+declare function or(token: string): string;
+//#endregion
+export { FilterTokenOptions, btw, buildFilterToken, contains, eq, gt, gte, ilike, inOp, lt, lte, not, nullOp, or, sw };
+//# sourceMappingURL=filter.d.mts.map

package/dist/lib/filter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.mts","names":[],"sources":["../../src/lib/filter.ts"],"mappings":";;;;;AAMA;;UAAiB,kBAAA;EAEF;EAAb,UAAA,GAAa,gBAAA;EAIH;EAFV,MAAA,GAAS,YAAA;EAEe;EAAxB,QAAA,EAAU,cAAA;EAJG;EAMb,KAAA;AAAA;;;;;;AAgBF;;;;;AAyBA;iBAzBgB,gBAAA,CAAiB,OAAA,EAAS,kBAAA;;;;AAmC1C;;;iBAVgB,EAAA,CAAG,KAAA;;AAoBnB;;;;;iBAVgB,EAAA,CAAG,KAAA;;;;;AA8BnB;;iBApBgB,GAAA,CAAI,KAAA;;;AA8BpB;;;;iBApBgB,EAAA,CAAG,KAAA;AAgCnB;;;;;AAWA;AAXA,iBAtBgB,GAAA,CAAI,KAAA;;;;AA2CpB;;;iBAjCgB,IAAA,CAAK,MAAA;;AA2CrB;;;;iBA/BgB,MAAA,CAAA;AAyChB;;;;;AAaA;;AAbA,iBA9BgB,GAAA,CAAI,GAAA,UAAa,GAAA;;;AAqDjC;;;;iBA3CgB,KAAA,CAAM,KAAA;;;;;;;iBAUN,EAAA,CAAG,KAAA;;;;;;;iBAUH,QAAA,CAAS,MAAA;;;;;;;iBAaT,GAAA,CAAI,KAAA;;;;;;;iBAUJ,EAAA,CAAG,KAAA"}

package/dist/lib/filter.mjs

@@ -0,0 +1,180 @@
+import { FilterComparator, FilterOperator, FilterSuffix } from "./types.mjs";
+
+//#region src/lib/filter.ts
+const SEP = ":";
+/**
+* Builds a single filter token string compatible with nestjs-paginate.
+*
+* Token format: `[comparator]:[suffix]:[operator]:value`
+* - `$null` has no value.
+* - `$in` and `$contains` use a comma-separated value.
+* - `$btw` uses a two-element array `[min, max]`.
+*
+* @param options - Token options (comparator, suffix, operator, value).
+* @returns The filter token string (e.g. `$eq:5`, `$gte:3`, `$or:$eq:foo`).
+*/
+function buildFilterToken(options) {
+	const { comparator, suffix, operator, value } = options;
+	const parts = [];
+	if (comparator && comparator !== FilterComparator.AND) parts.push(comparator);
+	if (suffix) parts.push(suffix);
+	parts.push(operator);
+	if (operator === FilterOperator.NULL) return parts.join(SEP);
+	let valueStr;
+	if (Array.isArray(value)) valueStr = value.map(String).join(",");
+	else if (value !== void 0 && value !== null) valueStr = String(value);
+	else return parts.join(SEP);
+	parts.push(valueStr);
+	return parts.join(SEP);
+}
+/**
+* Equals. Produces a token like `$eq:value`.
+*
+* @param value - The value to match (string or number).
+* @returns Filter token string.
+*/
+function eq(value) {
+	return buildFilterToken({
+		operator: FilterOperator.EQ,
+		value
+	});
+}
+/**
+* Greater than. Produces a token like `$gt:value`.
+*
+* @param value - The numeric lower bound (exclusive).
+* @returns Filter token string.
+*/
+function gt(value) {
+	return buildFilterToken({
+		operator: FilterOperator.GT,
+		value
+	});
+}
+/**
+* Greater than or equal. Produces a token like `$gte:value`.
+*
+* @param value - The numeric lower bound (inclusive).
+* @returns Filter token string.
+*/
+function gte(value) {
+	return buildFilterToken({
+		operator: FilterOperator.GTE,
+		value
+	});
+}
+/**
+* Less than. Produces a token like `$lt:value`.
+*
+* @param value - The numeric upper bound (exclusive).
+* @returns Filter token string.
+*/
+function lt(value) {
+	return buildFilterToken({
+		operator: FilterOperator.LT,
+		value
+	});
+}
+/**
+* Less than or equal. Produces a token like `$lte:value`.
+*
+* @param value - The numeric upper bound (inclusive).
+* @returns Filter token string.
+*/
+function lte(value) {
+	return buildFilterToken({
+		operator: FilterOperator.LTE,
+		value
+	});
+}
+/**
+* In list. Produces a token like `$in:a,b,c` for “column value is one of these”.
+*
+* @param values - Array of allowed values (strings or numbers).
+* @returns Filter token string.
+*/
+function inOp(values) {
+	return buildFilterToken({
+		operator: FilterOperator.IN,
+		value: values.map(String).join(",")
+	});
+}
+/**
+* Is null. Produces the token `$null` (no value).
+*
+* @returns Filter token string.
+*/
+function nullOp() {
+	return buildFilterToken({ operator: FilterOperator.NULL });
+}
+/**
+* Between (inclusive). Produces a token like `$btw:min,max`.
+*
+* @param min - Lower bound (inclusive).
+* @param max - Upper bound (inclusive).
+* @returns Filter token string.
+*/
+function btw(min, max) {
+	return buildFilterToken({
+		operator: FilterOperator.BTW,
+		value: [min, max]
+	});
+}
+/**
+* Case-insensitive like. Produces a token like `$ilike:value` (backend typically wraps in `%` for substring match).
+*
+* @param value - The string to match.
+* @returns Filter token string.
+*/
+function ilike(value) {
+	return buildFilterToken({
+		operator: FilterOperator.ILIKE,
+		value
+	});
+}
+/**
+* Starts with. Produces a token like `$sw:value` (backend typically appends `%`).
+*
+* @param value - The prefix string.
+* @returns Filter token string.
+*/
+function sw(value) {
+	return buildFilterToken({
+		operator: FilterOperator.SW,
+		value
+	});
+}
+/**
+* Array contains. Produces a token like `$contains:a,b` for array columns.
+*
+* @param values - Values that must be contained in the array.
+* @returns Filter token string.
+*/
+function contains(values) {
+	return buildFilterToken({
+		operator: FilterOperator.CONTAINS,
+		value: values.map(String).join(",")
+	});
+}
+/**
+* Negate a filter token. Prepends `$not:` to the given token (e.g. `not(eq('x'))` → `$not:$eq:x`).
+*
+* @param token - A filter token string from another helper (e.g. `eq('x')`, `nullOp()`).
+* @returns Filter token string.
+*/
+function not(token) {
+	return `${FilterSuffix.NOT}${SEP}${token}`;
+}
+/**
+* OR comparator. Prepends `$or:` to the given token so the condition is combined with OR (e.g. `or(eq('foo'))` → `$or:$eq:foo`).
+*
+* @param token - A filter token string.
+* @returns Filter token string.
+*/
+function or(token) {
+	return `${FilterComparator.OR}${SEP}${token}`;
+}
+
+//#endregion
+export { btw, buildFilterToken, contains, eq, gt, gte, ilike, inOp, lt, lte, not, nullOp, or, sw };
+//# sourceMappingURL=filter.mjs.map

package/dist/lib/filter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.mjs","names":[],"sources":["../../src/lib/filter.ts"],"sourcesContent":["import { FilterComparator, FilterOperator, FilterSuffix } from './types';\n\n/**\n * Options for building a single filter token string.\n * Used by `buildFilterToken` to produce nestjs-paginate–compatible filter values.\n */\nexport interface FilterTokenOptions {\n  /** Logical grouping: `$and` (default) or `$or`. Omitted when `$and`. */\n  comparator?: FilterComparator;\n  /** Negate the condition, e.g. `$not`. */\n  suffix?: FilterSuffix;\n  /** The filter operator (e.g. `$eq`, `$gte`, `$in`). */\n  operator: FilterOperator;\n  /** Value for the operator. Omit for `$null`; use `[min, max]` for `$btw`; comma-separated string or array for `$in`/`$contains`. */\n  value?: string | number | [number, number];\n}\n\nconst SEP = ':';\n\n/**\n * Builds a single filter token string compatible with nestjs-paginate.\n *\n * Token format: `[comparator]:[suffix]:[operator]:value`\n * - `$null` has no value.\n * - `$in` and `$contains` use a comma-separated value.\n * - `$btw` uses a two-element array `[min, max]`.\n *\n * @param options - Token options (comparator, suffix, operator, value).\n * @returns The filter token string (e.g. `$eq:5`, `$gte:3`, `$or:$eq:foo`).\n */\nexport function buildFilterToken(options: FilterTokenOptions): string {\n  const { comparator, suffix, operator, value } = options;\n  const parts: string[] = [];\n\n  if (comparator && comparator !== FilterComparator.AND) parts.push(comparator);\n  if (suffix) parts.push(suffix);\n  parts.push(operator);\n\n  if (operator === FilterOperator.NULL) return parts.join(SEP);\n\n  let valueStr: string;\n  if (Array.isArray(value)) valueStr = value.map(String).join(',');\n  else if (value !== undefined && value !== null) valueStr = String(value);\n  else return parts.join(SEP);\n\n  parts.push(valueStr);\n  return parts.join(SEP);\n}\n\n/**\n * Equals. Produces a token like `$eq:value`.\n *\n * @param value - The value to match (string or number).\n * @returns Filter token string.\n */\nexport function eq(value: string | number): string {\n  return buildFilterToken({ operator: FilterOperator.EQ, value });\n}\n\n/**\n * Greater than. Produces a token like `$gt:value`.\n *\n * @param value - The numeric lower bound (exclusive).\n * @returns Filter token string.\n */\nexport function gt(value: number): string {\n  return buildFilterToken({ operator: FilterOperator.GT, value });\n}\n\n/**\n * Greater than or equal. Produces a token like `$gte:value`.\n *\n * @param value - The numeric lower bound (inclusive).\n * @returns Filter token string.\n */\nexport function gte(value: number): string {\n  return buildFilterToken({ operator: FilterOperator.GTE, value });\n}\n\n/**\n * Less than. Produces a token like `$lt:value`.\n *\n * @param value - The numeric upper bound (exclusive).\n * @returns Filter token string.\n */\nexport function lt(value: number): string {\n  return buildFilterToken({ operator: FilterOperator.LT, value });\n}\n\n/**\n * Less than or equal. Produces a token like `$lte:value`.\n *\n * @param value - The numeric upper bound (inclusive).\n * @returns Filter token string.\n */\nexport function lte(value: number): string {\n  return buildFilterToken({ operator: FilterOperator.LTE, value });\n}\n\n/**\n * In list. Produces a token like `$in:a,b,c` for “column value is one of these”.\n *\n * @param values - Array of allowed values (strings or numbers).\n * @returns Filter token string.\n */\nexport function inOp(values: (string | number)[]): string {\n  return buildFilterToken({\n    operator: FilterOperator.IN,\n    value: values.map(String).join(','),\n  });\n}\n\n/**\n * Is null. Produces the token `$null` (no value).\n *\n * @returns Filter token string.\n */\nexport function nullOp(): string {\n  return buildFilterToken({ operator: FilterOperator.NULL });\n}\n\n/**\n * Between (inclusive). Produces a token like `$btw:min,max`.\n *\n * @param min - Lower bound (inclusive).\n * @param max - Upper bound (inclusive).\n * @returns Filter token string.\n */\nexport function btw(min: number, max: number): string {\n  return buildFilterToken({ operator: FilterOperator.BTW, value: [min, max] });\n}\n\n/**\n * Case-insensitive like. Produces a token like `$ilike:value` (backend typically wraps in `%` for substring match).\n *\n * @param value - The string to match.\n * @returns Filter token string.\n */\nexport function ilike(value: string): string {\n  return buildFilterToken({ operator: FilterOperator.ILIKE, value });\n}\n\n/**\n * Starts with. Produces a token like `$sw:value` (backend typically appends `%`).\n *\n * @param value - The prefix string.\n * @returns Filter token string.\n */\nexport function sw(value: string): string {\n  return buildFilterToken({ operator: FilterOperator.SW, value });\n}\n\n/**\n * Array contains. Produces a token like `$contains:a,b` for array columns.\n *\n * @param values - Values that must be contained in the array.\n * @returns Filter token string.\n */\nexport function contains(values: (string | number)[]): string {\n  return buildFilterToken({\n    operator: FilterOperator.CONTAINS,\n    value: values.map(String).join(','),\n  });\n}\n\n/**\n * Negate a filter token. Prepends `$not:` to the given token (e.g. `not(eq('x'))` → `$not:$eq:x`).\n *\n * @param token - A filter token string from another helper (e.g. `eq('x')`, `nullOp()`).\n * @returns Filter token string.\n */\nexport function not(token: string): string {\n  return `${FilterSuffix.NOT}${SEP}${token}`;\n}\n\n/**\n * OR comparator. Prepends `$or:` to the given token so the condition is combined with OR (e.g. `or(eq('foo'))` → `$or:$eq:foo`).\n *\n * @param token - A filter token string.\n * @returns Filter token string.\n */\nexport function or(token: string): string {\n  return `${FilterComparator.OR}${SEP}${token}`;\n}\n\n/** Alias for `inOp` (use when `in` is not a reserved word in your context). */\nexport { inOp as in };\n"],"mappings":";;;AAiBA,MAAM,MAAM;;;;;;;;;;;;AAaZ,SAAgB,iBAAiB,SAAqC;CACpE,MAAM,EAAE,YAAY,QAAQ,UAAU,UAAU;CAChD,MAAM,QAAkB,EAAE;AAE1B,KAAI,cAAc,eAAe,iBAAiB,IAAK,OAAM,KAAK,WAAW;AAC7E,KAAI,OAAQ,OAAM,KAAK,OAAO;AAC9B,OAAM,KAAK,SAAS;AAEpB,KAAI,aAAa,eAAe,KAAM,QAAO,MAAM,KAAK,IAAI;CAE5D,IAAI;AACJ,KAAI,MAAM,QAAQ,MAAM,CAAE,YAAW,MAAM,IAAI,OAAO,CAAC,KAAK,IAAI;UACvD,UAAU,UAAa,UAAU,KAAM,YAAW,OAAO,MAAM;KACnE,QAAO,MAAM,KAAK,IAAI;AAE3B,OAAM,KAAK,SAAS;AACpB,QAAO,MAAM,KAAK,IAAI;;;;;;;;AASxB,SAAgB,GAAG,OAAgC;AACjD,QAAO,iBAAiB;EAAE,UAAU,eAAe;EAAI;EAAO,CAAC;;;;;;;;AASjE,SAAgB,GAAG,OAAuB;AACxC,QAAO,iBAAiB;EAAE,UAAU,eAAe;EAAI;EAAO,CAAC;;;;;;;;AASjE,SAAgB,IAAI,OAAuB;AACzC,QAAO,iBAAiB;EAAE,UAAU,eAAe;EAAK;EAAO,CAAC;;;;;;;;AASlE,SAAgB,GAAG,OAAuB;AACxC,QAAO,iBAAiB;EAAE,UAAU,eAAe;EAAI;EAAO,CAAC;;;;;;;;AASjE,SAAgB,IAAI,OAAuB;AACzC,QAAO,iBAAiB;EAAE,UAAU,eAAe;EAAK;EAAO,CAAC;;;;;;;;AASlE,SAAgB,KAAK,QAAqC;AACxD,QAAO,iBAAiB;EACtB,UAAU,eAAe;EACzB,OAAO,OAAO,IAAI,OAAO,CAAC,KAAK,IAAI;EACpC,CAAC;;;;;;;AAQJ,SAAgB,SAAiB;AAC/B,QAAO,iBAAiB,EAAE,UAAU,eAAe,MAAM,CAAC;;;;;;;;;AAU5D,SAAgB,IAAI,KAAa,KAAqB;AACpD,QAAO,iBAAiB;EAAE,UAAU,eAAe;EAAK,OAAO,CAAC,KAAK,IAAI;EAAE,CAAC;;;;;;;;AAS9E,SAAgB,MAAM,OAAuB;AAC3C,QAAO,iBAAiB;EAAE,UAAU,eAAe;EAAO;EAAO,CAAC;;;;;;;;AASpE,SAAgB,GAAG,OAAuB;AACxC,QAAO,iBAAiB;EAAE,UAAU,eAAe;EAAI;EAAO,CAAC;;;;;;;;AASjE,SAAgB,SAAS,QAAqC;AAC5D,QAAO,iBAAiB;EACtB,UAAU,eAAe;EACzB,OAAO,OAAO,IAAI,OAAO,CAAC,KAAK,IAAI;EACpC,CAAC;;;;;;;;AASJ,SAAgB,IAAI,OAAuB;AACzC,QAAO,GAAG,aAAa,MAAM,MAAM;;;;;;;;AASrC,SAAgB,GAAG,OAAuB;AACxC,QAAO,GAAG,iBAAiB,KAAK,MAAM"}

package/dist/lib/query-string.d.mts

@@ -0,0 +1,11 @@
+import { PaginateParamsRaw } from "./types.mjs";
+
+//#region src/lib/query-string.d.ts
+/**
+ * Serialize params to a query string compatible with nestjs-paginate.
+ * Repeated keys (e.g. sortBy, searchBy) are emitted as multiple key=value pairs.
+ */
+declare function toQueryString(params: PaginateParamsRaw): string;
+//#endregion
+export { toQueryString };
+//# sourceMappingURL=query-string.d.mts.map

package/dist/lib/query-string.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-string.d.mts","names":[],"sources":["../../src/lib/query-string.ts"],"mappings":";;;;;AAMA;;iBAAgB,aAAA,CAAc,MAAA,EAAQ,iBAAA"}

package/dist/lib/query-string.mjs

@@ -0,0 +1,19 @@
+//#region src/lib/query-string.ts
+/**
+* Serialize params to a query string compatible with nestjs-paginate.
+* Repeated keys (e.g. sortBy, searchBy) are emitted as multiple key=value pairs.
+*/
+function toQueryString(params) {
+	const pairs = [];
+	for (const [key, val] of Object.entries(params)) {
+		if (val === void 0 || val === null) continue;
+		if (Array.isArray(val)) {
+			for (const v of val) if (v !== void 0 && v !== null && v !== "") pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
+		} else if (val !== "") pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(val))}`);
+	}
+	return pairs.length ? `?${pairs.join("&")}` : "";
+}
+
+//#endregion
+export { toQueryString };
+//# sourceMappingURL=query-string.mjs.map

package/dist/lib/query-string.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-string.mjs","names":[],"sources":["../../src/lib/query-string.ts"],"sourcesContent":["import type { PaginateParamsRaw } from './types';\n\n/**\n * Serialize params to a query string compatible with nestjs-paginate.\n * Repeated keys (e.g. sortBy, searchBy) are emitted as multiple key=value pairs.\n */\nexport function toQueryString(params: PaginateParamsRaw): string {\n  const pairs: string[] = [];\n  for (const [key, val] of Object.entries(params)) {\n    if (val === undefined || val === null) continue;\n    if (Array.isArray(val)) {\n      for (const v of val) {\n        if (v !== undefined && v !== null && v !== '')\n          pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);\n      }\n    } else if (val !== '') {\n      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(val))}`);\n    }\n  }\n  return pairs.length ? `?${pairs.join('&')}` : '';\n}\n"],"mappings":";;;;;AAMA,SAAgB,cAAc,QAAmC;CAC/D,MAAM,QAAkB,EAAE;AAC1B,MAAK,MAAM,CAAC,KAAK,QAAQ,OAAO,QAAQ,OAAO,EAAE;AAC/C,MAAI,QAAQ,UAAa,QAAQ,KAAM;AACvC,MAAI,MAAM,QAAQ,IAAI,EACpB;QAAK,MAAM,KAAK,IACd,KAAI,MAAM,UAAa,MAAM,QAAQ,MAAM,GACzC,OAAM,KAAK,GAAG,mBAAmB,IAAI,CAAC,GAAG,mBAAmB,OAAO,EAAE,CAAC,GAAG;aAEpE,QAAQ,GACjB,OAAM,KAAK,GAAG,mBAAmB,IAAI,CAAC,GAAG,mBAAmB,OAAO,IAAI,CAAC,GAAG;;AAG/E,QAAO,MAAM,SAAS,IAAI,MAAM,KAAK,IAAI,KAAK"}

package/dist/lib/types.d.mts

@@ -0,0 +1,103 @@
+//#region src/lib/types.d.ts
+/**
+ * Filter operators compatible with nestjs-paginate backend.
+ */
+declare enum FilterOperator {
+  EQ = "$eq",
+  GT = "$gt",
+  GTE = "$gte",
+  IN = "$in",
+  NULL = "$null",
+  LT = "$lt",
+  LTE = "$lte",
+  BTW = "$btw",
+  ILIKE = "$ilike",
+  SW = "$sw",
+  CONTAINS = "$contains"
+}
+declare enum FilterSuffix {
+  NOT = "$not"
+}
+declare enum FilterComparator {
+  AND = "$and",
+  OR = "$or"
+}
+type SortDirection = 'ASC' | 'DESC';
+type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...0[]];
+type Join<K, P> = K extends string ? P extends string ? `${K}${'' extends P ? '' : '.'}${P}` : never : never;
+/**
+ * Column path for type T up to depth D.
+ * Primitives -> key; Arrays -> key + key.nestedPath; Objects -> key + key.nestedPath.
+ */
+type Column<T, D extends number = 2> = [D] extends [never] ? never : T extends Record<string, unknown> ? { [K in keyof T]-?: K extends string ? T[K] extends string | number | boolean | Date ? `${K}` : T[K] extends (infer U)[] ? `${K}` | Join<K, Column<U, Prev[D]>> : T[K] extends Record<string, unknown> ? `${K}` | Join<K, Column<T[K], Prev[D]>> : `${K}` : never }[keyof T] : '';
+type ColumnPath<T> = Column<T> extends infer C ? (C extends string ? C : never) : never;
+/**
+ * Params shape for serialization (query string / axios params).
+ * Keys: page, limit, sortBy[], search, searchBy[], select, filter.<column>, cursor, withDeleted.
+ */
+type PaginateParamsRaw = Record<string, string | string[]>;
+/**
+ * Input shape for building paginate params, aligned with nestjs-paginate query contract.
+ */
+interface PaginateParamsInput<T> {
+  /**
+   * Page number to retrieve.
+   * If you provide an invalid value, the default page number will be applied.
+   * @example 1
+   * @default 1 (when omitted, backend default applies)
+   */
+  page?: number;
+  /**
+   * Number of records per page.
+   * If the provided value is greater than the backend’s max limit, the max value will be applied.
+   * @example 20
+   * @default Backend config (e.g. 20)
+   */
+  limit?: number;
+  /**
+   * Sort by one or more columns and direction.
+   * To sort by multiple fields, provide multiple entries; the order in the array defines the sort order.
+   * Format: `[fieldName, 'ASC' | 'DESC']`.
+   * @example [['name', 'ASC'], ['createdAt', 'DESC']]
+   * @default Backend default sort (or unspecified order if none configured)
+   */
+  sortBy?: [ColumnPath<T>, SortDirection][] | [ColumnPath<T>, SortDirection];
+  /**
+   * Search term to filter result values across searchable columns.
+   * @example 'John'
+   */
+  search?: string;
+  /**
+   * List of fields to search by the search term.
+   * When omitted, the backend uses all configured searchable columns.
+   * @example ['name', 'email']
+   * @default All searchable fields (backend config)
+   */
+  searchBy?: ColumnPath<T>[];
+  /**
+   * List of fields to select (sparse fieldsets).
+   * When omitted, all fields are returned.
+   * @example ['id', 'name', 'email']
+   * @default All fields
+   */
+  select?: ColumnPath<T>[];
+  /**
+   * Filter by column. Each key is a column path; each value is a filter token string or array of tokens.
+   * Token format: optional `$not`, then operator (e.g. `$eq`, `$gte`, `$in`), then value. Use helpers from this package (e.g. `eq()`, `gte()`) to build tokens.
+   * Available operators: `$eq`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$null`, `$btw`, `$ilike`, `$sw`, `$contains`. Comparators: `$and`, `$or`.
+   * @example { name: eq('John'), age: gte(18) }
+   */
+  filter?: Partial<Record<ColumnPath<T>, string | string[]>>;
+  /**
+   * Cursor for cursor-based pagination.
+   * Opaque value returned by the backend in the previous page’s meta (e.g. `meta.cursor`); send it to get the next page.
+   */
+  cursor?: string;
+  /**
+   * When true, retrieve records including soft-deleted ones (if the backend supports soft delete).
+   */
+  withDeleted?: boolean;
+}
+//#endregion
+export { Column, ColumnPath, FilterComparator, FilterOperator, FilterSuffix, PaginateParamsInput, PaginateParamsRaw, SortDirection };
+//# sourceMappingURL=types.d.mts.map

package/dist/lib/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/lib/types.ts"],"mappings":";;AAGA;;aAAY,cAAA;EACV,EAAA;EACA,EAAA;EACA,GAAA;EACA,EAAA;EACA,IAAA;EACA,EAAA;EACA,GAAA;EACA,GAAA;EACA,KAAA;EACA,EAAA;EACA,QAAA;AAAA;AAAA,aAGU,YAAA;EACV,GAAA;AAAA;AAAA,aAGU,gBAAA;EACV,GAAA;EACA,EAAA;AAAA;AAAA,KAGU,aAAA;AAAA,KAEP,IAAA;AAAA,KAEA,IAAA,SAAa,CAAA,kBACd,CAAA,qBACK,CAAA,cAAe,CAAA,cAAe,CAAA;;;AANvC;;KAcY,MAAA,6BAAmC,CAAA,4BAE3C,CAAA,SAAU,MAAA,kCAEM,CAAA,KAAM,CAAA,kBACd,CAAA,CAAE,CAAA,sCAAuC,IAAA,MACpC,CAAA,KACH,CAAA,CAAE,CAAA,2BACG,CAAA,KAAM,IAAA,CAAK,CAAA,EAAG,MAAA,CAAO,CAAA,EAAG,IAAA,CAAK,CAAA,MAChC,CAAA,CAAE,CAAA,UAAW,MAAA,uBACR,CAAA,KAAM,IAAA,CAAK,CAAA,EAAG,MAAA,CAAO,CAAA,CAAE,CAAA,GAAI,IAAA,CAAK,CAAA,SAChC,CAAA,mBAEP,CAAA;AAAA,KAGF,UAAA,MAAgB,MAAA,CAAO,CAAA,qBAAsB,CAAA,kBAAmB,CAAA;;;;;KAMhE,iBAAA,GAAoB,MAAA;;;;UAKf,mBAAA;EAnCR;;;;;;EA0CP,IAAA;EA5CgB;;;;;;EAoDhB,KAAA;EA1CU;;;;;;;EAmDV,MAAA,IAAU,UAAA,CAAW,CAAA,GAAI,aAAA,OAAoB,UAAA,CAAW,CAAA,GAAI,aAAA;EA9ClD;;;;EAoDV,MAAA;EAlDc;;;;;;EA0Dd,QAAA,GAAW,UAAA,CAAW,CAAA;EAzDC;;;;;;EAiEvB,MAAA,GAAS,UAAA,CAAW,CAAA;EA/DsB;;;;;;EAuE1C,MAAA,GAAS,OAAA,CAAQ,MAAA,CAAO,UAAA,CAAW,CAAA;EApEtB;;;;EA0Eb,MAAA;EArFE;;;EA0FF,WAAA;AAAA"}

package/dist/lib/types.mjs

@@ -0,0 +1,31 @@
+//#region src/lib/types.ts
+/**
+* Filter operators compatible with nestjs-paginate backend.
+*/
+let FilterOperator = /* @__PURE__ */ function(FilterOperator) {
+	FilterOperator["EQ"] = "$eq";
+	FilterOperator["GT"] = "$gt";
+	FilterOperator["GTE"] = "$gte";
+	FilterOperator["IN"] = "$in";
+	FilterOperator["NULL"] = "$null";
+	FilterOperator["LT"] = "$lt";
+	FilterOperator["LTE"] = "$lte";
+	FilterOperator["BTW"] = "$btw";
+	FilterOperator["ILIKE"] = "$ilike";
+	FilterOperator["SW"] = "$sw";
+	FilterOperator["CONTAINS"] = "$contains";
+	return FilterOperator;
+}({});
+let FilterSuffix = /* @__PURE__ */ function(FilterSuffix) {
+	FilterSuffix["NOT"] = "$not";
+	return FilterSuffix;
+}({});
+let FilterComparator = /* @__PURE__ */ function(FilterComparator) {
+	FilterComparator["AND"] = "$and";
+	FilterComparator["OR"] = "$or";
+	return FilterComparator;
+}({});
+
+//#endregion
+export { FilterComparator, FilterOperator, FilterSuffix };
+//# sourceMappingURL=types.mjs.map

package/dist/lib/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../../src/lib/types.ts"],"sourcesContent":["/**\n * Filter operators compatible with nestjs-paginate backend.\n */\nexport enum FilterOperator {\n  EQ = '$eq',\n  GT = '$gt',\n  GTE = '$gte',\n  IN = '$in',\n  NULL = '$null',\n  LT = '$lt',\n  LTE = '$lte',\n  BTW = '$btw',\n  ILIKE = '$ilike',\n  SW = '$sw',\n  CONTAINS = '$contains',\n}\n\nexport enum FilterSuffix {\n  NOT = '$not',\n}\n\nexport enum FilterComparator {\n  AND = '$and',\n  OR = '$or',\n}\n\nexport type SortDirection = 'ASC' | 'DESC';\n\ntype Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...0[]];\n\ntype Join<K, P> = K extends string\n  ? P extends string\n    ? `${K}${'' extends P ? '' : '.'}${P}`\n    : never\n  : never;\n\n/**\n * Column path for type T up to depth D.\n * Primitives -> key; Arrays -> key + key.nestedPath; Objects -> key + key.nestedPath.\n */\nexport type Column<T, D extends number = 2> = [D] extends [never]\n  ? never\n  : T extends Record<string, unknown>\n    ? {\n        [K in keyof T]-?: K extends string\n          ? T[K] extends string | number | boolean | Date\n            ? `${K}`\n            : T[K] extends (infer U)[]\n              ? `${K}` | Join<K, Column<U, Prev[D]>>\n              : T[K] extends Record<string, unknown>\n                ? `${K}` | Join<K, Column<T[K], Prev[D]>>\n                : `${K}`\n          : never;\n      }[keyof T]\n    : '';\n\nexport type ColumnPath<T> = Column<T> extends infer C ? (C extends string ? C : never) : never;\n\n/**\n * Params shape for serialization (query string / axios params).\n * Keys: page, limit, sortBy[], search, searchBy[], select, filter.<column>, cursor, withDeleted.\n */\nexport type PaginateParamsRaw = Record<string, string | string[]>;\n\n/**\n * Input shape for building paginate params, aligned with nestjs-paginate query contract.\n */\nexport interface PaginateParamsInput<T> {\n  /**\n   * Page number to retrieve.\n   * If you provide an invalid value, the default page number will be applied.\n   * @example 1\n   * @default 1 (when omitted, backend default applies)\n   */\n  page?: number;\n\n  /**\n   * Number of records per page.\n   * If the provided value is greater than the backend’s max limit, the max value will be applied.\n   * @example 20\n   * @default Backend config (e.g. 20)\n   */\n  limit?: number;\n\n  /**\n   * Sort by one or more columns and direction.\n   * To sort by multiple fields, provide multiple entries; the order in the array defines the sort order.\n   * Format: `[fieldName, 'ASC' | 'DESC']`.\n   * @example [['name', 'ASC'], ['createdAt', 'DESC']]\n   * @default Backend default sort (or unspecified order if none configured)\n   */\n  sortBy?: [ColumnPath<T>, SortDirection][] | [ColumnPath<T>, SortDirection];\n\n  /**\n   * Search term to filter result values across searchable columns.\n   * @example 'John'\n   */\n  search?: string;\n\n  /**\n   * List of fields to search by the search term.\n   * When omitted, the backend uses all configured searchable columns.\n   * @example ['name', 'email']\n   * @default All searchable fields (backend config)\n   */\n  searchBy?: ColumnPath<T>[];\n\n  /**\n   * List of fields to select (sparse fieldsets).\n   * When omitted, all fields are returned.\n   * @example ['id', 'name', 'email']\n   * @default All fields\n   */\n  select?: ColumnPath<T>[];\n\n  /**\n   * Filter by column. Each key is a column path; each value is a filter token string or array of tokens.\n   * Token format: optional `$not`, then operator (e.g. `$eq`, `$gte`, `$in`), then value. Use helpers from this package (e.g. `eq()`, `gte()`) to build tokens.\n   * Available operators: `$eq`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$null`, `$btw`, `$ilike`, `$sw`, `$contains`. Comparators: `$and`, `$or`.\n   * @example { name: eq('John'), age: gte(18) }\n   */\n  filter?: Partial<Record<ColumnPath<T>, string | string[]>>;\n\n  /**\n   * Cursor for cursor-based pagination.\n   * Opaque value returned by the backend in the previous page’s meta (e.g. `meta.cursor`); send it to get the next page.\n   */\n  cursor?: string;\n\n  /**\n   * When true, retrieve records including soft-deleted ones (if the backend supports soft delete).\n   */\n  withDeleted?: boolean;\n}\n"],"mappings":";;;;AAGA,IAAY,0DAAL;AACL;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;;AAGF,IAAY,sDAAL;AACL;;;AAGF,IAAY,8DAAL;AACL;AACA"}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "nestjs-paginate-client",
+  "version": "0.0.1",
+  "description": "Type-safe query string builder for nestjs-paginate compatible backends. This package is a client-side library for the nestjs-paginate package.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/M0D1xD/nestjs-paginate-client.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Mohammed Zakout",
+    "email": "info@zakout.tech"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "commit": "cz",
+    "prepare": "husky",
+    "format": "prettier ./src --write",
+    "format:check": "prettier ./src --check",
+    "lint": "eslint ./src --max-warnings 0",
+    "tsc:check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release": "release-it"
+  },
+  "config": {
+    "commitizen": {
+      "path": "cz-conventional-changelog"
+    }
+  },
+  "lint-staged": {
+    "*": "prettier --ignore-unknown --write"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.6.1",
+    "@commitlint/config-conventional": "^19.6.0",
+    "@eslint/js": "^9.15.0",
+    "@release-it/conventional-changelog": "10.0.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "commitizen": "^4.3.1",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^9.16.0",
+    "globals": "^17.3.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.8.1",
+    "prettier-plugin-packagejson": "^3.0.0",
+    "release-it": "^19.2.4",
+    "semantic-release": "^25.0.3",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18"
+  },
+  "keywords": [
+    "@nestjs",
+    "nestjs-paginate",
+    "pagination",
+    "query-string",
+    "typescript"
+  ],
+  "packageManager": "pnpm@10.29.3",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}