query-builder-prisma 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,481 @@
+/**
+ * Structural contracts — the ONLY knowledge this package has about Prisma.
+ *
+ * Nothing here imports Prisma. Any object exposing `findMany` + `count` with the
+ * standard Prisma delegate call shape satisfies these contracts — Prisma 5, 6, 7,
+ * 8, and (per ARCHITECTURE.md, invariant 2) any future version that keeps its
+ * public API.
+ */
+/**
+ * Minimal structural contract every Prisma model delegate (e.g. `prisma.user`)
+ * already satisfies. Used only as an upper bound so the concrete delegate type is
+ * preserved at call sites while keeping our classes generic.
+ */
+interface PrismaModelDelegate {
+    findMany: (...args: never[]) => unknown;
+    count: (...args: never[]) => unknown;
+}
+/** `findMany` arguments for the given delegate, derived from the delegate itself. */
+type FindManyArgsOf<D extends PrismaModelDelegate> = NonNullable<Parameters<D['findMany']>[0]>;
+/** `where` input of the model, derived from the delegate. */
+type WhereOf<D extends PrismaModelDelegate> = NonNullable<FindManyArgsOf<D>['where']>;
+/** `select` input of the model, derived from the delegate. */
+type SelectOf<D extends PrismaModelDelegate> = NonNullable<FindManyArgsOf<D>['select']>;
+/** `include` input of the model, derived from the delegate. */
+type IncludeOf<D extends PrismaModelDelegate> = NonNullable<FindManyArgsOf<D>['include']>;
+/** Scalar/relation keys that can be referenced from a model's `where` input. */
+type WhereKeyOf<D extends PrismaModelDelegate> = keyof WhereOf<D> & string;
+/** `orderBy` input of the model, derived from the delegate. */
+type OrderByOf<D extends PrismaModelDelegate> = NonNullable<FindManyArgsOf<D>['orderBy']>;
+/** Keys that can be used to order a model's results. */
+type OrderKeyOf<D extends PrismaModelDelegate> = OrderByOf<D> extends infer O ? O extends readonly unknown[] ? keyof O[number] & string : keyof O & string : never;
+/** The rows array `findMany` resolves to, derived from the delegate. */
+type RowsOf<D extends PrismaModelDelegate> = Awaited<ReturnType<D['findMany']>>;
+/** A single row of the model, derived from the delegate. */
+type RowElementOf<D extends PrismaModelDelegate> = RowsOf<D> extends readonly (infer E)[] ? E : never;
+
+/**
+ * Structural projection engine (ARCHITECTURE.md, invariant 3).
+ *
+ * Narrows the output type of `findMany` according to the accumulated
+ * `select`/`include` arguments — without importing a single Prisma type.
+ * Everything is derived from the model's own row type, which already encodes
+ * relation shapes, so this works on every Prisma version.
+ *
+ * Degradation rule: when Prisma's exact semantics can't be mirrored, the result
+ * is the *wider but correct* type — never a wrong one.
+ */
+
+/** Keys of a select/include spec that are "on" (`true` or a nested spec). */
+type TruthyKeys<S> = {
+    [K in keyof S]-?: NonNullable<S[K]> extends false ? never : K;
+}[keyof S];
+/**
+ * Apply a `select` spec to a row: only selected fields remain, nested selects
+ * recurse into relation element types.
+ */
+type ApplySelect<Row, S> = {
+    [K in TruthyKeys<S> & keyof Row]: ProjectField<Row[K], S[K]>;
+};
+/**
+ * Apply an `include` spec to a row: all base fields stay, included relations are
+ * projected (recursively when the include carries a nested `select`), and a
+ * truthy `_count` widens in as `Record<string, number>` (audit F9 — the engine
+ * cannot know the selected relation keys, so it degrades wide, never wrong).
+ */
+type ApplyInclude<Row, I> = Row & {
+    [K in TruthyKeys<I> & (keyof Row | '_count')]: K extends '_count' ? Record<string, number> : ProjectField<Row[K & keyof Row], I[K]>;
+};
+/** Project one field (`Field`) according to its select/include `Spec`. */
+type ProjectField<Field, Spec> = Spec extends true ? Field : Spec extends {
+    select: infer Sub;
+} ? ProjectNested<Field, Sub> : Spec extends {
+    include: infer Sub;
+} ? ProjectNestedInclude<Field, Sub> : Field;
+/**
+ * Project a relation field through a `select`. Only the selected keys remain.
+ * Lists map over their element; optionality (`| null | undefined`) is preserved
+ * exactly.
+ */
+type ProjectNested<Field, Sub> = Field extends readonly (infer E)[] ? ApplySelect<E, Sub>[] : ApplySelect<NonNullable<Field>, Sub> | (undefined extends Field ? undefined : never) | (null extends Field ? null : never);
+/**
+ * Project a relation field through an `include`. Unlike select, include keeps
+ * the relation's own fields — the element is intersected with its projection
+ * via `ApplyInclude` (audit F3). Lists map over their element; optionality is
+ * preserved exactly.
+ */
+type ProjectNestedInclude<Field, Sub> = Field extends readonly (infer E)[] ? ApplyInclude<E, Sub>[] : ApplyInclude<NonNullable<Field>, Sub> | (undefined extends Field ? undefined : never) | (null extends Field ? null : never);
+/**
+ * The row shape produced by a `findMany` call with the given accumulated args.
+ * With no `select`/`include`, this is the full model row (identity).
+ */
+type ApplyProjection<Row, TArgs> = TArgs extends {
+    select: infer S;
+} ? ApplySelect<Row, S> : TArgs extends {
+    include: infer I;
+} ? ApplyInclude<Row, I> : Row;
+/** The array a builder's `execute()` resolves to for the given delegate + args. */
+type FindResultOf<D extends PrismaModelDelegate, TArgs> = ApplyProjection<RowElementOf<D>, TArgs>[];
+
+/** Sort direction accepted by Prisma's `orderBy`. */
+type SortOrder = 'asc' | 'desc';
+/** Direction to walk through a cursor-paginated result set. */
+type CursorDirection = 'forward' | 'backward';
+/** A single numeric/date/string bound used by `QueryBuilder.range()`. */
+type RangeBound = string | number | Date;
+/** Open/closed bounds for one field path. Omitted bounds are skipped. */
+interface RangeInput {
+    from?: RangeBound | undefined;
+    to?: RangeBound | undefined;
+}
+/** Offset pagination metadata returned by `executeWithMeta()`. */
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPage: number;
+}
+/**
+ * Metadata shape when `executeWithMeta({ includeTotal: false })` skips the
+ * `COUNT` query — the totals are unknown, not zero (audit G3).
+ */
+interface PaginationMetaNoTotal {
+    page: number;
+    limit: number;
+    total: null;
+    totalPage: null;
+}
+/** Cursor pagination metadata returned by `executeWithCursor()`. */
+interface CursorMeta {
+    limit: number;
+    /** Cursor to pass as `cursor` to fetch the next page (`null` if none). */
+    nextCursor: string | null;
+    /** Cursor to pass as `cursor` (with `direction: 'backward'`) for the previous page. */
+    prevCursor: string | null;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+/**
+ * A partial `where` whose values may also be `undefined`, so optional query
+ * params can be forwarded directly (they are stripped out at build time).
+ */
+type FilterInput<D extends PrismaModelDelegate> = {
+    [K in WhereKeyOf<D>]?: WhereOf<D>[K] | undefined;
+};
+
+/**
+ * Per-database capability sets (ARCHITECTURE.md, invariant 4).
+ *
+ * Prisma-supported databases disagree on filter operators — most importantly,
+ * `mode: 'insensitive'` is only accepted on PostgreSQL, CockroachDB and MongoDB,
+ * and *throws* on MySQL, MariaDB, SQLite and SQL Server. Capability records let
+ * every builder method ask "what is allowed here?" instead of hardcoding
+ * database names.
+ */
+interface DialectCapabilities {
+    /**
+     * Prisma accepts `mode: 'insensitive'` on string filters for this dialect
+     * (postgresql, cockroachdb, mongodb).
+     */
+    caseInsensitiveMode: boolean;
+    /**
+     * The database's default collation makes `contains` case-insensitive without
+     * any extra argument (mysql, mariadb, sqlserver). For sqlite this is `false`:
+     * ASCII `LIKE` is case-sensitive there, and Prisma offers no `mode`.
+     */
+    caseInsensitiveCollation: boolean;
+}
+/** Built-in capability sets, one per database Prisma supports (plus universal). */
+declare const DIALECT_CAPABILITIES: {
+    postgresql: {
+        caseInsensitiveMode: true;
+        caseInsensitiveCollation: false;
+    };
+    cockroachdb: {
+        caseInsensitiveMode: true;
+        caseInsensitiveCollation: false;
+    };
+    mysql: {
+        caseInsensitiveMode: false;
+        caseInsensitiveCollation: true;
+    };
+    mariadb: {
+        caseInsensitiveMode: false;
+        caseInsensitiveCollation: true;
+    };
+    sqlite: {
+        caseInsensitiveMode: false;
+        caseInsensitiveCollation: false;
+    };
+    sqlserver: {
+        caseInsensitiveMode: false;
+        caseInsensitiveCollation: true;
+    };
+    mongodb: {
+        caseInsensitiveMode: true;
+        caseInsensitiveCollation: false;
+    };
+    /**
+     * Fallback used when no dialect is configured/detected. Only emits arguments
+     * that are valid on EVERY Prisma-supported database.
+     */
+    universal: {
+        caseInsensitiveMode: false;
+        caseInsensitiveCollation: false;
+    };
+};
+/** Names of the built-in dialects. */
+type Dialect = keyof typeof DIALECT_CAPABILITIES;
+
+/** Options accepted by the {@link QueryBuilder} constructor. */
+interface QueryBuilderOptions<D extends PrismaModelDelegate> {
+    /** Seed `findMany` args, e.g. `{ where: { deletedAt: null } }` (prepended to every `where`). */
+    initialArgs?: FindManyArgsOf<D> | undefined;
+    /**
+     * Per-builder dialect override. When omitted: global `configureQueryBuilder()`
+     * config → registered auto-detector → `'universal'` (always-valid args).
+     */
+    dialect?: Dialect | undefined;
+    /**
+     * Throw on out-of-range pagination input instead of clamping silently:
+     * limits outside `[1, 1000]`, pages below 1, or a computed `skip` beyond
+     * `MAX_SKIP` (audits F12 / F18). Defaults to clamping.
+     */
+    strictNumbers?: boolean | undefined;
+}
+/** Meta type of {@link QueryBuilder.executeWithMeta} for the given options. */
+type MetaOf<O extends {
+    includeTotal?: boolean;
+}> = O['includeTotal'] extends false ? PaginationMetaNoTotal : PaginationMeta;
+/** Thrown by {@link QueryBuilder.firstOrThrow} when no row matched. */
+declare class NoResultError extends Error {
+    constructor();
+}
+/**
+ * Generic, reusable and fully type-safe query builder for any Prisma model
+ * delegate, on every Prisma version (see ARCHITECTURE.md).
+ *
+ * All option types (`where`, `select`, `include`, `orderBy`, ...) are inferred
+ * structurally from the delegate passed to the constructor — nothing is imported
+ * from Prisma, so no Prisma upgrade can ever break this class.
+ *
+ * The result type of `execute()` is narrowed by `.select()` / `.include()` via a
+ * structural projection engine, mirroring Prisma's own behaviour.
+ *
+ * @typeParam D - The Prisma model delegate, e.g. `typeof prisma.user`.
+ * @typeParam TArgs - Accumulated `findMany` args. Defaults to no projection.
+ *
+ * @example
+ * const result = await new QueryBuilder(prisma.user)
+ *   .search({ searchText, fields: ['email', 'username'] })
+ *   .filter({ role, status })
+ *   .range({ createdAt: { from, to }, 'avatar.size': { from: min, to: max } })
+ *   .sortBy({ sortBy: 'createdAt', sortOrder: 'desc' })
+ *   .paginate({ page: 1, limit: 10 })
+ *   .select({ id: true, email: true })
+ *   .execute();
+ */
+declare class QueryBuilder<D extends PrismaModelDelegate, TArgs = object> {
+    private readonly delegate;
+    private readonly dialect;
+    private readonly strictNumbers;
+    private readonly andConditions;
+    private customArgs;
+    /**
+     * The `initialArgs` seed `where` plus every `.custom({ where })`, AND-merged.
+     * Kept out of `customArgs` so a later `.custom({ where })` merges with the
+     * seed instead of replacing it (audit F2 — the seed carries safety filters).
+     */
+    private customWhere;
+    private orderByArg;
+    private selectArg;
+    private includeArg;
+    private page;
+    private limit;
+    private cursorActive;
+    private cursor;
+    private cursorLimit;
+    private cursorDirection;
+    private cursorField;
+    private cursorStrict;
+    /**
+     * @param delegate - The Prisma delegate to query (e.g. `prisma.user`).
+     * @param options - Optional seed args, a dialect override, or `strictNumbers`.
+     */
+    constructor(delegate: D, options?: QueryBuilderOptions<D>);
+    /**
+     * Case-insensitive `contains` across the provided string fields. No condition
+     * is added when `searchText` is empty or whitespace-only (audit G7).
+     *
+     * Dialect-aware: adds `mode: 'insensitive'` only where Prisma accepts it (see
+     * `caseInsensitiveMode` in `src/dialects/capabilities.ts`); everywhere else
+     * the bare `contains` relies on the database's collation, and where that is
+     * ASCII-only matching stays case-sensitive — Prisma offers no alternative
+     * there.
+     */
+    search(params: {
+        searchText?: string | undefined;
+        fields: WhereKeyOf<D>[];
+    }): this;
+    /**
+     * Adds an equality/operator filter. Accepts a partial Prisma `where` object;
+     * `undefined` values are ignored so optional query params are safe to pass.
+     */
+    filter(filters: FilterInput<D>): this;
+    /**
+     * Adds `gte`/`lte` range conditions. Keys may be dot-paths to reach relations
+     * or nested objects (e.g. `'avatar.size'`). Bounds left `undefined` are
+     * skipped; a field is only added when at least one bound is present.
+     */
+    range(ranges: Record<string, RangeInput>): this;
+    /** Adds an arbitrary, fully-typed Prisma `where` condition. */
+    where(condition: WhereOf<D>): this;
+    /**
+     * Sets `orderBy` from a single key. No-op when `sortBy` is not provided.
+     * Dot paths expand like `.range()` (`'avatar.size'` → `{ avatar: { size } }`,
+     * audit F6). For multi-key or nested relation sorts use {@link orderBy}.
+     */
+    sortBy(params: {
+        sortBy?: OrderKeyOf<D> | (string & {});
+        sortOrder?: SortOrder;
+    }): this;
+    /**
+     * Sets `orderBy` verbatim from the full Prisma shape: arrays for multi-key
+     * sorts, nested relation order objects. `.sortBy()` remains the single-key
+     * convenience — the latest of the two calls wins (audit G1).
+     */
+    orderBy(order: OrderByOf<D>): this;
+    /** Configures `skip`/`take` from a 1-based page number and page size. */
+    paginate(params: {
+        page?: number;
+        limit?: number;
+    }): this;
+    /**
+     * Configures cursor-based ("seek") pagination. Use {@link executeWithCursor}
+     * to run the query and obtain `next`/`prev` cursors.
+     *
+     * - `cursor` is the value of `cursorField` from the edge row of the previous
+     *   page (omit it for the first page). Strings, numbers and Dates are
+     *   accepted; Dates serialize to ISO-8601 in the returned cursors (audit F4).
+     * - `direction` walks `'forward'` (next) or `'backward'` (previous).
+     * - `cursorField` is the unique, sequential column to seek on (default `id`).
+     *   Pair it with a matching {@link sortBy} for stable ordering.
+     * - `strict` spends one extra 1-row probe query to make `hasNextPage` /
+     *   `hasPrevPage` exact instead of optimistic (audit F10).
+     *
+     * Takes precedence over {@link paginate} when both are set.
+     */
+    cursorPaginate(params: {
+        cursor?: string | number | Date | undefined;
+        limit?: number;
+        direction?: CursorDirection;
+        cursorField?: OrderKeyOf<D> | (string & {});
+        strict?: boolean;
+    }): this;
+    /**
+     * Projects fields with Prisma `select`. The result type of `execute()` is
+     * narrowed to exactly the selected shape. Clears any active `.include()`.
+     */
+    select<TSelect extends SelectOf<D>>(select: TSelect): QueryBuilder<D, Omit<TArgs, 'select' | 'include'> & {
+        select: TSelect;
+    }>;
+    /**
+     * Eager-loads relations with Prisma `include`. The result type of `execute()`
+     * is widened with the included relations. Clears any active `.select()`.
+     */
+    include<TInclude extends IncludeOf<D>>(include: TInclude): QueryBuilder<D, Omit<TArgs, 'select' | 'include'> & {
+        include: TInclude;
+    }>;
+    /**
+     * Merges raw `findMany` args, e.g. `cursor`, `distinct` or a custom `where`.
+     * Values that are `undefined` are stripped at any depth, so
+     * `custom({ distinct: undefined })` cannot overwrite an earlier value
+     * (audit F15). A custom `where` is AND-ed with the `initialArgs` seed and any
+     * previous custom `where` — it never replaces them (audit F2). Successive
+     * custom `where`s may nest `{ AND: [...] }` groups; Prisma treats that
+     * identically.
+     */
+    custom(args: FindManyArgsOf<D>): this;
+    /** The fully assembled `findMany` args. Useful for debugging or reuse. */
+    buildArgs(): FindManyArgsOf<D>;
+    /**
+     * Executes the query and returns the rows, typed from `.select()`/`.include()`.
+     *
+     * Tip: for 100% Prisma-native inference you can always run the passthrough
+     * `prisma.user.findMany(qb.buildArgs())` — same args, Prisma's own overloads.
+     */
+    execute(): Promise<FindResultOf<D, TArgs>>;
+    /** Executes the query and returns the first row, or `null` when none matched. */
+    first(): Promise<ApplyProjection<RowElementOf<D>, TArgs> | null>;
+    /** Like {@link first}, but throws {@link NoResultError} when nothing matched. */
+    firstOrThrow(): Promise<ApplyProjection<RowElementOf<D>, TArgs>>;
+    /** Counts rows matching the current filters (ignores pagination/projection). */
+    count(): Promise<number>;
+    /**
+     * Executes the query and returns the rows plus offset pagination metadata.
+     * When no pagination was configured, defaults to page 1, limit 10 so `meta`
+     * always describes the data actually returned. `count` and `findMany` run in
+     * parallel.
+     *
+     * Pass `{ includeTotal: false }` to skip the `COUNT` query entirely — `meta`
+     * then carries `total: null` / `totalPage: null` (audit G3).
+     *
+     * Throws when cursor pagination is configured — offset meta cannot describe a
+     * seek query, and the cursor over-fetch row would leak into `data` (audit F1).
+     * Use {@link executeWithCursor} instead.
+     */
+    executeWithMeta<O extends {
+        includeTotal?: boolean;
+    } = {
+        includeTotal?: boolean;
+    }>(opts?: O): Promise<{
+        meta: MetaOf<O>;
+        data: FindResultOf<D, TArgs>;
+    }>;
+    /**
+     * Executes a cursor-paginated query (see {@link cursorPaginate}) and returns
+     * the page rows plus `next`/`prev` cursors. Rows are always returned in the
+     * configured sort order, regardless of pagination `direction`.
+     *
+     * Throws when a `.select()` projection drops `cursorField` — the page cursors
+     * are derived from that field and would come out as `undefined` (audit F5).
+     */
+    executeWithCursor(): Promise<{
+        meta: CursorMeta;
+        data: FindResultOf<D, TArgs>;
+    }>;
+    /** strictNumbers: out-of-range limits throw instead of clamping (audit F12). */
+    private assertLimit;
+    private assertPage;
+    /** strictNumbers: a computed skip beyond MAX_SKIP throws (audit F18). */
+    private assertSkipCap;
+    /** A projection without the cursor field would derive cursors from `undefined` (audit F5). */
+    private assertCursorFieldProjected;
+    private buildWhere;
+}
+
+/**
+ * Register capabilities for a database - including ones Prisma adds in the
+ * future. No core code changes are ever required to support a new dialect.
+ */
+declare function registerDialect(name: string, capabilities: DialectCapabilities): void;
+/** Set the global default dialect for all builders that do not override it. */
+declare function configureQueryBuilder(options: {
+    dialect?: string | undefined;
+}): void;
+/**
+ * Plug in an auto-detector (best-effort). It must never throw; an undefined
+ * result simply falls through to the built-in detector and then 'universal'.
+ */
+declare function setDialectDetector(detector: () => string | undefined): void;
+/** A dialect name plus the capabilities resolved for it. */
+interface ResolvedDialect {
+    name: string;
+    capabilities: DialectCapabilities;
+}
+/**
+ * Resolve the active dialect per the documented precedence. An unregistered
+ * name resolves to `'universal'` — the reported name never lies about the
+ * capabilities actually applied (audit G8).
+ */
+declare function resolveDialect(explicit?: string | undefined): ResolvedDialect;
+/** Test helper: reset global configuration (registry entries are kept). */
+declare function resetDialectConfig(): void;
+
+/**
+ * Best-effort dialect auto-detection (M2 scope).
+ *
+ * v0 intentionally detects nothing and returns `undefined` → callers fall
+ * through to `'universal'`, which never emits an invalid argument on any
+ * database. Future heuristics (guarded property sniffing of the Prisma client)
+ * must keep the same contract: NEVER throw, NEVER guess wrong loudly — an
+ * unknown dialect must degrade to `'universal'`, not to a wrong guess.
+ *
+ * Users who know their database should prefer explicit configuration:
+ *   configureQueryBuilder({ dialect: 'postgres' })
+ * or per builder:
+ *   new QueryBuilder(prisma.user, { dialect: 'mongodb' })
+ */
+declare function detectDialect(): Dialect | undefined;
+
+export { type ApplyInclude, type ApplyProjection, type ApplySelect, type CursorDirection, type CursorMeta, DIALECT_CAPABILITIES, type Dialect, type DialectCapabilities, type FilterInput, type FindManyArgsOf, type FindResultOf, type IncludeOf, NoResultError, type OrderByOf, type OrderKeyOf, type PaginationMeta, type PaginationMetaNoTotal, type PrismaModelDelegate, QueryBuilder, type QueryBuilderOptions, type RangeBound, type RangeInput, type ResolvedDialect, type RowElementOf, type RowsOf, type SelectOf, type SortOrder, type WhereKeyOf, type WhereOf, configureQueryBuilder, detectDialect, registerDialect, resetDialectConfig, resolveDialect, setDialectDetector };