query-builder-prisma 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,636 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DIALECT_CAPABILITIES: () => DIALECT_CAPABILITIES,
+  NoResultError: () => NoResultError,
+  QueryBuilder: () => QueryBuilder,
+  configureQueryBuilder: () => configureQueryBuilder,
+  detectDialect: () => detectDialect,
+  registerDialect: () => registerDialect,
+  resetDialectConfig: () => resetDialectConfig,
+  resolveDialect: () => resolveDialect,
+  setDialectDetector: () => setDialectDetector
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/conditions.ts
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function isSafeKey(key) {
+  return !DANGEROUS_KEYS.has(key);
+}
+function stripUndefined(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== void 0 && isSafeKey(key)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function deepStripUndefined(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === void 0 || !isSafeKey(key)) {
+      continue;
+    }
+    result[key] = isDeepStrippable(value) ? deepStripUndefined(value) : Array.isArray(value) ? value.map((item) => isDeepStrippable(item) ? deepStripUndefined(item) : item) : value;
+  }
+  return result;
+}
+function isDeepStrippable(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function expandDotPath(path, leaf) {
+  const keys = path.split(".").filter((key) => key.length > 0);
+  if (keys.length === 0 || keys.some((key) => !isSafeKey(key))) {
+    return {};
+  }
+  let current = leaf;
+  for (let i = keys.length - 1; i >= 0; i--) {
+    const key = keys[i];
+    if (key === void 0) {
+      continue;
+    }
+    current = { [key]: current };
+  }
+  return current;
+}
+function combineAnd(conditions, customWhere) {
+  const all = isPlainObject(customWhere) ? [customWhere, ...conditions] : [...conditions];
+  if (all.length === 0) {
+    return void 0;
+  }
+  if (all.length === 1) {
+    return all[0];
+  }
+  return { AND: all };
+}
+
+// src/core/pagination.ts
+var DEFAULT_PAGE_SIZE = 10;
+var MAX_PAGE_SIZE = 1e3;
+var MAX_SKIP = 1e5;
+function clampLimit(limit) {
+  if (!Number.isFinite(limit)) {
+    return DEFAULT_PAGE_SIZE;
+  }
+  return Math.min(Math.max(1, Math.floor(limit)), MAX_PAGE_SIZE);
+}
+function clampPage(page) {
+  if (!Number.isFinite(page)) {
+    return 1;
+  }
+  return Math.max(1, Math.floor(page));
+}
+function toOffsetArgs(page, limit) {
+  const safePage = clampPage(page);
+  const safeLimit = clampLimit(limit);
+  const skip = Math.min((safePage - 1) * safeLimit, MAX_SKIP);
+  return { take: safeLimit, skip, page: safePage, limit: safeLimit };
+}
+function buildPaginationMeta(total, page, limit) {
+  const safeLimit = clampLimit(limit);
+  const safePage = clampPage(page);
+  return {
+    page: safePage,
+    limit: safeLimit,
+    total,
+    totalPage: Math.ceil(total / safeLimit)
+  };
+}
+function serializeCursorValue(value) {
+  return value instanceof Date ? value.toISOString() : String(value);
+}
+function toCursorArgs(plan) {
+  const sign = plan.direction === "backward" ? -1 : 1;
+  const take = sign * (clampLimit(plan.limit ?? DEFAULT_PAGE_SIZE) + 1);
+  if (plan.cursor === void 0) {
+    return { take };
+  }
+  return {
+    take,
+    cursor: { [plan.cursorField]: plan.cursor },
+    skip: 1
+  };
+}
+function buildCursorPage(rows, info) {
+  const { limit, direction, cursorField, hadCursor, exactFlags } = info;
+  const safeLimit = clampLimit(limit);
+  const hasExtra = rows.length > safeLimit;
+  const pageRows = hasExtra ? rows.slice(0, safeLimit) : rows;
+  const ordered = direction === "backward" ? [...pageRows].reverse() : pageRows;
+  const hasRows = rows.length > 0;
+  const hasNextPage = exactFlags?.hasNextPage ?? (direction === "forward" ? hasExtra : hadCursor && hasRows);
+  const hasPrevPage = exactFlags?.hasPrevPage ?? (direction === "backward" ? hasExtra : hadCursor && hasRows);
+  const first = ordered[0];
+  const last = ordered[ordered.length - 1];
+  return {
+    data: ordered,
+    meta: {
+      limit: safeLimit,
+      nextCursor: hasNextPage && last !== void 0 ? serializeCursorValue(last[cursorField]) : null,
+      prevCursor: hasPrevPage && first !== void 0 ? serializeCursorValue(first[cursorField]) : null,
+      hasNextPage,
+      hasPrevPage
+    }
+  };
+}
+
+// src/dialects/capabilities.ts
+var 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 }
+};
+
+// src/dialects/detect.ts
+function detectDialect() {
+  return void 0;
+}
+
+// src/dialects/registry.ts
+var STATE_KEY = /* @__PURE__ */ Symbol.for("query-builder-prisma.dialect-state");
+function state() {
+  const host = globalThis;
+  return host[STATE_KEY] ??= {
+    registry: new Map(Object.entries(DIALECT_CAPABILITIES)),
+    globalDialect: void 0,
+    detector: void 0
+  };
+}
+function registerDialect(name, capabilities) {
+  state().registry.set(name, capabilities);
+}
+function configureQueryBuilder(options) {
+  state().globalDialect = options.dialect;
+}
+function setDialectDetector(detector) {
+  state().detector = detector;
+}
+function resolveDialect(explicit) {
+  const s = state();
+  const requested = explicit ?? s.globalDialect ?? s.detector?.() ?? detectDialect() ?? "universal";
+  const capabilities = s.registry.get(requested);
+  return capabilities ? { name: requested, capabilities } : { name: "universal", capabilities: DIALECT_CAPABILITIES.universal };
+}
+function resetDialectConfig() {
+  const s = state();
+  s.globalDialect = void 0;
+  s.detector = void 0;
+}
+
+// src/core/query-builder.ts
+var NoResultError = class extends Error {
+  constructor() {
+    super("Query returned no rows");
+    this.name = "NoResultError";
+  }
+};
+var QueryBuilder = class {
+  delegate;
+  dialect;
+  strictNumbers;
+  andConditions = [];
+  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).
+   */
+  customWhere;
+  orderByArg;
+  selectArg;
+  includeArg;
+  page;
+  limit;
+  cursorActive = false;
+  cursor;
+  cursorLimit;
+  cursorDirection = "forward";
+  cursorField = "id";
+  cursorStrict = false;
+  /**
+   * @param delegate - The Prisma delegate to query (e.g. `prisma.user`).
+   * @param options - Optional seed args, a dialect override, or `strictNumbers`.
+   */
+  constructor(delegate, options) {
+    this.delegate = delegate;
+    this.dialect = options?.dialect;
+    this.strictNumbers = options?.strictNumbers ?? false;
+    if (options?.initialArgs) {
+      const { where, ...rest } = options.initialArgs;
+      this.customArgs = { ...rest };
+      this.customWhere = where;
+    }
+  }
+  /**
+   * 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) {
+    const text = params.searchText?.trim();
+    const fields = params.fields;
+    if (text && fields.length > 0) {
+      const { capabilities } = resolveDialect(this.dialect);
+      this.andConditions.push({
+        OR: fields.map((field) => {
+          const match = { contains: text };
+          if (capabilities.caseInsensitiveMode) {
+            match.mode = "insensitive";
+          }
+          return { [field]: match };
+        })
+      });
+    }
+    return 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) {
+    const cleaned = stripUndefined(filters);
+    if (Object.keys(cleaned).length > 0) {
+      this.andConditions.push(cleaned);
+    }
+    return 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) {
+    for (const [path, bound] of Object.entries(ranges)) {
+      const condition = {};
+      if (bound.from !== void 0) {
+        condition.gte = bound.from;
+      }
+      if (bound.to !== void 0) {
+        condition.lte = bound.to;
+      }
+      if (Object.keys(condition).length > 0) {
+        const expanded = expandDotPath(path, condition);
+        if (Object.keys(expanded).length > 0) {
+          this.andConditions.push(expanded);
+        }
+      }
+    }
+    return this;
+  }
+  /** Adds an arbitrary, fully-typed Prisma `where` condition. */
+  where(condition) {
+    const cleaned = stripUndefined(condition);
+    if (Object.keys(cleaned).length > 0) {
+      this.andConditions.push(cleaned);
+    }
+    return 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) {
+    const { sortBy, sortOrder = "desc" } = params;
+    if (sortBy) {
+      const expanded = expandDotPath(sortBy, sortOrder);
+      if (Object.keys(expanded).length > 0) {
+        this.orderByArg = expanded;
+      }
+    }
+    return 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) {
+    this.orderByArg = order;
+    return this;
+  }
+  /** Configures `skip`/`take` from a 1-based page number and page size. */
+  paginate(params) {
+    this.assertPage(params.page);
+    this.assertLimit(params.limit);
+    this.page = params.page ?? 1;
+    this.limit = params.limit ?? DEFAULT_PAGE_SIZE;
+    return 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) {
+    this.assertLimit(params.limit);
+    this.cursorActive = true;
+    this.cursor = params.cursor;
+    this.cursorLimit = params.limit;
+    this.cursorDirection = params.direction ?? "forward";
+    this.cursorField = params.cursorField ?? "id";
+    this.cursorStrict = params.strict ?? false;
+    return this;
+  }
+  /**
+   * Projects fields with Prisma `select`. The result type of `execute()` is
+   * narrowed to exactly the selected shape. Clears any active `.include()`.
+   */
+  select(select) {
+    this.selectArg = select;
+    this.includeArg = void 0;
+    return this;
+  }
+  /**
+   * Eager-loads relations with Prisma `include`. The result type of `execute()`
+   * is widened with the included relations. Clears any active `.select()`.
+   */
+  include(include) {
+    this.includeArg = include;
+    this.selectArg = void 0;
+    return this;
+  }
+  /**
+   * 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) {
+    const { where, ...rest } = args;
+    this.customArgs = { ...this.customArgs, ...deepStripUndefined(rest) };
+    if (where !== void 0) {
+      const cleaned = isPlainObject(where) ? deepStripUndefined(where) : where;
+      const hasKeys = !isPlainObject(cleaned) || Object.keys(cleaned).length > 0;
+      if (hasKeys) {
+        this.customWhere = combineAnd([cleaned], this.customWhere);
+      }
+    }
+    return this;
+  }
+  /** The fully assembled `findMany` args. Useful for debugging or reuse. */
+  buildArgs() {
+    const args = { ...this.customArgs };
+    const where = this.buildWhere();
+    if (where) {
+      args.where = where;
+    }
+    if (this.orderByArg) {
+      args.orderBy = this.orderByArg;
+    }
+    if (this.selectArg) {
+      args.select = this.selectArg;
+    }
+    if (this.includeArg) {
+      args.include = this.includeArg;
+    }
+    if (this.cursorActive) {
+      const cursorArgs = toCursorArgs({
+        cursor: this.cursor,
+        limit: this.cursorLimit,
+        direction: this.cursorDirection,
+        cursorField: this.cursorField
+      });
+      args.take = cursorArgs.take;
+      if (cursorArgs.cursor) {
+        args.cursor = cursorArgs.cursor;
+      }
+      if (cursorArgs.skip !== void 0) {
+        args.skip = cursorArgs.skip;
+      }
+    } else if (this.limit !== void 0) {
+      const page = this.page ?? 1;
+      this.assertSkipCap(page, this.limit);
+      const offset = toOffsetArgs(page, this.limit);
+      args.take = offset.take;
+      args.skip = offset.skip;
+    }
+    return args;
+  }
+  /**
+   * 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.
+   */
+  async execute() {
+    const findMany = this.delegate.findMany.bind(this.delegate);
+    const data = await findMany(this.buildArgs());
+    return data;
+  }
+  /** Executes the query and returns the first row, or `null` when none matched. */
+  async first() {
+    const args = { ...this.buildArgs() };
+    args.take = 1;
+    delete args.skip;
+    delete args.cursor;
+    const findMany = this.delegate.findMany.bind(this.delegate);
+    const rows = await findMany(args);
+    const row = rows[0];
+    return row ?? null;
+  }
+  /** Like {@link first}, but throws {@link NoResultError} when nothing matched. */
+  async firstOrThrow() {
+    const row = await this.first();
+    if (row === null) {
+      throw new NoResultError();
+    }
+    return row;
+  }
+  /** Counts rows matching the current filters (ignores pagination/projection). */
+  async count() {
+    const where = this.buildWhere();
+    const countFn = this.delegate.count.bind(this.delegate);
+    return countFn(where ? { where } : {});
+  }
+  /**
+   * 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.
+   */
+  async executeWithMeta(opts) {
+    if (this.cursorActive) {
+      throw new Error(
+        "executeWithMeta() is offset-mode only: this builder has cursor pagination configured via cursorPaginate(). Use executeWithCursor() instead."
+      );
+    }
+    if (this.limit === void 0) {
+      this.paginate({ page: 1, limit: DEFAULT_PAGE_SIZE });
+    }
+    this.assertSkipCap(this.page ?? 1, this.limit ?? DEFAULT_PAGE_SIZE);
+    const offset = toOffsetArgs(this.page ?? 1, this.limit ?? DEFAULT_PAGE_SIZE);
+    if (opts?.includeTotal === false) {
+      const data2 = await this.execute();
+      return {
+        meta: { page: offset.page, limit: offset.limit, total: null, totalPage: null },
+        data: data2
+      };
+    }
+    const [total, data] = await Promise.all([this.count(), this.execute()]);
+    return {
+      meta: buildPaginationMeta(total, offset.page, offset.limit),
+      data
+    };
+  }
+  /**
+   * 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).
+   */
+  async executeWithCursor() {
+    if (!this.cursorActive) {
+      this.cursorPaginate({});
+    }
+    this.assertCursorFieldProjected();
+    const limit = this.cursorLimit ?? DEFAULT_PAGE_SIZE;
+    const hadCursor = this.cursor !== void 0;
+    const findMany = this.delegate.findMany.bind(this.delegate);
+    const rows = await findMany(this.buildArgs());
+    let exactFlags;
+    if (this.cursorStrict && hadCursor) {
+      const probeArgs = {
+        take: this.cursorDirection === "forward" ? -1 : 1,
+        cursor: { [this.cursorField]: this.cursor },
+        skip: 1
+      };
+      const where = this.buildWhere();
+      if (where) {
+        probeArgs.where = where;
+      }
+      if (this.orderByArg) {
+        probeArgs.orderBy = this.orderByArg;
+      }
+      const probe = await findMany(probeArgs);
+      const hasEdgeRow = probe.length > 0;
+      exactFlags = this.cursorDirection === "forward" ? { hasPrevPage: hasEdgeRow } : { hasNextPage: hasEdgeRow };
+    }
+    const { data, meta } = buildCursorPage(rows, {
+      limit,
+      direction: this.cursorDirection,
+      cursorField: this.cursorField,
+      hadCursor,
+      exactFlags
+    });
+    return { meta, data };
+  }
+  /** strictNumbers: out-of-range limits throw instead of clamping (audit F12). */
+  assertLimit(limit) {
+    if (!this.strictNumbers || limit === void 0) {
+      return;
+    }
+    if (!Number.isFinite(limit) || limit < 1 || limit > MAX_PAGE_SIZE) {
+      throw new Error(`strictNumbers: limit ${String(limit)} is outside [1, ${MAX_PAGE_SIZE}].`);
+    }
+  }
+  assertPage(page) {
+    if (!this.strictNumbers || page === void 0) {
+      return;
+    }
+    if (!Number.isFinite(page) || page < 1) {
+      throw new Error(`strictNumbers: page ${String(page)} must be a finite number >= 1.`);
+    }
+  }
+  /** strictNumbers: a computed skip beyond MAX_SKIP throws (audit F18). */
+  assertSkipCap(page, limit) {
+    if (!this.strictNumbers) {
+      return;
+    }
+    const skip = (clampPage(page) - 1) * clampLimit(limit);
+    if (skip > MAX_SKIP) {
+      throw new Error(
+        `strictNumbers: computed skip ${String(skip)} exceeds the ${String(MAX_SKIP)} cap \u2014 use cursor pagination for deep pages.`
+      );
+    }
+  }
+  /** A projection without the cursor field would derive cursors from `undefined` (audit F5). */
+  assertCursorFieldProjected() {
+    const select = this.selectArg ?? this.customArgs.select;
+    if (select && !select[this.cursorField]) {
+      throw new Error(
+        `executeWithCursor(): the projection drops cursorField "${this.cursorField}", so page cursors would be built from undefined. Keep the field in .select() or remove the projection.`
+      );
+    }
+  }
+  buildWhere() {
+    return combineAnd(this.andConditions, this.customWhere);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DIALECT_CAPABILITIES,
+  NoResultError,
+  QueryBuilder,
+  configureQueryBuilder,
+  detectDialect,
+  registerDialect,
+  resetDialectConfig,
+  resolveDialect,
+  setDialectDetector
+});
+//# sourceMappingURL=index.cjs.map