pqb 0.56.13 → 0.57.0

package/dist/index.d.ts

@@ -1808,9 +1808,9 @@ type WhereArg<T extends PickQueryMetaRelations> = {
  * ```
  */
 type WhereQueryBuilder<T extends PickQueryRelations> = EmptyObject extends T['relations'] ? {
-    [K in keyof T]: K extends keyof Where | keyof ExpressionMethods | 'table' | 'get' | 'columnTypes' | 'meta' | 'relations' | 'modify' | 'result' | 'returnType' | 'withData' | 'windows' | 'then' ? T[K] : never;
+    [K in keyof T]: K extends keyof Where | keyof ExpressionMethods | 'table' | 'get' | 'columnTypes' | 'meta' | 'relations' | 'useHelper' | 'modify' | 'result' | 'returnType' | 'withData' | 'windows' | 'then' ? T[K] : never;
 } : {
-    [K in keyof T['relations'] | keyof T]: K extends keyof T['relations'] ? T['relations'][K]['query'] : K extends keyof T & (keyof Where | keyof ExpressionMethods | 'table' | 'get' | 'columnTypes' | 'meta' | 'relations' | 'modify' | 'result' | 'returnType' | 'withData' | 'windows' | 'then') ? T[K] : never;
+    [K in keyof T['relations'] | keyof T]: K extends keyof T['relations'] ? T['relations'][K]['query'] : K extends keyof T & (keyof Where | keyof ExpressionMethods | 'table' | 'get' | 'columnTypes' | 'meta' | 'relations' | 'useHelper' | 'modify' | 'result' | 'returnType' | 'withData' | 'windows' | 'then') ? T[K] : never;
 };
 type WhereArgs<T extends PickQueryMetaRelations> = WhereArg<T>[];
 type WhereNotArgs<T extends PickQueryMetaRelations> = [WhereArg<T>];
@@ -7820,6 +7820,8 @@ declare class QueryMethods<ColumnTypes> {
     /**
      * 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');
@@ -7870,7 +7872,7 @@ declare class QueryMethods<ColumnTypes> {
      */
     makeHelper<T extends PickQueryMetaShape, Args extends unknown[], Result>(this: T, fn: (q: T, ...args: Args) => Result): QueryHelper<T, Args, Result>;
     /**
-     * `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) => {
@@ -7878,9 +7880,9 @@ declare class QueryMethods<ColumnTypes> {
      *   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
      * ```
      *
@@ -7888,7 +7890,7 @@ declare class QueryMethods<ColumnTypes> {
      * 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 {
@@ -7896,7 +7898,7 @@ declare class QueryMethods<ColumnTypes> {
      *   }
      * });
      *
-     * 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;
@@ -7916,16 +7918,38 @@ declare class QueryMethods<ColumnTypes> {
      *   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.
+     */
+    useHelper<T extends PickQueryTableMetaResultReturnTypeWithDataWindowsThen, Fn extends IsQueryHelperForTable<T['table']>>(this: T, fn: Fn, ...args: Fn['args']): Fn['result'] extends PickQueryMetaResultReturnTypeWithDataWindowsThen ? MergeQuery<T, Fn['result']> : Fn['result'];
+    /**
+     * `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<T extends PickQueryTableMetaResultReturnTypeWithDataWindowsThen, Fn extends IsQueryHelperForTable<T['table']>>(this: T, fn: Fn, ...args: Fn['args']): Fn['result'] extends PickQueryMetaResultReturnTypeWithDataWindowsThen ? MergeQuery<T, Fn['result']> : Fn['result'];
+    modify<T, R>(this: T, fn: (q: T) => R): R;
     /**
      * Narrows a part of the query output type.
      * Use with caution, type-safety isn't guaranteed with it.

package/dist/index.js

@@ -12839,6 +12839,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');
@@ -12899,7 +12901,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) => {
@@ -12907,9 +12909,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
    * ```
    *
@@ -12917,7 +12919,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 {
@@ -12925,7 +12927,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;
@@ -12945,18 +12947,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.