@querykitjs/core 1.2.0 → 2.0.0

package/dist/internal.d.cts

@@ -0,0 +1,249 @@
+import { SkippedCondition, SortDirection, Sort, CursorMeta, InfiniteMeta, OffsetMeta, Relations, QueryLimits, Filterable } from './index.cjs';
+export { Z as isRaw } from './raw-Bx8c-TrC.cjs';
+
+/**
+ * Opaque cursor tokens for keyset pagination, shared by every adapter so a token
+ * is interchangeable between them. A token is the base64url encoding of
+ * `{ v: <cursor value> }`; dates travel as ISO strings.
+ */
+declare function encodeCursor(value: unknown): string;
+/** The cursor value, or `undefined` for a missing or undecodable token. */
+declare function decodeCursor(cursor?: string | null): unknown | undefined;
+interface CursorToken {
+    k: string | number | boolean;
+    id: string | number | boolean;
+}
+/** A v2 token for a row's cursor value and primary key; signed when `secret` is given. */
+declare function encodeCursorToken(payload: {
+    k: unknown;
+    id: unknown;
+}, secret?: string): Promise<string>;
+/**
+ * The `{ k, id }` of a v2 token, `undefined` for no token. A v1 token, a
+ * non-scalar `k` / `id`, a missing or wrong signature (with `secret`) or
+ * anything undecodable throws `QueryKitError` — invalid-value, site cursorKey,
+ * `key` the cursor key in use (the same key as an adapter's cast error).
+ */
+declare function decodeCursorToken(token: string | null | undefined, options: {
+    source: string;
+    secret?: string;
+    key?: string;
+}): Promise<CursorToken | undefined>;
+
+interface Diagnostics {
+    /** Table (drizzle), model (prisma, mongoose) — reported as `source`. */
+    source: string;
+    strict: boolean;
+    onSkipped?: (info: SkippedCondition) => void;
+}
+declare function reportSkip(diag: Diagnostics | undefined, info: Omit<SkippedCondition, "source">): void;
+
+interface ContextStore<TContext extends object> {
+    get(): TContext | undefined;
+    /** Run `fn` with `patch` merged over the current context. */
+    run<T>(patch: TContext, fn: () => T): T;
+}
+declare function createContextStore<TContext extends object>(): ContextStore<TContext>;
+
+interface NormalizedSortItem {
+    key: string;
+    direction: SortDirection;
+}
+/**
+ * The wire `sort` array with a direction on every item. An item without a `key`
+ * (`null`, `{}`) is dropped — sort comes from the client, and a malformed item
+ * must not crash the query — and, with `diag`, reported as `invalid-value` on
+ * `site: "sort"` (a `QueryKitError` under strict; task 021 B14).
+ */
+declare function normalizeSort(sort?: Sort, diag?: Diagnostics): NormalizedSortItem[];
+
+/**
+ * Page-size clamping and the three pagination metas, computed once for every
+ * adapter so `total_pages`, `has_more`, `next_cursor` … mean the same thing on
+ * all of them. Adapters only fetch rows; these functions turn rows into a page.
+ */
+
+/** A requested page size, defaulted, truncated, at least 1 and at most `max`. */
+declare function clampPageSize(requested: number | undefined, fallback: number, max: number): number;
+/** A requested page number: an integer, at least 1. */
+declare function clampPage(requested: number | undefined): number;
+/** A requested offset: an integer, at least 0. */
+declare function clampOffset(requested: number | undefined): number;
+declare function offsetMeta(page: number, perPage: number, totalItems: number): OffsetMeta;
+/**
+ * `withTotal: false` (task 013): rows fetched with `perPage + 1` and no count →
+ * the page and its meta; the extra row only signals `has_next`, totals are `null`.
+ */
+declare function offsetPageWithoutTotal<T>(rows: readonly T[], page: number, perPage: number): {
+    data: T[];
+    meta: OffsetMeta;
+};
+/** Rows fetched with `limit + 1` → the page and its meta (the extra row only signals `has_more`). */
+declare function infinitePage<T>(rows: readonly T[], limit: number, offset: number): {
+    data: T[];
+    meta: InfiniteMeta;
+};
+interface CursorPageOptions {
+    limit: number;
+    direction: "forward" | "backward";
+    /** A cursor was supplied (the request continues from a previous page). */
+    hasCursor: boolean;
+    /** The row field the tokens are read from. */
+    cursorField: string;
+    /** The primary-key field — the tie-break value in every token (task 012). */
+    idField: string;
+    /** Signs the tokens (registry `cursorSecret`). */
+    secret?: string;
+}
+/**
+ * Rows fetched with `limit + 1` in query order → the page in display order and
+ * its meta. A backward page is fetched reversed and flipped back here.
+ */
+declare function cursorPage<T extends Record<string, unknown>>(rows: readonly T[], options: CursorPageOptions): Promise<{
+    data: T[];
+    meta: CursorMeta;
+}>;
+
+/** `{ all: true }` — and nothing else — asks for every row (the scope still applies). */
+declare function isAllRows(filter: unknown): boolean;
+/** `undefined`, `null`, `[]` or `{}`: no condition at all. */
+declare function isEmptyFilter(filter: unknown): boolean;
+/** A mutation without a condition — also one whose every condition was skipped. */
+declare function refuseEmptyFilter(source: string, method: "updateWhere" | "deleteWhere"): never;
+
+/**
+ * A repository `scope` (the server's RBAC / tenancy filter) split once for every
+ * adapter (task 014): equality values and `{ in: [...] }` lists.
+ */
+/** One scope condition, in the shape every adapter's `buildWhere` reads. */
+interface ScopeCondition {
+    key: string;
+    operation: "=" | "in";
+    value: unknown;
+}
+/** The scope as conditions: `{ k: v }` → `k = v`, `{ k: { in: [...] } }` → `k in [...]`. */
+declare function scopeConditions(scope: Record<string, unknown> | undefined): ScopeCondition[];
+/** The values `create` / `upsert` fill in: the equality scopes only (a list has no single value). */
+declare function scopeDefaults(scope: Record<string, unknown> | undefined): Record<string, unknown>;
+
+/** How one adapter spells a relation's options. */
+interface WithDialect {
+    /** Column selection: drizzle `columns`, prisma / mongoose `select`. */
+    columns: string;
+    /** Nested relations: drizzle `with`, prisma `include`, mongoose `populate`. */
+    nested: string;
+    /** Row filters: prisma `where`, mongoose `match`; drizzle none (its `where` is code, not JSON). */
+    filters: readonly string[];
+    /** Logical keys inside a filter, walked into: prisma `AND` / `OR` / `NOT`, mongoose `$and` / `$or` / `$nor`. */
+    logical: readonly string[];
+    /** Options that only page: drizzle `limit` / `offset`, prisma `take` / `skip`, mongoose `options.limit` / `options.skip`. */
+    paging: readonly string[];
+    /** A sort whose keys must be allowed columns: prisma `orderBy`. */
+    orderBy?: string;
+    /** An options bag whose keys must be `paging` keys: mongoose `options`. */
+    options?: string;
+}
+/**
+ * The checked `with`: every relation in `relations`, every selected column in its
+ * `columns`, every filter field in its `filterable`, every nested relation in its
+ * `nested`. A relation asked for with `true` (or without a selection) gets its
+ * listed columns selected, so a column list is never widened to the full row.
+ */
+declare function checkWith(withValue: unknown, relations: Relations | undefined, dialect: WithDialect, source: string, path?: string): Record<string, unknown> | undefined;
+
+/**
+ * The filter-limit walk shared by the validators (task 008). It runs on the raw,
+ * unvalidated payload **before** any recursive schema sees it, so it is
+ * iterative — no recursion at all, whatever the payload's depth — and a
+ * 10 000-level `not` chain is rejected after `maxDepth + 1` steps.
+ *
+ * Only size is judged here. Shape errors (a missing `key`, a bad operator) are
+ * the validator's job — a malformed node is skipped, not reported.
+ */
+
+/** Where in the filter a limit was crossed — object keys and array indexes, from the root. */
+type LimitPath = (string | number)[];
+interface LimitViolation {
+    limit: keyof QueryLimits;
+    max: number;
+    path: LimitPath;
+}
+/** The limits the walk checks. */
+type FilterLimits = Pick<QueryLimits, "maxDepth" | "maxConditions" | "maxInItems" | "maxStringLength">;
+/** `maxInItems (200)` — the form every package's error text uses. */
+declare const formatLimit: (limit: keyof QueryLimits, max: number) => string;
+/**
+ * The first limit the filter crosses, depth-first in document order, or
+ * `undefined` when it is within all four. A flat array (implicit AND) puts its
+ * conditions at level 1. Key order mirrors the validators: `key` first, then
+ * `and`, `or`, `not`.
+ */
+declare function findFilterLimitViolation(filter: unknown, limits: FilterLimits): LimitViolation | undefined;
+/** Whether an operator takes a SQL LIKE pattern. */
+declare const isLikeOperator: (operation: string) => boolean;
+/**
+ * Unescaped wildcards in a LIKE pattern, a run of `%` counted once (`%%a%` ⇒ 2).
+ * A backslash escapes the next character, as in the adapters' LIKE translation.
+ */
+declare function likeWildcards(pattern: string): number;
+/** Rows an offset-paginated request skips: `(page - 1) × perPage`, with the core default page size. */
+declare const offsetOf: (page: number | undefined, perPage: number | undefined) => number;
+
+/**
+ * The server-side request policy every adapter applies (task 009): which fields
+ * a client may filter by and with which operators (`filterable`), which it may
+ * sort and page by (`sortable`), and the request limits (`limits`, task 008).
+ *
+ * A plain object that is not a condition, a group, a branded `raw()` node or a
+ * driver-native object (`isNative`) is refused as well (R19): it would otherwise
+ * reach the driver as its own `where`, past `filterable`.
+ *
+ * A refused request never reaches the driver and is never dropped silently:
+ * every check throws `QueryKitError`, whatever `strict` / `onSkippedCondition`
+ * say. A key the model does not have is **not** the policy's business — it goes
+ * on to the adapter's own `unknown-key` handling, unchanged.
+ */
+
+interface PolicyOptions {
+    /** Table / model name for the error. */
+    source: string;
+    /** Wire key → the model's canonical field name, or `undefined` when the model has no such field. */
+    fieldOf: (key: string) => string | undefined;
+    /** Canonical primary-key field — the last-resort safe default. */
+    primaryKey: string;
+    /** Canonical `createdAt` field when the model has one (default `sortable`). */
+    createdAt?: string;
+    filterable?: Filterable;
+    sortable?: readonly string[];
+    allowedColumns?: readonly string[];
+    forcedColumns?: Readonly<Record<string, unknown>>;
+    limits?: Partial<QueryLimits>;
+    /**
+     * A driver object that cannot come from JSON and stands for itself (drizzle `SQL`).
+     * Anything else that is not a condition, a group or a {@link isRaw} node is refused (R19).
+     */
+    isNative?: (node: object) => boolean;
+}
+interface Policy {
+    readonly limits: QueryLimits;
+    /** Limits, then every condition's field and operator. */
+    checkFilter(filter: unknown): void;
+    /** Field count, then every sort field. */
+    checkSort(sort: readonly {
+        key?: unknown;
+    }[] | undefined): void;
+    checkCursorKey(key: string): void;
+    /** Offset pagination: the clamped `page` × `perPage`. Infinite: the clamped `offset`. */
+    checkPage(page: {
+        page: number;
+        perPage: number;
+    } | {
+        offset: number;
+    }): void;
+    /** A `groupBy` / `sum` / `avg` / `min` / `max` field must be filterable. */
+    checkAggregateKey(key: string): void;
+}
+declare function resolvePolicy(options: PolicyOptions): Policy;
+
+export { checkWith, clampOffset, clampPage, clampPageSize, createContextStore, cursorPage, decodeCursor, decodeCursorToken, encodeCursor, encodeCursorToken, findFilterLimitViolation, formatLimit, infinitePage, isAllRows, isEmptyFilter, isLikeOperator, likeWildcards, normalizeSort, offsetMeta, offsetOf, offsetPageWithoutTotal, refuseEmptyFilter, reportSkip, resolvePolicy, scopeConditions, scopeDefaults };
+export type { ContextStore, CursorPageOptions, CursorToken, Diagnostics, FilterLimits, LimitPath, LimitViolation, NormalizedSortItem, Policy, PolicyOptions, ScopeCondition, WithDialect };

