@dudousxd/nestjs-filter 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @dudousxd/nestjs-filter
 
+## 1.8.0
+
+### Minor Changes
+
+- [#27](https://github.com/DavideCarvalho/nestjs-filter/pull/27) [`ab90005`](https://github.com/DavideCarvalho/nestjs-filter/commit/ab90005b46894bc560eee5047e9a0dca1e6495e2) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Ecosystem improvements across the filter core and both ORM adapters.
+
+  - **Full-text vector search fix**: switched Postgres full-text matching to `websearch_to_tsquery` for correct, user-friendly query parsing, with optional `ts_rank`-based relevance ordering.
+  - **`throwOnInvalid` policy**: opt-in strict mode that rejects unknown fields/operators/invalid input instead of silently dropping them.
+  - **`defaultSort`**: configure a fallback sort applied when no explicit sort is requested.
+  - **Deterministic query param names**: stable, predictable parameter naming in generated queries for easier debugging and caching.
+  - **Cursor / keyset pagination**: stable, non-overlapping cursor-based pagination for both the TypeORM and MikroORM adapters.
+  - **Per-field operator allowlist**: restrict which operators are permitted on a per-field basis.
+  - **Computed / virtual field filtering**: filter on computed/virtual fields that are not plain columns.
+  - **Opt-in spatie / JSON:API query syntax**: support for `filter[field][op]` bracket syntax and sparse fieldsets, enabled opt-in.
+  - **Cross-adapter contract suite + testcontainers**: a shared contract test suite run against both adapters, backed by Postgres and MySQL testcontainers for real-DB integration coverage.
+
 ## 1.7.1
 
 ### Patch Changes

package/dist/adapter/adapter.d.ts

@@ -27,6 +27,17 @@ export interface EntityRelationInfo {
     /** Relation cardinality type. */
     type: 'one-to-one' | 'many-to-one' | 'one-to-many' | 'many-to-many';
 }
+/**
+ * Behavior flags for full-text vector search ({@link FilterAdapter.applyVectorSearch}).
+ */
+export interface VectorSearchOptions {
+    /**
+     * When true, add relevance ordering for matched rows (e.g. Postgres
+     * `ORDER BY ts_rank(...) DESC`). Off by default because it changes the
+     * query's default ordering.
+     */
+    rank?: boolean;
+}
 export interface FilterAdapter {
     createQueryBuilder<E>(entity: Type<E>): unknown;
     /**
@@ -51,8 +62,11 @@ export interface FilterAdapter {
      *
      * @param qb - The query builder instance.
      * @param filters - Array of ColumnFilter conditions to apply.
+     * @param entity - The entity being queried. When provided, lets the adapter
+     *   resolve column types (e.g. so `isEmpty`/`isNotEmpty` only compare against
+     *   `''` on string columns — a DATE/number `col = ''` errors on MySQL).
      */
-    applyColumnFilters?(qb: unknown, filters: ColumnFilter[]): void;
+    applyColumnFilters?(qb: unknown, filters: ColumnFilter[], entity?: Type<unknown>): void;
     /**
      * Applies an auto-field value to the query builder.
      *
@@ -188,13 +202,21 @@ export interface FilterAdapter {
     /**
      * Applies a full-text vector search using a tsvector column.
      *
+     * Implementations must parse arbitrary user input safely (e.g. Postgres
+     * `websearch_to_tsquery`, not the raw `to_tsquery`, which throws a syntax
+     * error on ordinary multi-word input like `"foo bar"`).
+     *
+     * When `opts.rank` is true, the adapter may add relevance ordering
+     * (e.g. `ts_rank`) for the matched rows.
+     *
      * Optional — adapters that don't support vector search should not implement this.
      *
      * @param qb - The query builder instance.
-     * @param term - The search term.
+     * @param term - The search term (arbitrary user text).
      * @param vectorColumn - The tsvector column name.
+     * @param opts - Optional behavior flags (e.g. `{ rank: true }`).
      */
-    applyVectorSearch?(qb: unknown, term: string, vectorColumn: string): void;
+    applyVectorSearch?(qb: unknown, term: string, vectorColumn: string, opts?: VectorSearchOptions): void;
     /**
      * Restricts the query to DISTINCT values of the given field(s).
      *
@@ -211,6 +233,21 @@ export interface FilterAdapter {
      * @param entity - The root entity class.
      */
     applyDistinct?(qb: unknown, fields: string[], entity: Type<unknown>): void;
+    /**
+     * Restricts the query's projection to the given field(s) — JSON:API "sparse
+     * fieldsets". Unlike {@link applyDistinct}, this adds **no** `DISTINCT`
+     * modifier; it only narrows the SELECT list (the primary key should remain
+     * selected so rows stay addressable). Active WHERE / search / sort /
+     * pagination are unaffected.
+     *
+     * Optional — adapters that don't support projection narrowing should not
+     * implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param fields - Field/column names to select.
+     * @param entity - The root entity class.
+     */
+    applySelect?(qb: unknown, fields: string[], entity: Type<unknown>): void;
     /**
      * Applies sort ordering to the query builder.
      *
@@ -218,6 +255,33 @@ export interface FilterAdapter {
      * @param sorts - Array of SortItem directives (field + direction).
      */
     applySort?(qb: unknown, sorts: SortItem[]): void;
+    /**
+     * Applies a WHERE condition on a **computed/virtual field** — a developer-
+     * provided SQL expression declared via `@Filterable.computed`. Behaves like
+     * {@link applyAutoField} (scalar → equals, array → IN, operator object →
+     * those operators) but evaluates the raw `expression` instead of a column
+     * reference. The expression is dev-provided (never client input); values are
+     * always parameterized.
+     *
+     * Optional — adapters that don't support computed fields should not
+     * implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param expression - The raw SQL expression for the computed field.
+     * @param value - The filter value (scalar, array, or operator object).
+     */
+    applyComputedField?(qb: unknown, expression: string, value: unknown): void;
+    /**
+     * Applies an ORDER BY on a computed/virtual field's SQL expression.
+     *
+     * Optional — adapters that don't support computed fields should not
+     * implement this.
+     *
+     * @param qb - The query builder instance.
+     * @param expression - The raw SQL expression for the computed field.
+     * @param direction - Sort direction.
+     */
+    applyComputedSort?(qb: unknown, expression: string, direction: 'asc' | 'desc'): void;
     /**
      * Applies offset-based pagination to the query builder.
      *
@@ -239,6 +303,58 @@ export interface FilterAdapter {
         rows: unknown[];
         total: number;
     }>;
+    /**
+     * Executes the query builder and returns the matching rows (no count). Used
+     * by `FilterRunner.findPage` for cursor/keyset pagination, where a total
+     * count is intentionally not computed.
+     *
+     * Optional — required only if you call `findPage`.
+     *
+     * @param qb - The query builder instance.
+     * @returns The fetched rows.
+     */
+    getResult?(qb: unknown): Promise<unknown[]>;
+    /**
+     * Returns the primary-key property name of the entity, used as the stable
+     * tiebreaker for keyset/cursor pagination. Returns `null` when no single
+     * primary key can be determined.
+     *
+     * Optional — required only for `findPage` cursor pagination.
+     *
+     * @param entity - The entity class.
+     */
+    getPrimaryKey?(entity: Type<unknown>): string | null;
+    /**
+     * Applies a keyset (cursor) WHERE predicate to the query builder for
+     * row-value comparison across the keyset columns.
+     *
+     * Given a keyset (the active sort columns plus a primary-key tiebreaker, each
+     * with a direction) and the boundary row's column values, the adapter adds a
+     * predicate equivalent to a lexicographic tuple comparison that selects rows
+     * strictly *after* the boundary in keyset order. Columns sorted `asc` use
+     * `>` and `desc` use `<` at each tier; ties on a column fall through to the
+     * next. Implementations must parameterize all values.
+     *
+     * Optional — required only for `findPage` cursor pagination.
+     *
+     * @param qb - The query builder instance.
+     * @param keyset - The keyset columns with directions (sort cols + pk).
+     * @param values - The boundary row's values, positionally aligned to keyset.
+     */
+    applyKeysetPagination?(qb: unknown, keyset: SortItem[], values: unknown[]): void;
+    /**
+     * Applies an ORDER BY for the keyset columns and a row LIMIT — the ordering
+     * and slice for a cursor page. Separate from {@link applySort} so `findPage`
+     * controls the keyset ordering (including direction reversal for backward
+     * paging) independently of the request `sort`.
+     *
+     * Optional — required only for `findPage` cursor pagination.
+     *
+     * @param qb - The query builder instance.
+     * @param keyset - The keyset columns with directions.
+     * @param limit - Max rows to fetch.
+     */
+    applyKeysetOrderAndLimit?(qb: unknown, keyset: SortItem[], limit: number): void;
     /**
      * Loads the given relations onto already-fetched rows in a **separate query**
      * (not a join), so that pagination of the parent is unaffected. Used by

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

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

package/dist/decorator/allowed.d.ts

@@ -0,0 +1,30 @@
+import type { FilterOperator } from '../operators/types.js';
+import type { AllowedFieldEntry } from '../types.js';
+/**
+ * A normalized view of a `@Filterable` `allowed` list:
+ *
+ * - `fields` — the set of allowed field-name keys (regardless of operator
+ *   restrictions), suitable as the allowlist for sort/distinct/auto-field
+ *   membership checks.
+ * - `operatorsByField` — for entries that restricted operators, the set of
+ *   permitted operators per field. Fields declared as a plain string (allow
+ *   all operators) are **absent** from this map.
+ */
+export interface NormalizedAllowed {
+    fields: string[];
+    operatorsByField: Map<string, Set<FilterOperator>>;
+}
+/**
+ * Normalizes a `@Filterable` `allowed` list (which mixes plain field-name
+ * strings with `{ field, operators }` objects) into a {@link NormalizedAllowed}.
+ *
+ * Returns `undefined` when no allowlist was declared.
+ */
+export declare function normalizeAllowed(allowed: readonly AllowedFieldEntry[] | undefined): NormalizedAllowed | undefined;
+/**
+ * Returns the allowed field-name keys from a `@Filterable` `allowed` list,
+ * discarding any per-field operator restrictions. Used wherever the prior
+ * code expected a plain `string[]` allowlist (sort, distinct, auto-fields).
+ */
+export declare function allowedFieldNames(allowed: readonly AllowedFieldEntry[] | undefined): string[] | undefined;
+//# sourceMappingURL=allowed.d.ts.map

package/dist/decorator/allowed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowed.d.ts","sourceRoot":"","sources":["../../src/decorator/allowed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;CACpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,SAAS,GAChD,iBAAiB,GAAG,SAAS,CAa/B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,SAAS,GAChD,MAAM,EAAE,GAAG,SAAS,CAGtB"}

package/dist/decorator/allowed.js

@@ -0,0 +1,32 @@
+/**
+ * Normalizes a `@Filterable` `allowed` list (which mixes plain field-name
+ * strings with `{ field, operators }` objects) into a {@link NormalizedAllowed}.
+ *
+ * Returns `undefined` when no allowlist was declared.
+ */
+export function normalizeAllowed(allowed) {
+    if (!allowed)
+        return undefined;
+    const fields = [];
+    const operatorsByField = new Map();
+    for (const entry of allowed) {
+        if (typeof entry === 'string') {
+            fields.push(entry);
+            continue;
+        }
+        fields.push(entry.field);
+        operatorsByField.set(entry.field, new Set(entry.operators));
+    }
+    return { fields, operatorsByField };
+}
+/**
+ * Returns the allowed field-name keys from a `@Filterable` `allowed` list,
+ * discarding any per-field operator restrictions. Used wherever the prior
+ * code expected a plain `string[]` allowlist (sort, distinct, auto-fields).
+ */
+export function allowedFieldNames(allowed) {
+    if (!allowed)
+        return undefined;
+    return allowed.map((entry) => (typeof entry === 'string' ? entry : entry.field));
+}
+//# sourceMappingURL=allowed.js.map

package/dist/decorator/allowed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowed.js","sourceRoot":"","sources":["../../src/decorator/allowed.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAiD;IAEjD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA+B,CAAC;IAChE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzB,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAiD;IAEjD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACnF,CAAC"}

package/dist/decorator/filterable.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filterable.decorator.d.ts","sourceRoot":"","sources":["../../src/decorator/filterable.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErE,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAgBrE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEhF"}
+{"version":3,"file":"filterable.decorator.d.ts","sourceRoot":"","sources":["../../src/decorator/filterable.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErE,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAmBrE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEhF"}

package/dist/decorator/filterable.decorator.js

@@ -14,6 +14,9 @@ export function Filterable(options) {
             ...(options.allowed !== undefined && { allowed: options.allowed }),
             ...(options.blocked !== undefined && { blocked: options.blocked }),
             autoFields: options.autoFields ?? true,
+            ...(options.throwOnInvalid !== undefined && { throwOnInvalid: options.throwOnInvalid }),
+            ...(options.defaultSort !== undefined && { defaultSort: options.defaultSort }),
+            ...(options.computed !== undefined && { computed: options.computed }),
         };
         Reflect.defineMetadata(FILTERABLE_METADATA, meta, target);
     };

package/dist/decorator/filterable.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"filterable.decorator.js","sourceRoot":"","sources":["../../src/decorator/filterable.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGnD,MAAM,UAAU,UAAU,CAAC,OAA0B;IACnD,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,IAAI,4BAA4B,CAAC,MAAM,CAAC,IAAI,IAAI,iBAAiB,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,CAAC,IAAI,6CAA6C,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,IAAI,GAAmB;YAC3B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;SACvC,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,mBAAmB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,OAAO,OAAO,CAAC,WAAW,CAAC,mBAAmB,EAAE,MAAM,CAA+B,CAAC;AACxF,CAAC"}
+{"version":3,"file":"filterable.decorator.js","sourceRoot":"","sources":["../../src/decorator/filterable.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGnD,MAAM,UAAU,UAAU,CAAC,OAA0B;IACnD,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,IAAI,4BAA4B,CAAC,MAAM,CAAC,IAAI,IAAI,iBAAiB,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,CAAC,IAAI,6CAA6C,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,IAAI,GAAmB;YAC3B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;YACtC,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;YACvF,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;YAC9E,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;SACtE,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,mBAAmB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,OAAO,OAAO,CAAC,WAAW,CAAC,mBAAmB,EAAE,MAAM,CAA+B,CAAC;AACxF,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export declare const VERSION = "0.0.0";
 export { BaseFilter } from './base-filter.js';
-export type { FilterAdapter, EntityFieldInfo, EntityRelationInfo } from './adapter/adapter.js';
+export type { FilterAdapter, EntityFieldInfo, EntityRelationInfo, VectorSearchOptions, } from './adapter/adapter.js';
 export { Filterable, getFilterableMetadata } from './decorator/filterable.decorator.js';
+export { normalizeAllowed, allowedFieldNames } from './decorator/allowed.js';
+export type { NormalizedAllowed } from './decorator/allowed.js';
 export { FilterFor, getFilterForMap, getFilterForOptsMap, } from './decorator/filter-for.decorator.js';
 export type { FilterFieldTypeHint, FilterForOptions, } from './decorator/filter-for.decorator.js';
 export { ApplyFilter, getApplyFilterMetadata } from './decorator/apply-filter.decorator.js';
@@ -15,10 +17,13 @@ export { FilterRunner } from './runner.js';
 export { FilterModule } from './module.js';
 export { FilterException, FilterNotRegisteredException, FilterMissingEntityException, FilterStateUnavailableException, UnknownFilterKeyException, FilterValidationException, FilterMissingAdapterException, FilterMethodException, } from './errors/exceptions.js';
 export { FILTER_MODULE_OPTIONS, FILTER_ADAPTER, FILTERABLE_METADATA, FILTER_FOR_METADATA, FILTER_FOR_OPTS_METADATA, FILTER_RELATIONS_METADATA, APPLY_FILTER_METADATA, APPLY_FILTER_REQ_KEY, TENANT_SCOPED_METADATA, CONTEXT_ACCESSOR, } from './tokens.js';
-export type { ApplyFilterOptions, CursorPagination, EntityDescription, FieldMeta, FilterableOptions, FilterContext, FilterInput, FilterInputStrict, FilterInputLoose, FilterMetadata, FilterModuleOptions, FilterModuleOptionsFactory, FilterModuleAsyncOptions, InputNormalizer, InputSource, OffsetPagination, OnUnknownKey, RelationMeta, SortItem, StructuredInput, ValidationMode, } from './types.js';
+export type { AllowedFieldEntry, ApplyFilterOptions, CursorPage, CursorPagination, EntityDescription, FieldMeta, FilterableOptions, FilterContext, FilterInput, FilterInputStrict, FilterInputLoose, FilterMetadata, FilterModuleOptions, FilterModuleOptionsFactory, FilterModuleAsyncOptions, InputFormat, InputNormalizer, InputSource, OffsetPagination, OnUnknownKey, RelationMeta, SortItem, StructuredInput, ValidationMode, } from './types.js';
 export { resolveInputFromRequest } from './input/source-resolver.js';
 export { normalizeInput } from './input/normalizer.js';
+export { parseSpatieInput } from './input/spatie-parser.js';
 export { escapeLike } from './utils/escape-like.js';
+export { encodeCursor, decodeCursor, buildKeyset, extractCursorValues, } from './pagination/cursor.js';
+export type { CursorValues } from './pagination/cursor.js';
 export type { ColumnFilter, FilterOperator, FilterOperatorAlias, FilterOperatorInput, } from './operators/types.js';
 export { FILTER_OPERATORS, OPERATOR_ALIASES } from './operators/types.js';
 export { ColumnFilterDto } from './operators/column-filter.dto.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/F,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AACxF,OAAO,EACL,SAAS,EACT,eAAe,EACf,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EACV,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACjG,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvF,OAAO,EACL,YAAY,EACZ,oBAAoB,GACrB,MAAM,wCAAwC,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,YAAY,EACV,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export const VERSION = '0.0.0';
 export { BaseFilter } from './base-filter.js';
 export { Filterable, getFilterableMetadata } from './decorator/filterable.decorator.js';
+export { normalizeAllowed, allowedFieldNames } from './decorator/allowed.js';
 export { FilterFor, getFilterForMap, getFilterForOptsMap, } from './decorator/filter-for.decorator.js';
 export { ApplyFilter, getApplyFilterMetadata } from './decorator/apply-filter.decorator.js';
 export { Relations, getRelationsMap, resolveRelation } from './decorator/relations.decorator.js';
@@ -13,7 +14,9 @@ export { FilterException, FilterNotRegisteredException, FilterMissingEntityExcep
 export { FILTER_MODULE_OPTIONS, FILTER_ADAPTER, FILTERABLE_METADATA, FILTER_FOR_METADATA, FILTER_FOR_OPTS_METADATA, FILTER_RELATIONS_METADATA, APPLY_FILTER_METADATA, APPLY_FILTER_REQ_KEY, TENANT_SCOPED_METADATA, CONTEXT_ACCESSOR, } from './tokens.js';
 export { resolveInputFromRequest } from './input/source-resolver.js';
 export { normalizeInput } from './input/normalizer.js';
+export { parseSpatieInput } from './input/spatie-parser.js';
 export { escapeLike } from './utils/escape-like.js';
+export { encodeCursor, decodeCursor, buildKeyset, extractCursorValues, } from './pagination/cursor.js';
 export { FILTER_OPERATORS, OPERATOR_ALIASES } from './operators/types.js';
 export { ColumnFilterDto } from './operators/column-filter.dto.js';
 export { validateColumnFilter, validateColumnFilters, normalizeOperator, InvalidColumnFilterError, MAX_FILTER_DEPTH, } from './operators/validate-column-filter.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AACxF,OAAO,EACL,SAAS,EACT,eAAe,EACf,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAK7C,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAEjG,OAAO,EACL,YAAY,EACZ,oBAAoB,GACrB,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAwBrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAOpD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAO9C,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE7E,OAAO,EACL,SAAS,EACT,eAAe,EACf,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAK7C,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAEjG,OAAO,EACL,YAAY,EACZ,oBAAoB,GACrB,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AA2BrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAQhC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,uCAAuC,CAAC"}

package/dist/input/spatie-parser.d.ts

@@ -0,0 +1,40 @@
+import type { StructuredInput } from '../types.js';
+/**
+ * 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 declare function parseSpatieInput(input: unknown): StructuredInput;
+//# sourceMappingURL=spatie-parser.d.ts.map

package/dist/input/spatie-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatie-parser.d.ts","sourceRoot":"","sources":["../../src/input/spatie-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAmChE"}

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"}