pqb 0.56.13 → 0.57.1

package/dist/index.mjs

@@ -12837,6 +12837,8 @@ class QueryMethods {
   /**
    * Use `makeHelper` to make a query helper - a function where you can modify the query, and reuse this function across different places.
    *
+   * The idea is similar to {@link modify}, the difference is that `modify` is per query, and `makeHelper` can be reused.
+   *
    * ```ts
    * const defaultAuthorSelect = db.author.makeHelper((q) => {
    *   return q.select('firstName', 'lastName');
@@ -12897,7 +12899,7 @@ class QueryMethods {
     };
   }
   /**
-   * `modify` allows modifying the query with helpers defined with {@link makeHelper}:
+   * `useHelper` allows to use {@link makeHelper} in different queries:
    *
    * ```ts
    * const helper = db.table.makeHelper((q) => {
@@ -12905,9 +12907,9 @@ class QueryMethods {
    *   return q.select('name').where({ active: true }).order({ createdAt: 'DESC' });
    * });
    *
-   * const record = await db.table.select('id').modify(helper).find(1);
+   * const record = await db.table.select('id').useHelper(helper).find(1);
    *
-   * record.id; // id was selected before `modify`
+   * record.id; // id was selected before `useHelper`
    * record.name; // name was selected by the function
    * ```
    *
@@ -12915,7 +12917,7 @@ class QueryMethods {
    * Use this sparingly as it complicates dealing with the result.
    *
    * ```ts
-   * const helper = db.table((q) => {
+   * const helper = db.table.makeHelper((q) => {
    *   if (Math.random() > 0.5) {
    *     return q.select('one');
    *   } else {
@@ -12923,7 +12925,7 @@ class QueryMethods {
    *   }
    * });
    *
-   * const record = await db.table.modify(helper).find(1);
+   * const record = await db.table.useHelper(helper).find(1);
    *
    * // TS error: we don't know for sure if the `one` was selected.
    * record.one;
@@ -12943,18 +12945,42 @@ class QueryMethods {
    *   return q.select(select);
    * });
    *
-   * const record = await db.table.modify(helper, 'id').find(1);
+   * const record = await db.table.useHelper(helper, 'id').find(1);
    * // record has type { id: number } | { name: string }
    * if ('id' in record) {
    *   record.id;
    * }
    * ```
    *
-   * @param fn - function to modify the query with. The result type will be merged with the main query as if the `merge` method was used.
+   * @param fn - function to useHelper the query with. The result type will be merged with the main query as if the `merge` method was used.
    */
-  modify(fn, ...args) {
+  useHelper(fn, ...args) {
     return fn(this, ...args);
   }
+  /**
+   * `modify` is useful when you'd like to modify the query based on some condition.
+   *
+   * ```ts
+   * // parameters coming from outside
+   * const selectOneOrAnother = true;
+   * const filterBySomething = true;
+   *
+   * type ResultType =
+   *   | { id: number; one: string }[]
+   *   | { id: number; another: string }[];
+   * const result = await db.table
+   *   .select('id')
+   *   // conditional select results in a union type
+   *   .modify((q) => (includeName ? q.select('one') : q.select('another')))
+   *   // can use any query methods in modify
+   *   .modify((q) => (filterBySomething ? q.where({ something: true }) : q));
+   * ```
+   *
+   * @param fn - accepts the current query as a parameters. Anything returned by the function will be the return type of the query.
+   */
+  modify(fn) {
+    return fn(this);
+  }
   /**
    * Narrows a part of the query output type.
    * Use with caution, type-safety isn't guaranteed with it.