@dudousxd/nestjs-filter 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @dudousxd/nestjs-filter
+
+## 1.0.0
+
+### Minor Changes
+
+- [`6b22e31`](https://github.com/DavideCarvalho/nestjs-filter/commit/6b22e3153f1f0b275bd579f6fade8facae61b8a7) - Initial release of nestjs-filter.
+
+  Structured input format with three top-level keys: filter, include, search.
+
+  Core features:
+
+  - Declarative filter classes with @FilterFor, @Filterable, @ApplyFilter
+  - Auto-fields with entity metadata introspection
+  - 22 built-in operators with AND/OR composition
+  - Dot-notation relation filtering (posts.title)
+  - Eager loading via ?include=role,posts
+  - Global search via ?search=term (ILIKE or tsvector)
+  - applyDynamic() for querying any entity without a filter class
+  - AsyncLocalStorage state isolation
+  - class-validator integration
+  - FilterTestingModule + makeMockQueryBuilder
+
+  Adapters: MikroORM 7, TypeORM 0.3+
+  Client: Zero-dependency fluent query builder
+
+## 1.0.0
+
+### Minor Changes
+
+- [`0cd738a`](https://github.com/DavideCarvalho/nestjs-filter/commit/0cd738a41105812bad6bee876d4c707bf815258f) - Initial release. Declarative ORM-agnostic filter classes for NestJS.
+
+  Core: BaseFilter, FilterRunner, @Filterable, @FilterFor, @ApplyFilter decorators, FilterModule, auto-fields with entity metadata introspection, dot-notation relation filtering, 22 built-in operators with AND/OR composition, bracket notation query string support, class-validator integration, FilterExceptionFilter, FilterTestingModule, makeMockQueryBuilder.
+
+  Adapters: MikroORM 7 and TypeORM with full operator support, entity metadata introspection, and relation filtering.
+
+  Client: Zero-dependency fluent query builder for browser and Node.js with type-safe operator validation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davi Carvalho
+
+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,108 @@
+# @dudousxd/nestjs-filter
+
+Core package for nestjs-filter -- declarative, ORM-agnostic filter classes for NestJS.
+
+Provides `BaseFilter`, `FilterRunner`, decorators (`@Filterable`, `@FilterFor`, `@ApplyFilter`), `FilterModule`, exception handling, and testing utilities.
+
+## Install
+
+```bash
+pnpm add @dudousxd/nestjs-filter
+```
+
+You also need an ORM adapter package:
+
+```bash
+# MikroORM
+pnpm add @dudousxd/nestjs-filter-mikro-orm
+
+# TypeORM
+pnpm add @dudousxd/nestjs-filter-typeorm
+```
+
+## Quick Start
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { Filterable, FilterFor, BaseFilter, FilterModule, ApplyFilter } from '@dudousxd/nestjs-filter';
+
+// 1. Define a filter
+@Injectable()
+@Filterable({ entity: User })
+class UserFilter extends BaseFilter<QueryBuilder> {
+  @FilterFor('name')
+  applyName(value: string) {
+    this.$query.andWhere({ name: value });
+  }
+}
+
+// 2. Register
+@Module({
+  imports: [
+    FilterModule.forRoot({ inputNormalizer: 'camelCase' }),
+    FilterModule.forFeature([UserFilter]),
+  ],
+})
+class AppModule {}
+
+// 3. Use in controller
+@Controller('users')
+class UsersController {
+  @Get()
+  list(@ApplyFilter(UserFilter) qb: QueryBuilder) {
+    return qb.getResultList();
+  }
+}
+```
+
+## API Reference
+
+### Decorators
+
+- **`@Filterable({ entity, allowed?, blocked? })`** -- Class decorator. Associates a filter with an entity. `allowed` whitelists keys; `blocked` blacklists them.
+- **`@FilterFor(inputKey?)`** -- Method decorator. Maps an input key to the method. Defaults to the method name if omitted.
+- **`@ApplyFilter(FilterClass, options?)`** -- Parameter decorator. Resolves input from the request, runs the filter, and injects the QueryBuilder. Options: `source` (`'auto'|'query'|'body'|Function`), `dto`, `resolve` (dynamic filter selection).
+
+### Classes
+
+- **`BaseFilter<TQuery>`** -- Abstract base class. Provides `$query`, `$input`, `$context`, `$adapter` via AsyncLocalStorage. Optional `setup()` hook.
+- **`FilterRunner`** -- Injectable service. `apply(FilterClass, input, qb, context?)` runs a filter programmatically.
+- **`FilterModule`** -- `forRoot(options?)` registers global infrastructure. `forFeature(filters)` registers filter classes.
+
+### Exceptions
+
+- `FilterException` -- Abstract base.
+- `FilterNotRegisteredException` -- Filter class not in DI container.
+- `FilterMissingEntityException` -- Missing `@Filterable({ entity })`.
+- `FilterStateUnavailableException` -- Accessing `$query` outside `FilterRunner.apply()`.
+- `UnknownFilterKeyException` -- Unknown key when `onUnknownKey: 'throw'`.
+- `FilterValidationException` -- class-validator validation failed.
+- `FilterMethodException` -- A filter method (or `setup()`) threw an error.
+
+### Exception Filter
+
+- **`FilterExceptionFilter`** -- Catches `FilterValidationException` and returns `{ statusCode: 400, message, errors }`.
+
+### Testing (from `@dudousxd/nestjs-filter/testing`)
+
+- **`FilterTestingModule`** -- `forRoot(options?)` and `forFeature(filters)`. Defaults to `validation: 'off'`.
+- **`makeMockQueryBuilder<E>()`** -- Proxy-based mock QB that records all calls. Access via `qb.calls`.
+
+### Types
+
+- **`FilterInput<F>`** -- Extracts the input shape from a filter class.
+- **`FilterContext`** -- `{ req?, user?, raw? }`.
+- **`FilterModuleOptions`** -- `{ inputNormalizer?, dropId?, onUnknownKey?, validation? }`.
+- **`ApplyFilterOptions`** -- `{ source?, dto?, resolve? }`.
+- **`InputSource`** -- `'auto' | 'query' | 'body' | ((req) => Record<string, unknown>)`.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `inputNormalizer` | `'camelCase' \| 'snakeCase' \| fn` | `'camelCase'` | Normalize input keys. |
+| `dropId` | `boolean` | `false` | Strip trailing `Id`/`_id`. |
+| `onUnknownKey` | `'ignore' \| 'warn' \| 'throw'` | `'ignore'` | Policy for unrecognized keys. |
+| `validation` | `'auto' \| 'off'` | `'auto'` | Validate with class-validator if installed. |
+
+See the [root README](../../README.md) for full documentation.

package/dist/adapter/adapter.d.ts

@@ -0,0 +1,158 @@
+import type { Type } from '@nestjs/common';
+import type { ColumnFilter } from '../operators/types.js';
+/**
+ * Describes a single scalar field on an entity, as reported by the ORM's
+ * metadata layer. Used by `autoFields: true` to validate that incoming
+ * filter keys correspond to real entity columns.
+ */
+export interface EntityFieldInfo {
+    /** Property name on the entity class (e.g. 'name', 'email', 'createdAt'). */
+    name: string;
+    /** Actual database column name (e.g. 'name', 'email', 'created_at'). */
+    columnName: string;
+    /** Simplified type classification for the column. */
+    type: 'string' | 'number' | 'boolean' | 'date' | 'json' | 'unknown';
+}
+/**
+ * Describes a relation on an entity, as reported by the ORM's metadata layer.
+ * Used by dot-notation relation filtering to auto-join and filter by related
+ * entity fields (e.g. `posts.title` joins `posts` and filters by `title`).
+ */
+export interface EntityRelationInfo {
+    /** Relation property name on the entity class (e.g. 'posts', 'author'). */
+    name: string;
+    /** Target entity name (e.g. 'Post', 'User'). */
+    targetEntity: string;
+    /** Relation cardinality type. */
+    type: 'one-to-one' | 'many-to-one' | 'one-to-many' | 'many-to-many';
+}
+export interface FilterAdapter {
+    createQueryBuilder<E>(entity: Type<E>): unknown;
+    /**
+     * Applies a constraint on a relation. The adapter joins (without selecting)
+     * the given relation and passes the query builder to the callback, which adds
+     * WHERE conditions for the related entity's fields.
+     *
+     * Implementations should use an inner join (not a left join with select) to
+     * avoid eagerly loading relation data and producing duplicate parent rows.
+     *
+     * Optional — adapters that don't support relation filtering should not implement this.
+     */
+    applyRelationConstraint?(qb: unknown, relationName: string, callback: (relationQb: unknown) => Promise<void>): Promise<void>;
+    /**
+     * Applies an array of generic ColumnFilter conditions to a query builder.
+     *
+     * Each adapter translates the operator-based filters into ORM-specific
+     * syntax (MikroORM FilterQuery objects, TypeORM andWhere/Brackets, etc.).
+     *
+     * Optional — adapters that don't support operator-based filtering should
+     * not implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param filters - Array of ColumnFilter conditions to apply.
+     */
+    applyColumnFilters?(qb: unknown, filters: ColumnFilter[]): void;
+    /**
+     * Applies an auto-field value to the query builder.
+     *
+     * Auto-fields are input keys that have no @FilterFor mapping but are
+     * explicitly declared in the filter class via `autoFields`.
+     *
+     * The adapter handles three value shapes:
+     * - Single value → `equals` (andWhere)
+     * - Array value → `in` ($in / IN)
+     * - Object with operator keys → apply those operators
+     *
+     * Optional — adapters that don't support auto-fields should not implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param field - The field/column name.
+     * @param value - The filter value (scalar, array, or operator object).
+     */
+    applyAutoField?(qb: unknown, field: string, value: unknown): void;
+    /**
+     * Introspects the ORM's metadata for the given entity class and returns
+     * an array of scalar (non-relation) field descriptors.
+     *
+     * Used by `autoFields: true` to restrict accepted input keys to actual
+     * entity columns, preventing unknown-column probing and SQL errors.
+     *
+     * Optional — when absent or when it returns `null`, `autoFields: true`
+     * falls back to accepting any key (legacy behavior) with a logged warning.
+     *
+     * @param entity - The entity class to introspect.
+     * @returns Array of field descriptors, or `null` if metadata is unavailable.
+     */
+    getEntityFields?(entity: Type<unknown>): EntityFieldInfo[] | null;
+    /**
+     * Introspects the ORM's metadata for the given entity class and returns
+     * an array of relation descriptors.
+     *
+     * Used by dot-notation relation filtering (`posts.title`) to discover
+     * which input key prefixes correspond to real entity relations.
+     *
+     * Optional — when absent or when it returns `null`, dot-notation
+     * relation filtering is disabled.
+     *
+     * @param entity - The entity class to introspect.
+     * @returns Array of relation descriptors, or `null` if metadata is unavailable.
+     */
+    getEntityRelations?(entity: Type<unknown>): EntityRelationInfo[] | null;
+    /**
+     * Applies a dot-notation relation field filter to the query builder.
+     *
+     * Auto-joins the relation (if not already joined) and applies a WHERE
+     * condition on the related entity's field.
+     *
+     * The value follows the same shapes as `applyAutoField`:
+     * - Single value → equals
+     * - Array value → IN
+     * - Object with operator keys → apply those operators
+     *
+     * Optional — adapters that don't support dot-notation relation filtering
+     * should not implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param relationName - The relation property name (e.g. 'posts').
+     * @param field - The field name on the related entity (e.g. 'title').
+     * @param value - The filter value (scalar, array, or operator object).
+     */
+    applyAutoRelationField?(qb: unknown, relationName: string, field: string, value: unknown): void;
+    /**
+     * Applies eager loading for the given relation paths.
+     *
+     * Each include path is a dot-separated relation name (e.g. 'posts', 'posts.comments').
+     * The adapter should left-join-and-select these relations on the query builder.
+     *
+     * Optional — adapters that don't support includes should not implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param includes - Array of relation paths to eagerly load.
+     * @param entity - The root entity class.
+     */
+    applyIncludes?(qb: unknown, includes: string[], entity: Type<unknown>): void;
+    /**
+     * Applies a global ILIKE search across the given columns.
+     *
+     * Generates an OR condition: `col1 ILIKE '%term%' OR col2 ILIKE '%term%' OR ...`
+     *
+     * Optional — adapters that don't support search should not implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param term - The search term (already trimmed).
+     * @param columns - Column names to search across.
+     * @param entity - The root entity class.
+     */
+    applySearch?(qb: unknown, term: string, columns: string[], entity: Type<unknown>): void;
+    /**
+     * Applies a full-text vector search using a tsvector column.
+     *
+     * Optional — adapters that don't support vector search should not implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param term - The search term.
+     * @param vectorColumn - The tsvector column name.
+     */
+    applyVectorSearch?(qb: unknown, term: string, vectorColumn: string): void;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACrE;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,IAAI,EAAE,YAAY,GAAG,aAAa,GAAG,aAAa,GAAG,cAAc,CAAC;CACrE;AAED,MAAM,WAAW,aAAa;IAC5B,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAEhD;;;;;;;;;OASG;IACH,uBAAuB,CAAC,CACtB,EAAE,EAAE,OAAO,EACX,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAEhE;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAElE;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE,GAAG,IAAI,CAAC;IAElE;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC;IAExE;;;;;;;;;;;;;;;;;;OAkBG;IACH,sBAAsB,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAEhG;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAE7E;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAExF;;;;;;;;OAQG;IACH,iBAAiB,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3E"}

package/dist/adapter/adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/adapter/adapter.ts"],"names":[],"mappings":""}

package/dist/als-store.d.ts

@@ -0,0 +1,15 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { FilterAdapter } from './adapter/adapter.js';
+import type { FilterContext } from './types.js';
+export interface FilterState {
+    $query: unknown;
+    $input: Readonly<Record<string, unknown>>;
+    $context: FilterContext;
+    $adapter: FilterAdapter | null;
+    $whitelisted: Set<string>;
+    $blacklisted: Set<string>;
+    $pushed: Array<[string, unknown]>;
+}
+export declare const filterAls: AsyncLocalStorage<FilterState>;
+export declare function runWithFilterState<T>(state: FilterState, fn: () => T): T;
+//# sourceMappingURL=als-store.d.ts.map

package/dist/als-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"als-store.d.ts","sourceRoot":"","sources":["../src/als-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnC;AAED,eAAO,MAAM,SAAS,gCAAuC,CAAC;AAE9D,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAExE"}

package/dist/als-store.js

@@ -0,0 +1,6 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const filterAls = new AsyncLocalStorage();
+export function runWithFilterState(state, fn) {
+    return filterAls.run(state, fn);
+}
+//# sourceMappingURL=als-store.js.map

package/dist/als-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"als-store.js","sourceRoot":"","sources":["../src/als-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAcrD,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,iBAAiB,EAAe,CAAC;AAE9D,MAAM,UAAU,kBAAkB,CAAI,KAAkB,EAAE,EAAW;IACnE,OAAO,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC"}

package/dist/base-filter.d.ts

@@ -0,0 +1,46 @@
+import type { FilterAdapter } from './adapter/adapter.js';
+import type { FilterContext } from './types.js';
+export declare abstract class BaseFilter<TQuery = unknown> {
+    get $query(): TQuery;
+    get $input(): Readonly<Record<string, unknown>>;
+    get $context(): FilterContext;
+    get $adapter(): FilterAdapter | null;
+    /**
+     * Dynamically whitelist a filter key at runtime (typically called in setup()).
+     * Whitelisted keys bypass static allowed/blocked checks in the dispatcher.
+     */
+    protected whitelistMethod(key: string): void;
+    /**
+     * Dynamically blacklist a filter key at runtime (typically called in setup()).
+     * Blacklisted keys are skipped during dispatch regardless of static configuration.
+     */
+    protected blacklistMethod(key: string): void;
+    /**
+     * Returns the full input object, a single input value by key,
+     * or a default value if the key is not present.
+     */
+    input(): Readonly<Record<string, unknown>>;
+    input(key: string): unknown;
+    input(key: string, defaultValue: unknown): unknown;
+    /**
+     * Injects additional key/value pairs into the filter input queue.
+     * Pushed entries are dispatched after the current dispatch loop completes.
+     */
+    protected push(key: string, value: unknown): void;
+    protected push(input: Record<string, unknown>): void;
+    /**
+     * Imperatively constrain a relation. Delegates to the adapter's
+     * `applyRelationConstraint` with the given conditions applied via callback.
+     *
+     * @param relationName - The relation property name on the entity (e.g. 'posts').
+     * @param conditions - A record of column/value pairs to match on the related entity.
+     *
+     * @example
+     * ```ts
+     * await this.related('posts', { status: 'published' });
+     * ```
+     */
+    protected related(relationName: string, conditions: Record<string, unknown>): Promise<void>;
+    setup?(): void | Promise<void>;
+}
+//# sourceMappingURL=base-filter.d.ts.map

package/dist/base-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-filter.d.ts","sourceRoot":"","sources":["../src/base-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,8BAAsB,UAAU,CAAC,MAAM,GAAG,OAAO;IAC/C,IAAI,MAAM,IAAI,MAAM,CAInB;IAED,IAAI,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAI9C;IAED,IAAI,QAAQ,IAAI,aAAa,CAI5B;IAED,IAAI,QAAQ,IAAI,aAAa,GAAG,IAAI,CAInC;IAED;;;OAGG;IACH,SAAS,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM5C;;;OAGG;IACH,SAAS,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM5C;;;OAGG;IACH,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO;IAOlD;;;OAGG;IACH,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IACjD,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAapD;;;;;;;;;;;OAWG;cACa,OAAO,CACrB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,IAAI,CAAC;IAsBhB,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAC/B"}

package/dist/base-filter.js

@@ -0,0 +1,95 @@
+import { filterAls } from './als-store.js';
+import { FilterStateUnavailableException } from './errors/exceptions.js';
+export class BaseFilter {
+    get $query() {
+        const s = filterAls.getStore();
+        if (!s)
+            throw new FilterStateUnavailableException();
+        return s.$query;
+    }
+    get $input() {
+        const s = filterAls.getStore();
+        if (!s)
+            throw new FilterStateUnavailableException();
+        return s.$input;
+    }
+    get $context() {
+        const s = filterAls.getStore();
+        if (!s)
+            throw new FilterStateUnavailableException();
+        return s.$context;
+    }
+    get $adapter() {
+        const s = filterAls.getStore();
+        if (!s)
+            throw new FilterStateUnavailableException();
+        return s.$adapter;
+    }
+    /**
+     * Dynamically whitelist a filter key at runtime (typically called in setup()).
+     * Whitelisted keys bypass static allowed/blocked checks in the dispatcher.
+     */
+    whitelistMethod(key) {
+        const s = filterAls.getStore();
+        if (!s)
+            throw new FilterStateUnavailableException();
+        s.$whitelisted.add(key);
+    }
+    /**
+     * Dynamically blacklist a filter key at runtime (typically called in setup()).
+     * Blacklisted keys are skipped during dispatch regardless of static configuration.
+     */
+    blacklistMethod(key) {
+        const s = filterAls.getStore();
+        if (!s)
+            throw new FilterStateUnavailableException();
+        s.$blacklisted.add(key);
+    }
+    input(key, defaultValue) {
+        const inp = this.$input;
+        if (key === undefined)
+            return inp;
+        return key in inp ? inp[key] : defaultValue;
+    }
+    push(keyOrInput, value) {
+        const state = filterAls.getStore();
+        if (!state)
+            throw new FilterStateUnavailableException();
+        if (typeof keyOrInput === 'string') {
+            state.$pushed.push([keyOrInput, value]);
+        }
+        else {
+            for (const [k, v] of Object.entries(keyOrInput)) {
+                state.$pushed.push([k, v]);
+            }
+        }
+    }
+    /**
+     * Imperatively constrain a relation. Delegates to the adapter's
+     * `applyRelationConstraint` with the given conditions applied via callback.
+     *
+     * @param relationName - The relation property name on the entity (e.g. 'posts').
+     * @param conditions - A record of column/value pairs to match on the related entity.
+     *
+     * @example
+     * ```ts
+     * await this.related('posts', { status: 'published' });
+     * ```
+     */
+    async related(relationName, conditions) {
+        const adapter = this.$adapter;
+        if (!adapter?.applyRelationConstraint) {
+            throw new Error(`Adapter does not support relation constraints. Use $query directly to filter relation "${relationName}".`);
+        }
+        await adapter.applyRelationConstraint(this.$query, relationName, async (relationQb) => {
+            // Apply each condition as an andWhere on the relation query builder.
+            // The exact shape depends on the adapter -- TypeORM and MikroORM both
+            // support object-based andWhere calls.
+            const qb = relationQb;
+            for (const [column, value] of Object.entries(conditions)) {
+                qb.andWhere({ [column]: value });
+            }
+        });
+    }
+}
+//# sourceMappingURL=base-filter.js.map

package/dist/base-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-filter.js","sourceRoot":"","sources":["../src/base-filter.ts"],"names":[],"mappings":"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"}

package/dist/cli/generate.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=generate.d.ts.map

package/dist/cli/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":""}

package/dist/cli/generate.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const args = process.argv.slice(2);
+const command = args[0];
+const name = args[1];
+const ormArg = args.find((a) => a.startsWith('--orm='));
+const orm = ormArg?.split('=')[1] ?? 'mikro-orm';
+if (!command || !name || !['generate', 'g'].includes(command)) {
+    console.log('Usage: npx nestjs-filter generate <name> [--orm=mikro-orm|typeorm]');
+    process.exit(1);
+}
+const pascal = name.charAt(0).toUpperCase() + name.slice(1);
+const filterImport = orm === 'typeorm'
+    ? "import { TypeOrmFilter } from '@dudousxd/nestjs-filter-typeorm';"
+    : "import { MikroOrmFilter } from '@dudousxd/nestjs-filter-mikro-orm';";
+const baseClass = orm === 'typeorm' ? `TypeOrmFilter<${pascal}>` : `MikroOrmFilter<${pascal}>`;
+const template = `import { Injectable } from '@nestjs/common';
+import { Filterable, FilterFor } from '@dudousxd/nestjs-filter';
+${filterImport}
+import { ${pascal} } from './${name}.entity.js';
+
+@Injectable()
+@Filterable({ entity: ${pascal} })
+export class ${pascal}Filter extends ${baseClass} {
+  // @FilterFor('fieldName')
+  // applyField(value: string) {
+  //   this.$query.andWhere({ field: value });
+  // }
+}
+`;
+const outDir = join(process.cwd(), 'src');
+const outPath = join(outDir, `${name}.filter.ts`);
+if (existsSync(outPath)) {
+    console.error(`File already exists: ${outPath}`);
+    process.exit(1);
+}
+if (!existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true });
+}
+writeFileSync(outPath, template);
+console.log(`Created ${outPath}`);
+//# sourceMappingURL=generate.js.map

package/dist/cli/generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AACxB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AACrB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;AACxD,MAAM,GAAG,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC;AAEjD,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;IAClF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC5D,MAAM,YAAY,GAChB,GAAG,KAAK,SAAS;IACf,CAAC,CAAC,kEAAkE;IACpE,CAAC,CAAC,qEAAqE,CAAC;AAC5E,MAAM,SAAS,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,iBAAiB,MAAM,GAAG,CAAC,CAAC,CAAC,kBAAkB,MAAM,GAAG,CAAC;AAE/F,MAAM,QAAQ,GAAG;;EAEf,YAAY;WACH,MAAM,cAAc,IAAI;;;wBAGX,MAAM;eACf,MAAM,kBAAkB,SAAS;;;;;;CAM/C,CAAC;AAEF,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;AAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,YAAY,CAAC,CAAC;AAElD,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IACxB,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;IACxB,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACjC,OAAO,CAAC,GAAG,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC"}

package/dist/decorator/apply-filter.decorator.d.ts

@@ -0,0 +1,11 @@
+import 'reflect-metadata';
+import { type Type } from '@nestjs/common';
+import type { ApplyFilterOptions } from '../types.js';
+export interface ApplyFilterMetadataEntry {
+    filterClass: Type<unknown>;
+    options: ApplyFilterOptions;
+    paramIndex: number;
+}
+export declare function ApplyFilter(filterClass: Type<unknown>, options?: ApplyFilterOptions): ParameterDecorator;
+export declare function getApplyFilterMetadata(controllerCtor: Function, methodName: string | symbol): ApplyFilterMetadataEntry[];
+//# sourceMappingURL=apply-filter.decorator.d.ts.map

package/dist/decorator/apply-filter.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-filter.decorator.d.ts","sourceRoot":"","sources":["../../src/decorator/apply-filter.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAyB,KAAK,IAAI,EAAwB,MAAM,gBAAgB,CAAC;AAExF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,WAAW,CACzB,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,EAC1B,OAAO,GAAE,kBAAuB,GAC/B,kBAAkB,CAsBpB;AAED,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,QAAQ,EACxB,UAAU,EAAE,MAAM,GAAG,MAAM,GAC1B,wBAAwB,EAAE,CAG5B"}

package/dist/decorator/apply-filter.decorator.js

@@ -0,0 +1,22 @@
+import 'reflect-metadata';
+import { createParamDecorator } from '@nestjs/common';
+import { APPLY_FILTER_METADATA, APPLY_FILTER_REQ_KEY } from '../tokens.js';
+export function ApplyFilter(filterClass, options = {}) {
+    return (target, propertyKey, parameterIndex) => {
+        const existing = (Reflect.getOwnMetadata(APPLY_FILTER_METADATA, target.constructor, propertyKey) ?? []);
+        existing.push({ filterClass, options, paramIndex: parameterIndex });
+        Reflect.defineMetadata(APPLY_FILTER_METADATA, existing, target.constructor, propertyKey);
+        return createParamDecorator((_data, ctx) => {
+            const req = ctx.switchToHttp().getRequest();
+            const slot = req[APPLY_FILTER_REQ_KEY];
+            if (!slot)
+                return undefined;
+            return slot[parameterIndex];
+        })()(target, propertyKey, parameterIndex);
+    };
+}
+export function getApplyFilterMetadata(controllerCtor, methodName) {
+    return (Reflect.getOwnMetadata(APPLY_FILTER_METADATA, controllerCtor, methodName) ??
+        []);
+}
+//# sourceMappingURL=apply-filter.decorator.js.map

package/dist/decorator/apply-filter.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-filter.decorator.js","sourceRoot":"","sources":["../../src/decorator/apply-filter.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAoC,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAS3E,MAAM,UAAU,WAAW,CACzB,WAA0B,EAC1B,UAA8B,EAAE;IAEhC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;QAC7C,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,cAAc,CACtC,qBAAqB,EACrB,MAAM,CAAC,WAAW,EAClB,WAAqB,CACtB,IAAI,EAAE,CAA+B,CAAC;QACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC,CAAC;QACpE,OAAO,CAAC,cAAc,CACpB,qBAAqB,EACrB,QAAQ,EACR,MAAM,CAAC,WAAW,EAClB,WAAqB,CACtB,CAAC;QAEF,OAAO,oBAAoB,CAAC,CAAC,KAAc,EAAE,GAAqB,EAAE,EAAE;YACpE,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC,UAAU,EAA6B,CAAC;YACvE,MAAM,IAAI,GAAG,GAAG,CAAC,oBAAoB,CAA0B,CAAC;YAChE,IAAI,CAAC,IAAI;gBAAE,OAAO,SAAS,CAAC;YAC5B,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC;QAC9B,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;IAC5C,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,cAAwB,EACxB,UAA2B;IAE3B,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,qBAAqB,EAAE,cAAc,EAAE,UAAoB,CAAC;QACzF,EAAE,CAA+B,CAAC;AACtC,CAAC"}

package/dist/decorator/filter-for.decorator.d.ts

@@ -0,0 +1,4 @@
+import 'reflect-metadata';
+export declare function FilterFor(inputKey?: string): MethodDecorator;
+export declare function getFilterForMap(target: object): Map<string, string>;
+//# sourceMappingURL=filter-for.decorator.d.ts.map

package/dist/decorator/filter-for.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-for.decorator.d.ts","sourceRoot":"","sources":["../../src/decorator/filter-for.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B,wBAAgB,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,CAU5D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAenE"}