package/dist/internal.d.ts

@@ -0,0 +1,249 @@
+import { SkippedCondition, SortDirection, Sort, CursorMeta, InfiniteMeta, OffsetMeta, Relations, QueryLimits, Filterable } from './index.js';
+export { Z as isRaw } from './raw-Bx8c-TrC.js';
+
+/**
+ * Opaque cursor tokens for keyset pagination, shared by every adapter so a token
+ * is interchangeable between them. A token is the base64url encoding of
+ * `{ v: <cursor value> }`; dates travel as ISO strings.
+ */
+declare function encodeCursor(value: unknown): string;
+/** The cursor value, or `undefined` for a missing or undecodable token. */
+declare function decodeCursor(cursor?: string | null): unknown | undefined;
+interface CursorToken {
+    k: string | number | boolean;
+    id: string | number | boolean;
+}
+/** A v2 token for a row's cursor value and primary key; signed when `secret` is given. */
+declare function encodeCursorToken(payload: {
+    k: unknown;
+    id: unknown;
+}, secret?: string): Promise<string>;
+/**
+ * The `{ k, id }` of a v2 token, `undefined` for no token. A v1 token, a
+ * non-scalar `k` / `id`, a missing or wrong signature (with `secret`) or
+ * anything undecodable throws `QueryKitError` — invalid-value, site cursorKey,
+ * `key` the cursor key in use (the same key as an adapter's cast error).
+ */
+declare function decodeCursorToken(token: string | null | undefined, options: {
+    source: string;
+    secret?: string;
+    key?: string;
+}): Promise<CursorToken | undefined>;
+
+interface Diagnostics {
+    /** Table (drizzle), model (prisma, mongoose) — reported as `source`. */
+    source: string;
+    strict: boolean;
+    onSkipped?: (info: SkippedCondition) => void;
+}
+declare function reportSkip(diag: Diagnostics | undefined, info: Omit<SkippedCondition, "source">): void;
+
+interface ContextStore<TContext extends object> {
+    get(): TContext | undefined;
+    /** Run `fn` with `patch` merged over the current context. */
+    run<T>(patch: TContext, fn: () => T): T;
+}
+declare function createContextStore<TContext extends object>(): ContextStore<TContext>;
+
+interface NormalizedSortItem {
+    key: string;
+    direction: SortDirection;
+}
+/**
+ * The wire `sort` array with a direction on every item. An item without a `key`
+ * (`null`, `{}`) is dropped — sort comes from the client, and a malformed item
+ * must not crash the query — and, with `diag`, reported as `invalid-value` on
+ * `site: "sort"` (a `QueryKitError` under strict; task 021 B14).
+ */
+declare function normalizeSort(sort?: Sort, diag?: Diagnostics): NormalizedSortItem[];
+
+/**
+ * Page-size clamping and the three pagination metas, computed once for every
+ * adapter so `total_pages`, `has_more`, `next_cursor` … mean the same thing on
+ * all of them. Adapters only fetch rows; these functions turn rows into a page.
+ */
+
+/** A requested page size, defaulted, truncated, at least 1 and at most `max`. */
+declare function clampPageSize(requested: number | undefined, fallback: number, max: number): number;
+/** A requested page number: an integer, at least 1. */
+declare function clampPage(requested: number | undefined): number;
+/** A requested offset: an integer, at least 0. */
+declare function clampOffset(requested: number | undefined): number;
+declare function offsetMeta(page: number, perPage: number, totalItems: number): OffsetMeta;
+/**
+ * `withTotal: false` (task 013): rows fetched with `perPage + 1` and no count →
+ * the page and its meta; the extra row only signals `has_next`, totals are `null`.
+ */
+declare function offsetPageWithoutTotal<T>(rows: readonly T[], page: number, perPage: number): {
+    data: T[];
+    meta: OffsetMeta;
+};
+/** Rows fetched with `limit + 1` → the page and its meta (the extra row only signals `has_more`). */
+declare function infinitePage<T>(rows: readonly T[], limit: number, offset: number): {
+    data: T[];
+    meta: InfiniteMeta;
+};
+interface CursorPageOptions {
+    limit: number;
+    direction: "forward" | "backward";
+    /** A cursor was supplied (the request continues from a previous page). */
+    hasCursor: boolean;
+    /** The row field the tokens are read from. */
+    cursorField: string;
+    /** The primary-key field — the tie-break value in every token (task 012). */
+    idField: string;
+    /** Signs the tokens (registry `cursorSecret`). */
+    secret?: string;
+}
+/**
+ * Rows fetched with `limit + 1` in query order → the page in display order and
+ * its meta. A backward page is fetched reversed and flipped back here.
+ */
+declare function cursorPage<T extends Record<string, unknown>>(rows: readonly T[], options: CursorPageOptions): Promise<{
+    data: T[];
+    meta: CursorMeta;
+}>;
+
+/** `{ all: true }` — and nothing else — asks for every row (the scope still applies). */
+declare function isAllRows(filter: unknown): boolean;
+/** `undefined`, `null`, `[]` or `{}`: no condition at all. */
+declare function isEmptyFilter(filter: unknown): boolean;
+/** A mutation without a condition — also one whose every condition was skipped. */
+declare function refuseEmptyFilter(source: string, method: "updateWhere" | "deleteWhere"): never;
+
+/**
+ * A repository `scope` (the server's RBAC / tenancy filter) split once for every
+ * adapter (task 014): equality values and `{ in: [...] }` lists.
+ */
+/** One scope condition, in the shape every adapter's `buildWhere` reads. */
+interface ScopeCondition {
+    key: string;
+    operation: "=" | "in";
+    value: unknown;
+}
+/** The scope as conditions: `{ k: v }` → `k = v`, `{ k: { in: [...] } }` → `k in [...]`. */
+declare function scopeConditions(scope: Record<string, unknown> | undefined): ScopeCondition[];
+/** The values `create` / `upsert` fill in: the equality scopes only (a list has no single value). */
+declare function scopeDefaults(scope: Record<string, unknown> | undefined): Record<string, unknown>;
+
+/** How one adapter spells a relation's options. */
+interface WithDialect {
+    /** Column selection: drizzle `columns`, prisma / mongoose `select`. */
+    columns: string;
+    /** Nested relations: drizzle `with`, prisma `include`, mongoose `populate`. */
+    nested: string;
+    /** Row filters: prisma `where`, mongoose `match`; drizzle none (its `where` is code, not JSON). */
+    filters: readonly string[];
+    /** Logical keys inside a filter, walked into: prisma `AND` / `OR` / `NOT`, mongoose `$and` / `$or` / `$nor`. */
+    logical: readonly string[];
+    /** Options that only page: drizzle `limit` / `offset`, prisma `take` / `skip`, mongoose `options.limit` / `options.skip`. */
+    paging: readonly string[];
+    /** A sort whose keys must be allowed columns: prisma `orderBy`. */
+    orderBy?: string;
+    /** An options bag whose keys must be `paging` keys: mongoose `options`. */
+    options?: string;
+}
+/**
+ * The checked `with`: every relation in `relations`, every selected column in its
+ * `columns`, every filter field in its `filterable`, every nested relation in its
+ * `nested`. A relation asked for with `true` (or without a selection) gets its
+ * listed columns selected, so a column list is never widened to the full row.
+ */
+declare function checkWith(withValue: unknown, relations: Relations | undefined, dialect: WithDialect, source: string, path?: string): Record<string, unknown> | undefined;
+
+/**
+ * The filter-limit walk shared by the validators (task 008). It runs on the raw,
+ * unvalidated payload **before** any recursive schema sees it, so it is
+ * iterative — no recursion at all, whatever the payload's depth — and a
+ * 10 000-level `not` chain is rejected after `maxDepth + 1` steps.
+ *
+ * Only size is judged here. Shape errors (a missing `key`, a bad operator) are
+ * the validator's job — a malformed node is skipped, not reported.
+ */
+
+/** Where in the filter a limit was crossed — object keys and array indexes, from the root. */
+type LimitPath = (string | number)[];
+interface LimitViolation {
+    limit: keyof QueryLimits;
+    max: number;
+    path: LimitPath;
+}
+/** The limits the walk checks. */
+type FilterLimits = Pick<QueryLimits, "maxDepth" | "maxConditions" | "maxInItems" | "maxStringLength">;
+/** `maxInItems (200)` — the form every package's error text uses. */
+declare const formatLimit: (limit: keyof QueryLimits, max: number) => string;
+/**
+ * The first limit the filter crosses, depth-first in document order, or
+ * `undefined` when it is within all four. A flat array (implicit AND) puts its
+ * conditions at level 1. Key order mirrors the validators: `key` first, then
+ * `and`, `or`, `not`.
+ */
+declare function findFilterLimitViolation(filter: unknown, limits: FilterLimits): LimitViolation | undefined;
+/** Whether an operator takes a SQL LIKE pattern. */
+declare const isLikeOperator: (operation: string) => boolean;
+/**
+ * Unescaped wildcards in a LIKE pattern, a run of `%` counted once (`%%a%` ⇒ 2).
+ * A backslash escapes the next character, as in the adapters' LIKE translation.
+ */
+declare function likeWildcards(pattern: string): number;
+/** Rows an offset-paginated request skips: `(page - 1) × perPage`, with the core default page size. */
+declare const offsetOf: (page: number | undefined, perPage: number | undefined) => number;
+
+/**
+ * The server-side request policy every adapter applies (task 009): which fields
+ * a client may filter by and with which operators (`filterable`), which it may
+ * sort and page by (`sortable`), and the request limits (`limits`, task 008).
+ *
+ * A plain object that is not a condition, a group, a branded `raw()` node or a
+ * driver-native object (`isNative`) is refused as well (R19): it would otherwise
+ * reach the driver as its own `where`, past `filterable`.
+ *
+ * A refused request never reaches the driver and is never dropped silently:
+ * every check throws `QueryKitError`, whatever `strict` / `onSkippedCondition`
+ * say. A key the model does not have is **not** the policy's business — it goes
+ * on to the adapter's own `unknown-key` handling, unchanged.
+ */
+
+interface PolicyOptions {
+    /** Table / model name for the error. */
+    source: string;
+    /** Wire key → the model's canonical field name, or `undefined` when the model has no such field. */
+    fieldOf: (key: string) => string | undefined;
+    /** Canonical primary-key field — the last-resort safe default. */
+    primaryKey: string;
+    /** Canonical `createdAt` field when the model has one (default `sortable`). */
+    createdAt?: string;
+    filterable?: Filterable;
+    sortable?: readonly string[];
+    allowedColumns?: readonly string[];
+    forcedColumns?: Readonly<Record<string, unknown>>;
+    limits?: Partial<QueryLimits>;
+    /**
+     * A driver object that cannot come from JSON and stands for itself (drizzle `SQL`).
+     * Anything else that is not a condition, a group or a {@link isRaw} node is refused (R19).
+     */
+    isNative?: (node: object) => boolean;
+}
+interface Policy {
+    readonly limits: QueryLimits;
+    /** Limits, then every condition's field and operator. */
+    checkFilter(filter: unknown): void;
+    /** Field count, then every sort field. */
+    checkSort(sort: readonly {
+        key?: unknown;
+    }[] | undefined): void;
+    checkCursorKey(key: string): void;
+    /** Offset pagination: the clamped `page` × `perPage`. Infinite: the clamped `offset`. */
+    checkPage(page: {
+        page: number;
+        perPage: number;
+    } | {
+        offset: number;
+    }): void;
+    /** A `groupBy` / `sum` / `avg` / `min` / `max` field must be filterable. */
+    checkAggregateKey(key: string): void;
+}
+declare function resolvePolicy(options: PolicyOptions): Policy;
+
+export { checkWith, clampOffset, clampPage, clampPageSize, createContextStore, cursorPage, decodeCursor, decodeCursorToken, encodeCursor, encodeCursorToken, findFilterLimitViolation, formatLimit, infinitePage, isAllRows, isEmptyFilter, isLikeOperator, likeWildcards, normalizeSort, offsetMeta, offsetOf, offsetPageWithoutTotal, refuseEmptyFilter, reportSkip, resolvePolicy, scopeConditions, scopeDefaults };
+export type { ContextStore, CursorPageOptions, CursorToken, Diagnostics, FilterLimits, LimitPath, LimitViolation, NormalizedSortItem, Policy, PolicyOptions, ScopeCondition, WithDialect };