@adonis-agora/filter 0.1.0

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,30 @@
+# `@adonis-agora/filter`
+
+Server-side query filtering, sorting, and pagination for AdonisJS. Parses the
+Spatie/JSON:API query the `@agora/filter-client` builder emits, applies it to a
+Lucid query through a field allow-list, and resolves offset or keyset (cursor)
+pagination.
+
+```ts
+import { parseFilterRequest, applyFilter } from '@adonis-agora/filter'
+
+const input = parseFilterRequest(ctx.request.qs())
+const query = User.query()
+const { page, size } = applyFilter(query, input, {
+  allowed: ['name', 'email', 'age'],
+  searchable: ['name', 'email'],
+})
+return query.paginate(page, size)
+```
+
+Operators: equals/notEquals, contains/iContains/startsWith/endsWith, gt/gte/lt/lte,
+between/notBetween, in/notIn/isAnyOf, isNull/isNotNull/isEmpty/isNotEmpty, plus
+AND/OR composition. The `allowed`/`sortable`/`searchable` lists are the security
+boundary. The Lucid binding is structural (`QueryBuilderLike`) so any Lucid query
+builder works and the adapter is unit-testable.
+
+See the [repository README](https://github.com/DavideCarvalho/adonis-filter).
+
+## License
+
+MIT © Davi Carvalho

package/dist/commands/main.d.ts

@@ -0,0 +1,17 @@
+import { ListLoader } from '@adonisjs/core/ace';
+import MakeFilterClient from './make_filter_client.js';
+/**
+ * The commands barrel for `@adonis-agora/filter`. An app registers it in its
+ * `adonisrc` via `rcFile.addCommand('@adonis-agora/filter/commands')`. A
+ * {@link ListLoader} exposes the `make:filter-client` command's metadata and
+ * constructor to the ace kernel.
+ *
+ * `@adonisjs/core` is an *optional* peer of this otherwise framework-free core —
+ * only this `./commands` subpath imports it, so the main entrypoint stays
+ * dependency-free.
+ */
+declare const loader: ListLoader<typeof MakeFilterClient>;
+export declare const getMetaData: () => Promise<import("@adonisjs/core/types/ace").CommandMetaData[]>;
+export declare const getCommand: (metaData: import("@adonisjs/core/types/ace").CommandMetaData) => Promise<typeof MakeFilterClient | null>;
+export default loader;
+//# sourceMappingURL=main.d.ts.map

package/dist/commands/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,gBAAgB,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;GASG;AACH,QAAA,MAAM,MAAM,qCAAqC,CAAC;AAElD,eAAO,MAAM,WAAW,qEAAkC,CAAC;AAC3D,eAAO,MAAM,UAAU,2GAAiC,CAAC;AAEzD,eAAe,MAAM,CAAC"}

package/dist/commands/main.js

@@ -0,0 +1,17 @@
+import { ListLoader } from '@adonisjs/core/ace';
+import MakeFilterClient from './make_filter_client.js';
+/**
+ * The commands barrel for `@adonis-agora/filter`. An app registers it in its
+ * `adonisrc` via `rcFile.addCommand('@adonis-agora/filter/commands')`. A
+ * {@link ListLoader} exposes the `make:filter-client` command's metadata and
+ * constructor to the ace kernel.
+ *
+ * `@adonisjs/core` is an *optional* peer of this otherwise framework-free core —
+ * only this `./commands` subpath imports it, so the main entrypoint stays
+ * dependency-free.
+ */
+const loader = new ListLoader([MakeFilterClient]);
+export const getMetaData = loader.getMetaData.bind(loader);
+export const getCommand = loader.getCommand.bind(loader);
+export default loader;
+//# sourceMappingURL=main.js.map

package/dist/commands/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,gBAAgB,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;GASG;AACH,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAElD,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAe,MAAM,CAAC"}

package/dist/commands/make_filter_client.d.ts

@@ -0,0 +1,35 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+/**
+ * `node ace make:filter-client [entrypoint]` — the idiomatic AdonisJS equivalent
+ * of the NestJS `nestjs-filter` codegen bin.
+ *
+ * Where NestJS ships a standalone `reflect-metadata` bin that reads decorator
+ * metadata off entity classes, the Adonis filter declaration is already a plain
+ * runtime {@link FilterClientManifest} (`defineFilter(...)` specs), so this is a
+ * thin IO wrapper: it loads the app's declared `filters` manifest, hands it to
+ * the pure {@link generateFilterClients} core, and writes each emitted typed
+ * client to disk. All generation logic lives in `../src/generate_client.ts` and
+ * is unit-tested there — this command only does the file IO.
+ *
+ * The entrypoint module (default `config/filter.js`) must export a `filters`
+ * manifest (named export, or default):
+ *
+ * ```ts
+ * // config/filter.ts
+ * import { defineFilter } from '@adonis-agora/filter'
+ * export const filters = {
+ *   people: { spec: defineFilter({ filterable: ['name', 'age'] }), fieldTypes: { age: { kind: 'number' } } },
+ * }
+ * ```
+ */
+export default class MakeFilterClient extends BaseCommand {
+    #private;
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    entrypoint: string;
+    output: string;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=make_filter_client.d.ts.map

package/dist/commands/make_filter_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_filter_client.d.ts","sourceRoot":"","sources":["../../commands/make_filter_client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAe,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,OAAO,OAAO,gBAAiB,SAAQ,WAAW;;IACvD,OAAgB,WAAW,SAAwB;IACnD,OAAgB,WAAW,SAC4C;IACvE,OAAgB,OAAO,EAAE,cAAc,CAAsB;IAOrD,UAAU,EAAE,MAAM,CAAC;IAMnB,MAAM,EAAE,MAAM,CAAC;IAER,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAsCpC"}

package/dist/commands/make_filter_client.js

@@ -0,0 +1,85 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { mkdir, writeFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { BaseCommand, args, flags } from '@adonisjs/core/ace';
+import { generateFilterClients } from '../src/generate_client.js';
+/**
+ * `node ace make:filter-client [entrypoint]` — the idiomatic AdonisJS equivalent
+ * of the NestJS `nestjs-filter` codegen bin.
+ *
+ * Where NestJS ships a standalone `reflect-metadata` bin that reads decorator
+ * metadata off entity classes, the Adonis filter declaration is already a plain
+ * runtime {@link FilterClientManifest} (`defineFilter(...)` specs), so this is a
+ * thin IO wrapper: it loads the app's declared `filters` manifest, hands it to
+ * the pure {@link generateFilterClients} core, and writes each emitted typed
+ * client to disk. All generation logic lives in `../src/generate_client.ts` and
+ * is unit-tested there — this command only does the file IO.
+ *
+ * The entrypoint module (default `config/filter.js`) must export a `filters`
+ * manifest (named export, or default):
+ *
+ * ```ts
+ * // config/filter.ts
+ * import { defineFilter } from '@adonis-agora/filter'
+ * export const filters = {
+ *   people: { spec: defineFilter({ filterable: ['name', 'age'] }), fieldTypes: { age: { kind: 'number' } } },
+ * }
+ * ```
+ */
+export default class MakeFilterClient extends BaseCommand {
+    static commandName = 'make:filter-client';
+    static description = "Generate typed filter clients from the app's declared filter specs";
+    static options = { startApp: true };
+    async run() {
+        const manifest = await this.#loadManifest();
+        if (!manifest)
+            return;
+        const outDir = isAbsolute(this.output) ? this.output : this.app.makePath(this.output);
+        await mkdir(outDir, { recursive: true });
+        const generated = generateFilterClients(manifest);
+        for (const client of generated) {
+            const path = join(outDir, client.filename);
+            await writeFile(path, client.code, 'utf-8');
+            this.logger.action(`create ${path}`).succeeded();
+        }
+        this.logger.success(`Generated ${generated.length} filter client(s) into ${this.output}.`);
+    }
+    /** Import the entrypoint module and read its `filters` manifest (named or default export). */
+    async #loadManifest() {
+        const url = this.app.makeURL(this.entrypoint).href;
+        let mod;
+        try {
+            mod = (await import(url));
+        }
+        catch (error) {
+            this.logger.error(`Could not import filter manifest "${this.entrypoint}": ${String(error)}`);
+            this.exitCode = 1;
+            return undefined;
+        }
+        const manifest = (mod.filters ?? mod.default);
+        if (!manifest || Object.keys(manifest).length === 0) {
+            this.logger.warning(`No \`filters\` manifest exported from "${this.entrypoint}" — nothing to generate.`);
+            return undefined;
+        }
+        return manifest;
+    }
+}
+__decorate([
+    args.string({
+        description: 'Module exporting a `filters` manifest',
+        required: false,
+        default: 'config/filter.js',
+    })
+], MakeFilterClient.prototype, "entrypoint", void 0);
+__decorate([
+    flags.string({
+        description: 'Output directory for the generated clients',
+        default: 'app/generated/filters',
+    })
+], MakeFilterClient.prototype, "output", void 0);
+//# sourceMappingURL=make_filter_client.js.map

package/dist/commands/make_filter_client.js.map

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

package/dist/src/apply_from_request.d.ts

@@ -0,0 +1,69 @@
+import type { ResolvedCursor } from './cursor.js';
+import { type FilterSpec } from './filter_spec.js';
+import { type QueryBuilderLike } from './lucid_adapter.js';
+import { type ResolvedPagination } from './runner.js';
+import type { FilterInput } from './types.js';
+/**
+ * The structural slice of an AdonisJS `HttpContext` these helpers read. Only
+ * `request.qs()` (the decoded query string) is used to source the raw input;
+ * the whole ctx is also handed to a spec's tenant resolver. Declared
+ * structurally so the package never hard-imports `@adonisjs/core` — a real
+ * `HttpContext` satisfies it, and tests can pass a plain object.
+ */
+export interface FilterRequestContext {
+    request?: {
+        qs?: () => Record<string, unknown>;
+    };
+    [key: string]: any;
+}
+/** Options shared by the request-driven helpers. */
+export interface ApplyFromRequestOptions {
+    /**
+     * Pre-parsed input to use instead of reading `ctx.request.qs()`. Useful for
+     * non-HTTP callers and tests; when omitted the query string is parsed via
+     * {@link parseFilterRequest}.
+     */
+    input?: FilterInput;
+    /**
+     * Query embedding for pgvector embedding-similarity ranking (distinct from the
+     * text `search`). The idiomatic path: the controller computes it from an
+     * embedding service and passes it here (rather than shipping a large float
+     * array through the query string). Ignored unless the spec declares a
+     * `vectorSimilarity` column; merged over any `input.vectorSimilarity`.
+     */
+    vectorSimilarity?: readonly number[];
+}
+/** Options for {@link applyCursorFromRequest}. */
+export interface ApplyCursorFromRequestOptions extends ApplyFromRequestOptions {
+    /** Primary-key column appended to the keyset as a stable tiebreaker. Default `'id'`. */
+    primaryKey?: string;
+}
+/**
+ * Apply a {@link FilterSpec} to a Lucid query from a request context, returning
+ * the resolved offset pagination — the single explicit call an AdonisJS
+ * controller makes (the idiomatic replacement for the NestJS
+ * `ApplyFilterInterceptor` + `@ApplyFilter` param decorator).
+ *
+ * It resolves the request input from `ctx.request.qs()`, injects the server
+ * scope (tenant + default filters) that is never exposed to the allow-list, and
+ * delegates the allow-listed filter/sort/search + pagination resolution to
+ * {@link applyFilter}.
+ *
+ * ```ts
+ * const spec = defineFilter({ filterable: ['name', 'age'], tenant: { column: 'tenantId', resolve: (ctx) => ctx.auth.user.tenantId } })
+ *
+ * // in a controller:
+ * const query = User.query()
+ * const { page, size } = applyFilterFromRequest(query, spec, ctx)
+ * return query.paginate(page, size)
+ * ```
+ */
+export declare function applyFilterFromRequest(query: QueryBuilderLike, spec: FilterSpec, ctx: FilterRequestContext | undefined, options?: ApplyFromRequestOptions): ResolvedPagination;
+/**
+ * The keyset (cursor) counterpart of {@link applyFilterFromRequest}. Sources the
+ * request filters and the `after`/`before`/`first`/`last` cursor params from ctx,
+ * injects the same server scope, and delegates to {@link applyCursor}. Feed the
+ * fetched rows and the returned {@link ResolvedCursor} to `buildCursorPage`.
+ */
+export declare function applyCursorFromRequest(query: QueryBuilderLike, spec: FilterSpec, ctx: FilterRequestContext | undefined, options?: ApplyCursorFromRequestOptions): ResolvedCursor;
+//# sourceMappingURL=apply_from_request.d.ts.map

package/dist/src/apply_from_request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply_from_request.d.ts","sourceRoot":"","sources":["../../src/apply_from_request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,KAAK,UAAU,EAAsB,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG/E,OAAO,EAAqB,KAAK,kBAAkB,EAA4B,MAAM,aAAa,CAAC;AACnG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAEjD,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,kDAAkD;AAClD,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;IAC5E,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA6CD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,oBAAoB,GAAG,SAAS,EACrC,OAAO,GAAE,uBAA4B,GACpC,kBAAkB,CAQpB;AA6BD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,oBAAoB,GAAG,SAAS,EACrC,OAAO,GAAE,6BAAkC,GAC1C,cAAc,CAahB"}

package/dist/src/apply_from_request.js

@@ -0,0 +1,115 @@
+import { specToFilterConfig } from './filter_spec.js';
+import { applyColumnFilters } from './lucid_adapter.js';
+import { parseFilterRequest } from './parse_request.js';
+import { applyCursor, applyFilter } from './runner.js';
+/** Read the decoded query string off the ctx (empty object when absent). */
+function rawQs(ctx) {
+    const qs = ctx?.request?.qs;
+    if (typeof qs === 'function')
+        return qs.call(ctx?.request) ?? {};
+    return {};
+}
+/**
+ * Apply the server-side, non-client-tamperable scope to the query BEFORE the
+ * allow-listed request filters: the tenant constraint (when the spec declares
+ * one and a tenant id resolves from ctx) and any `defaultFilters`. These bypass
+ * the allow-list on purpose — they are trusted server policy, mirroring how the
+ * NestJS runner applied `@TenantScoped` via the adapter's auto-field path.
+ */
+function applyServerScope(query, spec, ctx) {
+    const serverFilters = [];
+    if (spec.tenant) {
+        const tenantId = spec.tenant.resolve(ctx);
+        if (tenantId !== undefined && tenantId !== null) {
+            serverFilters.push({ field: spec.tenant.column, operator: 'equals', value: tenantId });
+        }
+    }
+    if (spec.defaultFilters.length > 0) {
+        serverFilters.push(...spec.defaultFilters);
+    }
+    if (serverFilters.length > 0) {
+        applyColumnFilters(query, serverFilters);
+    }
+}
+/** Fall back to the spec's `defaultSort` when the request supplied no sort. */
+function withDefaultSort(input, spec) {
+    if ((!input.sort || input.sort.length === 0) && spec.defaultSort.length > 0) {
+        return { ...input, sort: [...spec.defaultSort] };
+    }
+    return input;
+}
+/**
+ * Apply a {@link FilterSpec} to a Lucid query from a request context, returning
+ * the resolved offset pagination — the single explicit call an AdonisJS
+ * controller makes (the idiomatic replacement for the NestJS
+ * `ApplyFilterInterceptor` + `@ApplyFilter` param decorator).
+ *
+ * It resolves the request input from `ctx.request.qs()`, injects the server
+ * scope (tenant + default filters) that is never exposed to the allow-list, and
+ * delegates the allow-listed filter/sort/search + pagination resolution to
+ * {@link applyFilter}.
+ *
+ * ```ts
+ * const spec = defineFilter({ filterable: ['name', 'age'], tenant: { column: 'tenantId', resolve: (ctx) => ctx.auth.user.tenantId } })
+ *
+ * // in a controller:
+ * const query = User.query()
+ * const { page, size } = applyFilterFromRequest(query, spec, ctx)
+ * return query.paginate(page, size)
+ * ```
+ */
+export function applyFilterFromRequest(query, spec, ctx, options = {}) {
+    const parsed = options.input ?? parseFilterRequest(rawQs(ctx));
+    const withVector = options.vectorSimilarity !== undefined
+        ? { ...parsed, vectorSimilarity: options.vectorSimilarity }
+        : parsed;
+    applyServerScope(query, spec, ctx);
+    return applyFilter(query, withDefaultSort(withVector, spec), specToFilterConfig(spec));
+}
+/** Parse cursor (keyset) params from a decoded query string (Spatie `page[...]` shapes). */
+function parseCursorParams(qs) {
+    const out = {};
+    const page = qs.page != null && typeof qs.page === 'object' && !Array.isArray(qs.page)
+        ? qs.page
+        : undefined;
+    const after = qs.after ?? page?.after;
+    const before = qs.before ?? page?.before;
+    if (typeof after === 'string' && after.length > 0)
+        out.after = after;
+    else if (typeof before === 'string' && before.length > 0)
+        out.before = before;
+    const first = qs.first ?? page?.first;
+    const last = qs.last ?? page?.last;
+    const toInt = (v) => {
+        const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : NaN;
+        return Number.isFinite(n) ? n : undefined;
+    };
+    const f = toInt(first);
+    const l = toInt(last);
+    if (f !== undefined)
+        out.first = f;
+    if (l !== undefined)
+        out.last = l;
+    return out;
+}
+/**
+ * The keyset (cursor) counterpart of {@link applyFilterFromRequest}. Sources the
+ * request filters and the `after`/`before`/`first`/`last` cursor params from ctx,
+ * injects the same server scope, and delegates to {@link applyCursor}. Feed the
+ * fetched rows and the returned {@link ResolvedCursor} to `buildCursorPage`.
+ */
+export function applyCursorFromRequest(query, spec, ctx, options = {}) {
+    const qs = rawQs(ctx);
+    const parsed = options.input ?? parseFilterRequest(qs);
+    const full = {
+        ...withDefaultSort(parsed, spec),
+        ...parseCursorParams(qs),
+    };
+    applyServerScope(query, spec, ctx);
+    const config = {
+        ...specToFilterConfig(spec),
+        ...(options.primaryKey !== undefined && { primaryKey: options.primaryKey }),
+    };
+    return applyCursor(query, full, config);
+}
+//# sourceMappingURL=apply_from_request.js.map

package/dist/src/apply_from_request.js.map

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

package/dist/src/cursor.d.ts

@@ -0,0 +1,92 @@
+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 {@link SortItem}[].
+ */
+export type CursorValues = unknown[];
+/**
+ * Cursor (keyset) pagination parameters, as parsed from a request:
+ *
+ * - `after` — return the page immediately following this opaque cursor (forward).
+ * - `before` — return the page immediately preceding this opaque cursor (backward).
+ * - `first` / `last` — page size for forward / backward paging respectively.
+ *
+ * `after` and `before` are mutually exclusive; if both are given, `after` wins.
+ */
+export interface CursorParams {
+    after?: string;
+    before?: string;
+    first?: number;
+    last?: number;
+}
+/**
+ * A single page of keyset-paginated results assembled by {@link buildCursorPage}.
+ *
+ * - `items` — the rows for this page, in the requested order.
+ * - `nextCursor` — opaque cursor for the next forward page, or `null` when this
+ *   is the last page.
+ * - `prevCursor` — opaque cursor for the previous (backward) page, or `null`
+ *   when this is the first page.
+ * - `hasNext` / `hasPrev` — convenience booleans mirroring the cursors.
+ */
+export interface CursorPage<T> {
+    items: T[];
+    nextCursor: string | null;
+    prevCursor: string | null;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * 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 {@link 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[];
+/** Flips every keyset column's direction (for backward cursor paging). */
+export declare function reverseKeyset(keyset: SortItem[]): 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;
+/** The keyset shape {@link applyCursor} resolves and hands to {@link buildCursorPage}. */
+export interface ResolvedCursor {
+    /** The base keyset (effective sort + primary-key tiebreaker), in forward order. */
+    keyset: SortItem[];
+    /** Effective page size — the number of rows to keep for this page. */
+    size: number;
+    /** True when paging backward (a `before` cursor was supplied). */
+    backward: boolean;
+    /** True when a cursor (`after`/`before`) was supplied — the opposite page is then known to exist. */
+    hasCursor: boolean;
+}
+/**
+ * Assembles a {@link CursorPage} from the rows fetched for a keyset query.
+ *
+ * The query is expected to have been built by {@link applyCursor}, which fetches
+ * one extra row (`limit = size + 1`) so we can detect a further page. For
+ * backward paging the rows come back reversed and are flipped here to restore
+ * the caller's requested order. Boundary cursors are computed from the base
+ * keyset so they round-trip regardless of paging direction.
+ */
+export declare function buildCursorPage<T extends Record<string, unknown>>(rows: T[], resolved: ResolvedCursor): CursorPage<T>;
+//# sourceMappingURL=cursor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,EAAE,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;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,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAK5D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,QAAQ,EAAE,GACjB,YAAY,CAUd;AAED,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAC;IAClB,qGAAqG;IACrG,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,IAAI,EAAE,CAAC,EAAE,EACT,QAAQ,EAAE,cAAc,GACvB,UAAU,CAAC,CAAC,CAAC,CAwBf"}

package/dist/src/cursor.js

@@ -0,0 +1,107 @@
+/**
+ * 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 {@link 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 }];
+}
+/** Flips every keyset column's direction (for backward cursor paging). */
+export function reverseKeyset(keyset) {
+    return keyset.map((s) => ({
+        field: s.field,
+        direction: s.direction === 'asc' ? 'desc' : 'asc',
+    }));
+}
+/**
+ * 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;
+    });
+}
+/**
+ * Assembles a {@link CursorPage} from the rows fetched for a keyset query.
+ *
+ * The query is expected to have been built by {@link applyCursor}, which fetches
+ * one extra row (`limit = size + 1`) so we can detect a further page. For
+ * backward paging the rows come back reversed and are flipped here to restore
+ * the caller's requested order. Boundary cursors are computed from the base
+ * keyset so they round-trip regardless of paging direction.
+ */
+export function buildCursorPage(rows, resolved) {
+    const { keyset, size, backward, hasCursor } = resolved;
+    const hasExtra = rows.length > size;
+    let pageRows = hasExtra ? rows.slice(0, size) : rows;
+    if (backward)
+        pageRows = pageRows.slice().reverse();
+    const firstRow = pageRows[0];
+    const lastRow = pageRows[pageRows.length - 1];
+    const startCursor = firstRow ? encodeCursor(extractCursorValues(firstRow, keyset)) : null;
+    const endCursor = lastRow ? encodeCursor(extractCursorValues(lastRow, keyset)) : null;
+    // With a cursor present, the opposite-direction page is known to exist; the
+    // same-direction page exists iff we saw the extra row.
+    const hasNext = backward ? hasCursor : hasExtra;
+    const hasPrev = backward ? hasExtra : hasCursor;
+    return {
+        items: pageRows,
+        nextCursor: hasNext ? endCursor : null,
+        prevCursor: hasPrev ? startCursor : null,
+        hasNext,
+        hasPrev,
+    };
+}
+//# sourceMappingURL=cursor.js.map

package/dist/src/cursor.js.map

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