@dudousxd/nestjs-filter 1.7.0 → 1.8.0

package/dist/input/spatie-parser.js

@@ -0,0 +1,159 @@
+/**
+ * Parses a spatie-laravel-query-builder / JSON:API-style query input into the
+ * library's internal {@link StructuredInput} model.
+ *
+ * This is an **opt-in** input format (enabled via the `inputFormat: 'spatie'`
+ * module option). The default `'native'` format is unchanged. The parser is a
+ * pure reshape — it does **not** enforce safety itself; its output flows through
+ * the same runner pipeline as native input, so the allowlist, per-field operator
+ * allowlist, and `throwOnInvalid` policy still apply.
+ *
+ * The input is the object produced after a query string has been decoded by
+ * Express + `qs` (bracket notation expanded into nested objects):
+ *
+ * | Query string                         | Decoded input                                   | Mapped to                                  |
+ * | ------------------------------------ | ----------------------------------------------- | ------------------------------------------ |
+ * | `filter[name]=Al`                    | `{ filter: { name: 'Al' } }`                    | `{ filter: { name: 'Al' } }` (equals)      |
+ * | `filter[id]=1,2,3`                   | `{ filter: { id: '1,2,3' } }`                   | `{ filter: { id: ['1','2','3'] } }` (in)   |
+ * | `filter[name][contains]=Al`          | `{ filter: { name: { contains: 'Al' } } }`     | operator object → existing operator path   |
+ * | `sort=-createdAt,name`               | `{ sort: '-createdAt,name' }`                   | `{ sort: '-createdAt,name' }`              |
+ * | `include=posts,comments`             | `{ include: 'posts,comments' }`                 | `{ include: 'posts,comments' }`            |
+ * | `fields[users]=id,name`              | `{ fields: { users: 'id,name' } }`             | `{ select: ['id','name'] }` (sparse)       |
+ * | `page[number]=2&page[size]=10`       | `{ page: { number: '2', size: '10' } }`        | `{ paginate: { page: 2, size: 10 } }`      |
+ * | `page[after]=cur&page[size]=10`      | `{ page: { after: 'cur', size: '10' } }`       | `{ paginate: { after, first } }` (cursor)  |
+ *
+ * Design notes:
+ * - **Filter values**: a bare scalar is interpreted by the adapter as `equals`;
+ *   a comma-separated scalar (spatie's convention for multi-value filters) is
+ *   split into an array (interpreted as `in`); an object whose keys are operators
+ *   passes straight through to the existing operator-object mechanism.
+ * - **Sparse fieldsets** (`fields[resource]`): JSON:API keys these by resource
+ *   type, but the runner applies a single SELECT to the primary entity, so the
+ *   per-resource lists are flattened (deduped, order-preserving) into one
+ *   `select` list and validated against the entity / allowlist downstream.
+ * - **Pagination**: JSON:API page-based (`page[number]`/`page[size]`) maps to
+ *   offset pagination; cursor-style (`page[after]`/`page[before]`) maps to the
+ *   library's keyset pagination input.
+ */
+export function parseSpatieInput(input) {
+    if (input == null || typeof input !== 'object')
+        return {};
+    const src = input;
+    const out = {};
+    if (src.filter != null && typeof src.filter === 'object' && !Array.isArray(src.filter)) {
+        out.filter = parseFilters(src.filter);
+    }
+    if (typeof src.sort === 'string') {
+        out.sort = src.sort;
+    }
+    else if (Array.isArray(src.sort)) {
+        // `sort[]=a&sort[]=-b` decodes to an array — join to the JSON:API string form.
+        out.sort = src.sort.filter((s) => typeof s === 'string').join(',');
+    }
+    if (typeof src.include === 'string') {
+        out.include = src.include;
+    }
+    else if (Array.isArray(src.include)) {
+        out.include = src.include.filter((s) => typeof s === 'string');
+    }
+    if (typeof src.search === 'string') {
+        out.search = src.search;
+    }
+    const select = parseSparseFieldsets(src.fields);
+    if (select.length > 0) {
+        out.select = select;
+    }
+    const paginate = parsePage(src.page);
+    if (paginate)
+        out.paginate = paginate;
+    return out;
+}
+/**
+ * Reshapes the `filter` map: scalar values become equals (with comma → array),
+ * operator objects pass through unchanged, and arrays are kept as-is.
+ */
+function parseFilters(filter) {
+    const out = {};
+    for (const [field, value] of Object.entries(filter)) {
+        if (Array.isArray(value)) {
+            out[field] = value;
+        }
+        else if (value != null && typeof value === 'object') {
+            // Operator object (`{ contains: 'x' }`) — passed straight through; the
+            // runner / adapter interprets and validates the operator keys.
+            out[field] = value;
+        }
+        else if (typeof value === 'string' && value.includes(',')) {
+            // spatie multi-value filter convention: comma-separated → array (IN).
+            out[field] = value
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+        }
+        else {
+            out[field] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Flattens JSON:API sparse fieldsets (`fields[resource]=a,b`) into a single
+ * order-preserving, de-duplicated list of column names. Per-resource keys are
+ * collapsed because the runner applies one SELECT to the primary entity; unknown
+ * columns are dropped downstream when validated against entity metadata.
+ */
+function parseSparseFieldsets(fields) {
+    if (fields == null || typeof fields !== 'object' || Array.isArray(fields))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const value of Object.values(fields)) {
+        const cols = typeof value === 'string'
+            ? value.split(',')
+            : Array.isArray(value)
+                ? value.filter((s) => typeof s === 'string')
+                : [];
+        for (const raw of cols) {
+            const col = raw.trim();
+            if (col.length > 0 && !seen.has(col)) {
+                seen.add(col);
+                out.push(col);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Maps a JSON:API `page` object to the library's pagination input.
+ * `page[number]`/`page[size]` → offset; `page[after]`/`page[before]` → cursor.
+ */
+function parsePage(page) {
+    if (page == null || typeof page !== 'object' || Array.isArray(page))
+        return undefined;
+    const p = page;
+    const after = typeof p.after === 'string' ? p.after : undefined;
+    const before = typeof p.before === 'string' ? p.before : undefined;
+    const size = toInt(p.size);
+    if (after !== undefined || before !== undefined) {
+        if (after !== undefined) {
+            return { after, ...(size !== undefined && { first: size }) };
+        }
+        return { before: before, ...(size !== undefined && { last: size }) };
+    }
+    const number = toInt(p.number);
+    if (number !== undefined || size !== undefined) {
+        return { page: number ?? 0, size: size ?? 25 };
+    }
+    return undefined;
+}
+function toInt(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const n = Number(value);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return undefined;
+}
+//# sourceMappingURL=spatie-parser.js.map

package/dist/input/spatie-parser.js.map

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

package/dist/pagination/cursor.d.ts

@@ -0,0 +1,37 @@
+import type { SortItem } from '../types.js';
+/**
+ * A decoded keyset cursor: the ordered values of the keyset columns (the active
+ * sort columns plus a stable primary-key tiebreaker) captured from a boundary
+ * row. The values line up positionally with the keyset's `SortItem[]`.
+ */
+export type CursorValues = unknown[];
+/**
+ * Encodes keyset cursor values into a compact, URL-safe opaque string
+ * (base64url of a JSON array). The shape is intentionally opaque to clients —
+ * only this module reads it back.
+ *
+ * `Date` values are encoded as `{ $d: <iso> }` so they round-trip to `Date`
+ * instances on decode (plain JSON would yield a string and break date keyset
+ * comparisons).
+ */
+export declare function encodeCursor(values: CursorValues): string;
+/**
+ * Decodes an opaque cursor string back into its keyset values. Returns `null`
+ * when the cursor is malformed (bad base64, bad JSON, or not an array) so the
+ * caller can ignore an invalid cursor instead of crashing.
+ */
+export declare function decodeCursor(cursor: string): CursorValues | null;
+/**
+ * Builds the keyset `SortItem[]` for cursor pagination: the caller's effective
+ * sorts, with a stable primary-key tiebreaker appended if it is not already
+ * present. The tiebreaker inherits the direction of the last sort column so the
+ * overall ordering stays monotonic (important for a correct `(cols, pk) > (...)`
+ * comparison).
+ */
+export declare function buildKeyset(sorts: SortItem[], primaryKey: string): SortItem[];
+/**
+ * Extracts the keyset values from a fetched row, in keyset column order.
+ * Supports dotted relation paths (e.g. `author.name`) by walking the object.
+ */
+export declare function extractCursorValues(row: Record<string, unknown>, keyset: SortItem[]): CursorValues;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/pagination/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/pagination/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,EAAE,CAAC;AAErC;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAOzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAahE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE,CAK7E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,QAAQ,EAAE,GACjB,YAAY,CAUd"}

package/dist/pagination/cursor.js

@@ -0,0 +1,69 @@
+/**
+ * Encodes keyset cursor values into a compact, URL-safe opaque string
+ * (base64url of a JSON array). The shape is intentionally opaque to clients —
+ * only this module reads it back.
+ *
+ * `Date` values are encoded as `{ $d: <iso> }` so they round-trip to `Date`
+ * instances on decode (plain JSON would yield a string and break date keyset
+ * comparisons).
+ */
+export function encodeCursor(values) {
+    // Pre-map Date values to a tagged form. We cannot detect dates in the
+    // JSON.stringify replacer because Date.toJSON() has already converted them to
+    // strings by the time the replacer sees the value.
+    const tagged = values.map((v) => (v instanceof Date ? { $d: v.toISOString() } : v));
+    const json = JSON.stringify(tagged);
+    return Buffer.from(json, 'utf8').toString('base64url');
+}
+/**
+ * Decodes an opaque cursor string back into its keyset values. Returns `null`
+ * when the cursor is malformed (bad base64, bad JSON, or not an array) so the
+ * caller can ignore an invalid cursor instead of crashing.
+ */
+export function decodeCursor(cursor) {
+    try {
+        const json = Buffer.from(cursor, 'base64url').toString('utf8');
+        const parsed = JSON.parse(json, (_key, value) => {
+            if (value && typeof value === 'object' && typeof value.$d === 'string') {
+                return new Date(value.$d);
+            }
+            return value;
+        });
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Builds the keyset `SortItem[]` for cursor pagination: the caller's effective
+ * sorts, with a stable primary-key tiebreaker appended if it is not already
+ * present. The tiebreaker inherits the direction of the last sort column so the
+ * overall ordering stays monotonic (important for a correct `(cols, pk) > (...)`
+ * comparison).
+ */
+export function buildKeyset(sorts, primaryKey) {
+    const hasPk = sorts.some((s) => s.field === primaryKey);
+    if (hasPk)
+        return sorts;
+    const lastDirection = sorts[sorts.length - 1]?.direction ?? 'asc';
+    return [...sorts, { field: primaryKey, direction: lastDirection }];
+}
+/**
+ * Extracts the keyset values from a fetched row, in keyset column order.
+ * Supports dotted relation paths (e.g. `author.name`) by walking the object.
+ */
+export function extractCursorValues(row, keyset) {
+    return keyset.map((s) => {
+        if (!s.field.includes('.'))
+            return row[s.field];
+        let current = row;
+        for (const segment of s.field.split('.')) {
+            if (current == null || typeof current !== 'object')
+                return undefined;
+            current = current[segment];
+        }
+        return current;
+    });
+}
+//# sourceMappingURL=cursor.js.map

package/dist/pagination/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/pagination/cursor.ts"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,sEAAsE;IACtE,8EAA8E;IAC9E,mDAAmD;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YAC9C,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;gBACvE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC5B,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB,EAAE,UAAkB;IAC/D,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC;IACxD,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,SAAS,IAAI,KAAK,CAAC;IAClE,OAAO,CAAC,GAAG,KAAK,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAA4B,EAC5B,MAAkB;IAElB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAChD,IAAI,OAAO,GAAY,GAAG,CAAC;QAC3B,KAAK,MAAM,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACzC,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;gBAAE,OAAO,SAAS,CAAC;YACrE,OAAO,GAAI,OAAmC,CAAC,OAAO,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/runner.d.ts

@@ -2,7 +2,7 @@ import { type Type } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 import type { FilterAdapter } from './adapter/adapter.js';
 import type { ContextAccessor } from './context-accessor.js';
-import type { EntityDescription, FilterContext, FilterModuleOptions, SortItem } from './types.js';
+import type { CursorPage, EntityDescription, FilterContext, FilterModuleOptions, SortItem } from './types.js';
 export declare class FilterRunner {
     private readonly moduleRef;
     private readonly options;
@@ -46,7 +46,9 @@ export declare class FilterRunner {
      * the `meta.fields` payload of generic, table-name-driven endpoints.
      */
     describe(entity: Type<unknown>): EntityDescription;
-    apply<F extends object, Q>(FilterClass: Type<F>, input: unknown, qb: Q, context?: FilterContext): Promise<Q>;
+    apply<F extends object, Q>(FilterClass: Type<F>, input: unknown, qb: Q, context?: FilterContext, internal?: {
+        native?: boolean;
+    }): Promise<Q>;
     private resolveFilter;
     private runSetup;
     /**
@@ -125,7 +127,10 @@ export declare class FilterRunner {
      * @param context - Optional filter context.
      * @returns The query builder with filters applied.
      */
-    applyDynamic<Q>(entity: Type<unknown>, input: unknown, qb: Q, context?: FilterContext): Promise<Q>;
+    applyDynamic<Q>(entity: Type<unknown>, input: unknown, qb: Q, context?: FilterContext, internal?: {
+        skipSortAndPagination?: boolean;
+        native?: boolean;
+    }): Promise<Q>;
     /**
      * Runs a dynamic query and **executes** it, returning the page of rows plus
      * the total count — with pagination-safe relation loading. Unlike
@@ -146,6 +151,31 @@ export declare class FilterRunner {
         rows: E[];
         total: number;
     }>;
+    /**
+     * Runs a dynamic query with **keyset (cursor) pagination** and executes it,
+     * returning a stable, non-overlapping page plus opaque forward/backward
+     * cursors. Unlike offset pagination (which drifts and re-scans as rows are
+     * inserted), keyset pagination seeks past a boundary row using a
+     * `WHERE (sortcols, pk) > (...)` predicate, so it is O(1) per page and stable
+     * under concurrent writes.
+     *
+     * The keyset is the request's effective sort (or `defaultSort`) plus the
+     * entity's primary key as a stable tiebreaker. Multi-column sort composes
+     * naturally. Direction is honored per column (asc → seek forward with `>`,
+     * desc → with `<`); for backward paging (`before`) the comparison and order
+     * are reversed internally and the result re-reversed so `items` is always in
+     * the requested order.
+     *
+     * Requires an adapter implementing `getResult`, `getPrimaryKey`,
+     * `applyKeysetPagination` and `applyKeysetOrderAndLimit`. Additive — does not
+     * change `apply`/`applyDynamic`/`findAndCount`.
+     */
+    findPage<E>(entity: Type<E>, input: unknown, opts?: {
+        qb?: unknown;
+        context?: FilterContext;
+    }): Promise<CursorPage<E>>;
+    /** Flips every keyset column's direction (for backward cursor paging). */
+    private reverseKeyset;
     /**
      * Splits include paths into join-safe (to-one) and deferred (to-many) sets,
      * by the cardinality of each path's first relation segment.
@@ -159,11 +189,47 @@ export declare class FilterRunner {
      * No-op (pass-through) when the adapter exposes no metadata.
      */
     private pruneUnknownColumnFilters;
+    /**
+     * Enforces per-field operator allowlists on a `where` ColumnFilter tree.
+     *
+     * For each clause whose `field` carries an operator restriction (declared as
+     * `{ field, operators }` in `@Filterable.allowed`), the clause's operator
+     * (after alias normalization) must be in the permitted set. A disallowed
+     * operator is dropped (default) or raises a `BadRequestException` when
+     * `throwOnInvalid` is set. Fields without a restriction (plain-string allowed
+     * entries, or no allowlist at all) pass through unchanged. Recurses AND/OR.
+     */
+    private enforceOperatorAllowlist;
+    /**
+     * Enforces a per-field operator allowlist on an auto-field value, mirroring
+     * the adapter's value-shape interpretation:
+     *
+     * - scalar → `equals`
+     * - array → `in`
+     * - operator object (`{ gte, lte }`) → each key is an operator
+     *
+     * Returns the value to apply, or `undefined` when the whole auto-field should
+     * be skipped (e.g. a scalar whose implied `equals` is not permitted, or an
+     * operator object reduced to no permitted keys). For operator objects, only
+     * the disallowed keys are stripped. When `throwOnInvalid` is set, a
+     * disallowed operator raises instead of being dropped.
+     */
+    private enforceAutoFieldOperators;
     /**
      * Applies global search for dynamic mode: auto-detects all string columns
      * from entity metadata (no filter class with static search config).
      */
     private applyGlobalSearchDynamic;
+    /**
+     * Resolves the effective `throwOnInvalid` policy: per-@Filterable wins over
+     * the module option, which defaults to `false` (silent-drop, legacy behavior).
+     */
+    private resolveThrowOnInvalid;
+    /**
+     * Resolves the effective `defaultSort`: per-@Filterable wins over the module
+     * option. Returns undefined when neither is set.
+     */
+    private resolveDefaultSort;
     private handleUnknownKey;
     /**
      * Parses raw sort input into an array of SortItem objects.
@@ -181,6 +247,15 @@ export declare class FilterRunner {
      * Silently skips invalid fields.
      */
     private validateSorts;
+    /**
+     * Applies a list of sorts, routing computed/virtual aliases to
+     * `applyComputedSort` (their dev-provided SQL expression) and regular columns
+     * to `applySort`. Order is preserved across the mix so the resulting
+     * `ORDER BY` matches the requested column order. Regular columns are still
+     * validated against the allowlist / entity metadata; computed aliases bypass
+     * that check because they are dev-declared, not real columns.
+     */
+    private applySortsWithComputed;
     /**
      * Parses raw distinct input into an array of field names.
      *

package/dist/runner.d.ts.map

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