pqb 0.17.1 → 0.17.2

package/dist/index.d.ts

@@ -2848,12 +2848,12 @@ declare abstract class WhereQueryBase extends QueryBase {
 type WithSelectable<T extends QueryBase, W extends keyof T['withData']> = T['withData'][W] extends WithDataItem ? StringKey<keyof T['withData'][W]['shape']> | `${T['withData'][W]['table']}.${StringKey<keyof T['withData'][W]['shape']>}` : never;
 /**
  * The first argument of all `join` and `joinLateral` methods.
- * See argument of {@link Join.join}.
+ * See argument of {@link join}.
  */
 type JoinFirstArg<T extends QueryBase> = Query | keyof T['relations'] | keyof T['withData'] | ((q: T['relations']) => Query);
 /**
  * Arguments of `join` methods (not `joinLateral`).
- * See {@link Join.join}
+ * See {@link join}
  */
 type JoinArgs<T extends QueryBase, Arg extends JoinFirstArg<T>> = Arg extends Query ? JoinQueryArgs<T, Arg> : Arg extends keyof T['relations'] ? EmptyTuple : Arg extends keyof T['withData'] ? JoinWithArgs<T, Arg> : never;
 /**
@@ -3014,29 +3014,555 @@ type JoinCallback<T extends QueryBase, Arg extends JoinFirstArg<T>> = (q: OnQuer
 type JoinLateralCallback<T extends QueryBase, Arg extends JoinFirstArg<T>, R extends QueryBase, Q extends QueryBase = JoinArgToQuery<T, Arg>> = (q: Q & OnQueryBuilder<T, Q>) => R;
 declare class Join {
     /**
-     * TODO: write docs
+     * ## Select relation
      *
-     * @param arg - can be a query object, a name of a relation, a name of `with` table, or a callback to join a relation
-     * @param args - arguments depend on the first argument, it can be object with columns, list of columns, `true` literal.
+     * Before joining a table, consider if selecting a relation is enough for your case:
+     *
+     * ```ts
+     * // select users with profiles
+     * // result type is Array<{ name: string, profile: Profile }>
+     * await db.user.select('name', {
+     *   profile: (q) => q.profile,
+     * });
+     *
+     * // select posts with counts of comments, order by comments count
+     * // result type is Array<Post & { commentsCount: number }>
+     * await db.post
+     *   .select('*', {
+     *     commentsCount: (q) => q.comments.count(),
+     *   })
+     *   .order({
+     *     commentsCount: 'DESC',
+     *   });
+     *
+     * // select authors with array of their book titles
+     * // result type is Array<Author & { books: string[] }>
+     * await db.author.select('*', {
+     *   books: (q) => q.books.pluck('title'),
+     * });
+     * ```
+     *
+     * Internally, such selects will use `LEFT JOIN LATERAL` to join a relation.
+     * If you're loading users with profiles (one-to-one relation), and some users don't have a profile, `profile` property will have `NULL` for such users.
+     * If you want to load only users that have profiles, and filter out the rest, add `.join()` method to the relation without arguments:
+     *
+     * ```ts
+     * // load only users who have a profile
+     * await db.user.select('*', {
+     *   profile: (q) => q.profile.join(),
+     * });
+     *
+     * // load only users who have a specific profile
+     * await db.user.select('*', {
+     *   profile: (q) => q.profile.join().where({ age: { gt: 20 } }),
+     * });
+     * ```
+     *
+     * You can also use this `.join()` method on the one-to-many relations, and records with empty array will be filtered out:
+     *
+     * ```ts
+     * // posts that have no tags won't be loaded
+     * // result type is Array<Post & { tags: Tag[] }>
+     * db.post.select('*', {
+     *   tags: (q) => q.tags.join(),
+     * });
+     * ```
+     *
+     * # Joins
+     *
+     * `join` methods allows to join other tables, relations by name, [with](/guide/advanced-queries#with) statements, sub queries.
+     *
+     * All the `join` methods accept the same arguments, but returning type is different because with `join` it's guaranteed to load joined table, and with `leftJoin` the joined table columns may be `NULL` when no matching record was found.
+     *
+     * For the following examples, imagine we have a `User` table with `id` and `name`, and `Message` table with `id`, `text`, messages belongs to user via `userId` column:
+     *
+     * ```ts
+     * export class UserTable extends BaseTable {
+     *   readonly table = 'user';
+     *   columns = this.setColumns((t) => ({
+     *     id: t.identity().primaryKey(),
+     *     name: t.text(),
+     *   }));
+     *
+     *   relations = {
+     *     messages: this.hasMany(() => MessageTable, {
+     *       primaryKey: 'id',
+     *       foreignKey: 'userId',
+     *     }),
+     *   };
+     * }
+     *
+     * export class MessageTable extends BaseTable {
+     *   readonly table = 'message';
+     *   columns = this.setColumns((t) => ({
+     *     id: t.identity().primaryKey(),
+     *     text: t.text(),
+     *     ...t.timestamps(),
+     *   }));
+     *
+     *   relations = {
+     *     user: this.belongsTo(() => UserTable, {
+     *       primaryKey: 'id',
+     *       foreignKey: 'userId',
+     *     }),
+     *   };
+     * }
+     * ```
+     *
+     * ## join
+     *
+     * `join` is a method for SQL `JOIN`, which is equivalent to `INNER JOIN`, `LEFT INNERT JOIN`.
+     *
+     * When no matching record is found, it will skip records of the main table.
+     *
+     * ### join relation
+     *
+     * When relations are defined between the tables, you can join them by a relation name.
+     * Joined table can be references from `where` and `select` by a relation name.
+     *
+     * ```ts
+     * const result = await db.user
+     *   .join('messages')
+     *   // after joining a table, we can use it in `where` conditions:
+     *   .where({ 'messages.text': { startsWith: 'Hi' } })
+     *   .select(
+     *     'name', // name is User column, table name may be omitted
+     *     'messages.text', // text is the Message column, and the table name is required
+     *   );
+     *
+     * // result has the following type:
+     * const ok: { name: string; text: string }[] = result;
+     * ```
+     *
+     * The first argument can also be a callback, where instead of relation name as a string we're picking it as a property of `q`.
+     * In such a way, we can alias the relation with `as`, add `where` conditions, use other query methods.
+     *
+     * ```ts
+     * const result = await db.user.join((q) =>
+     *   q.messages.as('m').where({ text: 'some text' }),
+     * );
+     * ```
+     *
+     * Optionally, you can pass a second callback argument, it makes `on` and `orOn` methods available.
+     *
+     * But remember that when joining a relation, the needed `ON` conditions are already handled automatically.
+     *
+     * ```ts
+     * const result = await db.user.join(
+     *   (q) => q.messages.as('m'),
+     *   (q) =>
+     *     q
+     *       .on('text', 'name') // additionally, match message with user name
+     *       .where({ text: 'some text' }), // you can add `where` in a second callback as well.
+     * );
+     * ```
+     *
+     * ### Selecting full joined records
+     *
+     * `select` supports selecting a full record of a previously joined table by passing a table name with `.*` at the end:
+     *
+     * ```ts
+     * const result = await db.book.join('author').select('title', {
+     *   author: 'author.*',
+     * });
+     *
+     * // result has the following type:
+     * const ok: {
+     *   // title of the book
+     *   title: string;
+     *   // a full author record is included:
+     *   author: { id: number; name: string; updatedAt: Date; createdAt: Date };
+     * }[] = result;
+     * ```
+     *
+     * It works fine for `1:1` (`belongsTo`, `hasOne`) relations, but it may have an unexpected result for `1:M` or `M:M` (`hasMany`, `hasAndBelongsToMany`) relations.
+     * For any kind of relation, it results in one main table record with data of exactly one joined table record, i.e. when selecting in this way, the records **won't** be collected into arrays.
+     *
+     * ```ts
+     * const result = await db.user
+     *   .join('messages')
+     *   .where({ 'messages.text': { startsWith: 'Hi' } })
+     *   .select('name', { messages: 'messages.*' });
+     *
+     * // result has the following type:
+     * const ok: {
+     *   name: string;
+     *   // full message is included:
+     *   messages: { id: number; text: string; updatedAt: Date; createdAt: Date };
+     * }[] = result;
+     * ```
+     *
+     * Because it's a one-to-many relation, one user has many messages, the user data will be duplicated for different messages data:
+     *
+     * | name   | msg                            |
+     * | ------ | ------------------------------ |
+     * | user 1 | `{ id: 1, text: 'message 1' }` |
+     * | user 1 | `{ id: 2, text: 'message 2' }` |
+     * | user 1 | `{ id: 3, text: 'message 3' }` |
+     *
+     * ### join table
+     *
+     * If relation wasn't defined, provide a `db.table` instance and specify columns for the join.
+     * Joined table can be references from `where` and `select` by a table name.
+     *
+     * ```ts
+     * // Join message where userId = id:
+     * db.user
+     *   .join(db.message, 'userId', 'id')
+     *   .where({ 'message.text': { startsWith: 'Hi' } })
+     *   .select('name', 'message.text');
+     * ```
+     *
+     * Columns in the join list may be prefixed with table names for clarity:
+     *
+     * ```ts
+     * db.user.join(db.message, 'message.userId', 'user.id');
+     * ```
+     *
+     * Joined table can have an alias for referencing it further:
+     *
+     * ```ts
+     * db.user
+     *   .join(db.message.as('m'), 'message.userId', 'user.id')
+     *   .where({ 'm.text': { startsWith: 'Hi' } })
+     *   .select('name', 'm.text');
+     * ```
+     *
+     * Joined table can be selected as an object as well as the relation join above:
+     *
+     * ```ts
+     * const result = await db.user
+     *   .join(db.message.as('m'), 'message.userId', 'user.id')
+     *   .where({ 'm.text': { startsWith: 'Hi' } })
+     *   .select('name', { msg: 'm.*' });
+     *
+     * // result has the following type:
+     * const ok: {
+     *   name: string;
+     *   // full message is included as msg:
+     *   msg: { id: number; text: string; updatedAt: Date; createdAt: Date };
+     * }[] = result;
+     * ```
+     *
+     * You can provide a custom comparison operator
+     *
+     * ```ts
+     * db.user.join(db.message, 'userId', '!=', 'id');
+     * ```
+     *
+     * Join can accept raw SQL for the `ON` part of join:
+     *
+     * ```ts
+     * db.user.join(
+     *   db.message,
+     *   db.user.sql`lower("message"."text") = lower("user"."name")`,
+     * );
+     * ```
+     *
+     * Join can accept raw SQL instead of columns:
+     *
+     * ```ts
+     * db.user.join(
+     *   db.message,
+     *   db.user.sql`lower("message"."text")`,
+     *   db.user.sql`lower("user"."name")`,
+     * );
+     *
+     * // with operator:
+     * db.user.join(
+     *   db.message,
+     *   db.user.sql`lower("message"."text")`,
+     *   '!=',
+     *   db.user.sql`lower("user"."name")`,
+     * );
+     * ```
+     *
+     * To join based on multiple columns, you can provide an object where keys are joining table columns, and values are main table columns or a raw SQL:
+     *
+     * ```ts
+     * db.user.join(db.message, {
+     *   userId: 'id',
+     *
+     *   // with table names:
+     *   'message.userId': 'user.id',
+     *
+     *   // value can be a raw SQL expression:
+     *   text: db.user.sql`lower("user"."name")`,
+     * });
+     * ```
+     *
+     * Join all records without conditions by providing `true`:
+     *
+     * ```ts
+     * db.user.join(db.message, true);
+     * ```
+     *
+     * Join methods can accept a callback with a special query builder that has `on` and `orOn` methods for handling advanced cases:
+     *
+     * ```ts
+     * db.user.join(
+     *   db.message,
+     *   (q) =>
+     *     q
+     *       // left column is the db.message column, right column is the db.user column
+     *       .on('userId', 'id')
+     *       // table names can be provided:
+     *       .on('message.userId', 'user.id')
+     *       // operator can be specified:
+     *       .on('userId', '!=', 'id')
+     *       // operator can be specified with table names as well:
+     *       .on('message.userId', '!=', 'user.id')
+     *       // `.orOn` takes the same arguments as `.on` and acts like `.or`:
+     *       .on('userId', 'id') // where message.userId = user.id
+     *       .orOn('text', 'name'), // or message.text = user.name
+     * );
+     * ```
+     *
+     * Join query builder supports all `where` methods: `.where`, `.whereIn`, `.whereExists`, and all `.or`, `.not`, and `.orNot` forms.
+     *
+     * Column names in the where conditions are applied for the joined table, but you can specify a table name to add a condition for the main table.
+     *
+     * ```ts
+     * db.user.join(db.message, (q) =>
+     *   q
+     *     .on('userId', 'id')
+     *     .where({
+     *       // not prefixed column name is for joined table:
+     *       text: { startsWith: 'hello' },
+     *       // specify a table name to set condition on the main table:
+     *       'user.name': 'Bob',
+     *     })
+     *     // id is a column of a joined table Message
+     *     .whereIn('id', [1, 2, 3])
+     *     // condition for id of a user
+     *     .whereIn('user.id', [4, 5, 6]),
+     * );
+     * ```
+     *
+     * The query above will generate the following SQL (simplified):
+     *
+     * ```sql
+     * SELECT * FROM "user"
+     * JOIN "message"
+     *   ON "message"."userId" = "user"."id"
+     *  AND "message"."text" ILIKE 'hello%'
+     *  AND "user"."name" = 'Bob'
+     *  AND "message"."id" IN (1, 2, 3)
+     *  AND "user"."id" IN (4, 5, 6)
+     * ```
+     *
+     * The join argument can be a query with `select`, `where`, and other methods. In such case, it will be handled as a sub query:
+     *
+     * ```ts
+     * db.user.join(
+     *   db.message
+     *     .select('id', 'userId', 'text')
+     *     .where({ text: { startsWith: 'Hi' } })
+     *     .as('t'),
+     *   'userId',
+     *   'id',
+     * );
+     * ```
+     *
+     * It will produce such SQL:
+     *
+     * ```sql
+     * SELECT * FROM "user"
+     * JOIN (
+     *   SELECT "t"."id", "t"."userId", "t"."text"
+     *   FROM "message" AS "t"
+     * ) "t" ON "t"."userId" = "user"."id"
+     * ```
+     *
+     * @param arg - {@link JoinFirstArg}
+     * @param args - {@link JoinArgs}
      */
     join<T extends Query, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): JoinResult<T, Arg, true, true>;
+    /**
+     * A join variant accepting a {@link JoinCallback}, see {@link join} for full info.
+     * @param arg - {@link JoinFirstArg}
+     * @param cb - {@link JoinCallback}
+     */
     join<T extends Query, Arg extends JoinFirstArg<T>, Cb extends JoinCallback<T, Arg>>(this: T, arg: Arg, cb: Cb): JoinResult<T, Arg, true, true, Cb>;
     _join<T extends Query, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): JoinResult<T, Arg, true, true>;
     _join<T extends Query, Arg extends JoinFirstArg<T>, Cb extends JoinCallback<T, Arg>>(this: T, arg: Arg, cb: Cb): JoinResult<T, Arg, true, true, Cb>;
+    /**
+     * `leftJoin` is a method for SQL `LEFT JOIN`, which is equivalent to `OUTER JOIN`, `LEFT OUTER JOIN`.
+     *
+     * When no matching record is found, it will fill joined table columns with `NULL` values in the result rows.
+     *
+     * Works just like `join`, except for result type that may have `null`:
+     *
+     * ```ts
+     * const result = await db.user
+     *   .leftJoin('messages')
+     *   .select('name', 'messages.text');
+     *
+     * // the same query, but joining table explicitly
+     * const result2: typeof result = await db.user
+     *   .leftJoin(db.message, 'userId', 'id')
+     *   .select('name', 'message.text');
+     *
+     * // result has the following type:
+     * const ok: { name: string; text: string | null }[] = result;
+     * ```
+     *
+     * @param arg - {@link JoinFirstArg}
+     * @param args - {@link JoinArgs}
+     */
     leftJoin<T extends Query, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): JoinResult<T, Arg, false, true>;
+    /**
+     * A `leftJoin` variant accepting a {@link JoinCallback}, see {@link join} for full info.
+     * @param arg - {@link JoinFirstArg}
+     * @param cb - {@link JoinCallback}
+     */
     leftJoin<T extends Query, Arg extends JoinFirstArg<T>, Cb extends JoinCallback<T, Arg>>(this: T, arg: Arg, cb: Cb): JoinResult<T, Arg, false, true, Cb>;
     _leftJoin<T extends Query, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): JoinResult<T, Arg, false, true>;
     _leftJoin<T extends Query, Arg extends JoinFirstArg<T>, Cb extends JoinCallback<T, Arg>>(this: T, arg: Arg, cb: Cb): JoinResult<T, Arg, false, true, Cb>;
+    /**
+     * `rightJoin` is a method for SQL `RIGHT JOIN`, which is equivalent to `RIGHT OUTER JOIN`.
+     *
+     * Takes the same arguments as `json`.
+     *
+     * It will load all records from the joining table, and fill the main table columns with `null` when no match is found.
+     *
+     * The columns of the table you're joining to are becoming nullable when using `rightJoin`.
+     *
+     * ```ts
+     * const result = await db.user
+     *   .rightJoin('messages')
+     *   .select('name', 'messages.text');
+     *
+     * // even though name is not a nullable column, it becomes nullable after using rightJoin
+     * const ok: { name: string | null; text: string }[] = result;
+     * ```
+     *
+     * @param arg - {@link JoinFirstArg}
+     * @param args - {@link JoinArgs}
+     */
     rightJoin<T extends Query, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): JoinResult<T, Arg, true, false>;
+    /**
+     * A `rightJoin` variant accepting a {@link JoinCallback}, see {@link join} for full info.
+     * @param arg - {@link JoinFirstArg}
+     * @param cb - {@link JoinCallback}
+     */
     rightJoin<T extends Query, Arg extends JoinFirstArg<T>, Cb extends JoinCallback<T, Arg>>(this: T, arg: Arg, cb: Cb): JoinResult<T, Arg, true, false, Cb>;
     _rightJoin<T extends Query, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): JoinResult<T, Arg, true, false>;
     _rightJoin<T extends Query, Arg extends JoinFirstArg<T>, Cb extends JoinCallback<T, Arg>>(this: T, arg: Arg, cb: Cb): JoinResult<T, Arg, true, false, Cb>;
+    /**
+     * `fullJoin` is a method for SQL `FULL JOIN`, which is equivalent to `FULL OUTER JOIN`.
+     *
+     * Takes the same arguments as `json`.
+     *
+     * It will load all records from the joining table, both sides of the join may result in `null` values when there is no match.
+     *
+     * All columns become nullable after using `fullJoin`.
+     *
+     * ```ts
+     * const result = await db.user
+     *   .rightJoin('messages')
+     *   .select('name', 'messages.text');
+     *
+     * // all columns can be null
+     * const ok: { name: string | null; text: string | null }[] = result;
+     * ```
+     *
+     * @param arg - {@link JoinFirstArg}
+     * @param args - {@link JoinArgs}
+     */
     fullJoin<T extends Query, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): JoinResult<T, Arg, false, false>;
+    /**
+     * A `fullJoin` variant accepting a {@link JoinCallback}, see {@link join} for full info.
+     * @param arg - {@link JoinFirstArg}
+     * @param cb - {@link JoinCallback}
+     */
     fullJoin<T extends Query, Arg extends JoinFirstArg<T>, Cb extends JoinCallback<T, Arg>>(this: T, arg: Arg, cb: Cb): JoinResult<T, Arg, false, false, Cb>;
     _fullJoin<T extends Query, Arg extends JoinFirstArg<T>, Args extends JoinArgs<T, Arg>>(this: T, arg: Arg, ...args: Args): JoinResult<T, Arg, false, false>;
     _fullJoin<T extends Query, Arg extends JoinFirstArg<T>, Cb extends JoinCallback<T, Arg>>(this: T, arg: Arg, cb: Cb): JoinResult<T, Arg, false, false, Cb>;
+    /**
+     * `joinLateral` allows joining a table with a sub-query that can reference the main table of current query and the other joined tables.
+     *
+     * Regular `JOIN` also can have a sub-query in its definition, but it cannot reference other tables of this query.
+     *
+     * `JOIN LATERAL` of Postgres can have conditions in the `ON` statement, but `Orchid ORM` decided that there are no useful use-cases for such conditions, and it is only building a sub-query.
+     *
+     * First argument is the other table you want to join, or a name of relation, or a name of `with` defined table.
+     *
+     * Second argument is a callback where you can reference other tables using `on` and `orOn`, select columns, do `where` conditions, and use any other query methods to build a sub-query.
+     *
+     * ```ts
+     * // joinLateral a Message table, alias it as `m`
+     * // without aliasing you can refer to the message by a table name
+     * User.joinLateral(Message.as('m'), (q) =>
+     *   q
+     *     // select message columns
+     *     .select('text')
+     *     // join the message to the user, column names can be prefixed with table names
+     *     .on('authorId', 'id')
+     *     // message columns are available without prefixing,
+     *     // outer table columns are available with a table name
+     *     .where({ text: 'some text', 'user.name': 'name' })
+     *     .order({ createdAt: 'DESC' }),
+     * )
+     *   // only selected message columns are available in select and where
+     *   .select('id', 'name', 'm.text')
+     *   .where({ 'm.text': messageData.text });
+     * ```
+     *
+     * As well as simple `join`, `joinLateral` can select an object of full joined record:
+     *
+     * ```ts
+     * // join by relation name
+     * const result = await User.joinLateral(
+     *   'messages',
+     *   (q) => q.as('message'), // alias to 'message'
+     * ).select('name', { message: 'message.*' });
+     *
+     * // result has the following type:
+     * const ok: {
+     *   name: string;
+     *   // full message is included:
+     *   message: { id: number; text: string; updatedAt: Date; createdAt: Date };
+     * }[] = result;
+     * ```
+     *
+     * `message` can be aliased withing the `select` as well as in case of a simple `join`:
+     *
+     * ```ts
+     * // join by relation name
+     * const result = await User.joinLateral(
+     *   'messages',
+     *   (q) => q.as('message'), // alias to 'message'
+     * ).select('name', { msg: 'message.*' });
+     *
+     * // result has the following type:
+     * const ok: {
+     *   name: string;
+     *   // full message is included as msg:
+     *   msg: { id: number; text: string; updatedAt: Date; createdAt: Date };
+     * }[] = result;
+     * ```
+     *
+     * @param arg - {@link JoinFirstArg}
+     * @param cb - {@link JoinLateralCallback}
+     */
     joinLateral<T extends Query, Arg extends JoinFirstArg<T>, R extends QueryBase>(this: T, arg: Arg, cb: JoinLateralCallback<T, Arg, R>): JoinLateralResult<T, R, true>;
     _joinLateral<T extends Query, Arg extends JoinFirstArg<T>, R extends QueryBase>(this: T, arg: Arg, cb: JoinLateralCallback<T, Arg, R>): JoinLateralResult<T, R, true>;
+    /**
+     * The same as {@link joinLateral}, but when no records found for the join it will result in `null`:
+     *
+     * ```ts
+     * const result = await db.user
+     *   .leftJoinLateral('messages', (q) => q.as('message'))
+     *   .select('name', 'message.text');
+     *
+     * // result has the following type:
+     * const ok: { name: string; text: string | null }[] = result;
+     * ```
+     *
+     * @param arg - {@link JoinFirstArg}
+     * @param cb - {@link JoinLateralCallback}
+     */
     leftJoinLateral<T extends Query, Arg extends JoinFirstArg<T>, R extends QueryBase>(this: T, arg: Arg, cb: JoinLateralCallback<T, Arg, R>): JoinLateralResult<T, R, false>;
     _leftJoinLateral<T extends Query, Arg extends JoinFirstArg<T>, R extends QueryBase>(this: T, arg: Arg, cb: JoinLateralCallback<T, Arg, R>): JoinLateralResult<T, R, false>;
 }
@@ -3050,7 +3576,6 @@ type OnArgs<Q extends {
 declare const pushQueryOn: <T extends QueryBase>(q: T, joinFrom: QueryBase, joinTo: QueryBase, ...on: OnArgs<QueryBase>) => T;
 declare const pushQueryOrOn: typeof pushQueryOn;
 declare const addQueryOn: <T extends QueryBase>(q: T, joinFrom: QueryBase, joinTo: QueryBase, ...args: OnArgs<QueryBase>) => T;
-declare const addQueryOrOn: typeof pushQueryOrOn;
 type OnJsonPathEqualsArgs<T extends QueryBase> = [
     leftColumn: keyof T['selectable'],
     leftPath: string,
@@ -4976,6 +5501,52 @@ declare class QueryMethods<CT extends ColumnTypesBase> {
         restartIdentity?: boolean;
         cascade?: boolean;
     }): TruncateResult<T>;
+    /**
+     * `modify` allows modifying the query with your function:
+     *
+     * ```ts
+     * const doSomethingWithQuery = (q: typeof db.table) => {
+     *   // can use all query methods
+     *   return q.select('name').where({ active: true }).order({ createdAt: 'DESC' });
+     * };
+     *
+     * const record = await db.table.select('id').modify(doSomethingWithQuery).find(1);
+     *
+     * record.id; // id was selected before `modify`
+     * record.name; // name was selected by the function
+     * ```
+     *
+     * It's possible to apply different `select`s inside the function, and then the result type will be a union of all possibilities:
+     *
+     * Use this sparingly as it complicates dealing with the result.
+     *
+     * ```ts
+     * const doSomethingWithQuery = (q: typeof db.table) => {
+     *   if (Math.random() > 0.5) {
+     *     return q.select('one');
+     *   } else {
+     *     return q.select('two');
+     *   }
+     * };
+     *
+     * const record = await db.table.modify(doSomethingWithQuery).find(1);
+     *
+     * // TS error: we don't know for sure if the `one` was selected.
+     * record.one;
+     *
+     * // use `in` operator to disambiguate the result type
+     * if ('one' in record) {
+     *   record.one;
+     * } else {
+     *   record.two;
+     * }
+     * ```
+     *
+     * @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.
+     */
+    modify<T extends Query, Arg extends Query & {
+        table: T['table'];
+    }, Result>(this: T, fn: (q: Arg) => Result): Result extends Query ? MergeQuery<T, Result> : Result;
     /**
      * Use `makeHelper` to make a query helper - a function where you can modify the query, and reuse this function across different places.
      *
@@ -6508,4 +7079,4 @@ declare const testTransaction: {
     close(arg: Arg): Promise<void>;
 };
 
-export { Adapter, AdapterConfig, AdapterOptions, AddQuerySelect, AddQueryWith, AfterHook, AggregateMethods, AggregateOptions, AliasOrTable, ArrayColumn, ArrayData, ArrayOfColumnsObjects, AsMethods, BaseOperators, BigIntColumn, BigSerialColumn, BitColumn, BitVaryingColumn, BooleanColumn, BooleanNullable, BoxColumn, ByteaColumn, CharColumn, CidrColumn, CircleColumn, CitextColumn, Clear, ClearStatement, ColumnData, ColumnExpression, ColumnFromDbParams, ColumnInfo, ColumnInfoMethods, ColumnInfoQueryData, ColumnOperators, ColumnType, ColumnTypes, ColumnsObject, ColumnsShape, CommonQueryData, CopyMethods, CopyOptions, CopyQueryData, Create, CreateCtx, CreateData, CreateKind, CreateMethodsNames, CustomTypeColumn, DateBaseColumn, DateColumn, DateTimeBaseClass, DateTimeTzBaseClass, Db, DbOptions, DbResult, DbTableOptions, DecimalBaseColumn, DecimalColumn, DefaultColumnTypes, Delete, DeleteMethodsNames, DeleteQueryData, DomainColumn, DoublePrecisionColumn, DropMode, EnumColumn, ExpressionOutput, FnExpression, FnExpressionArg, For, ForeignKey, ForeignKeyAction, ForeignKeyMatch, ForeignKeyOptions, From, FromArgs, FromResult, GetArg, GetQueryResult, GetStringArg, Having, HavingItem, HookAction, HookSelect, IdentityColumn, IndexColumnOptions, IndexOptions, InetColumn, InsertQueryData, IntegerBaseColumn, IntegerColumn, IntervalColumn, IsolationLevel, JSONColumn, JSONTextColumn, Join, JoinArgs, JoinCallback, JoinFirstArg, JoinItem, JoinLateralCallback, JoinLateralItem, JoinLateralResult, JoinOverrides, JoinResult, JoinedParsers, JoinedShapes, JsonItem, JsonMethods, JsonModifiers, LimitedTextBaseColumn, LineColumn, LsegColumn, MacAddr8Column, MacAddrColumn, MergeQuery, MergeQueryMethods, MoneyColumn, MoreThanOneRowError, NoPrimaryKeyOption, NotFoundError, NumberAsStringBaseColumn, NumberBaseColumn, NumberColumn, NumberColumnData, OnConflictItem, OnConflictMergeUpdate, OnConflictQueryBuilder, OnQueryBuilder, Operator, Operators, OrchidOrmError, OrchidOrmInternalError, OrderArg, OrderArgs, OrderItem, OrderTsQueryConfig, Over, PathColumn, PluckResultColumnType, PointColumn, PolygonColumn, Query, QueryAfterHook, QueryArraysResult, QueryBase, QueryBeforeHook, QueryData, QueryError, QueryErrorName, QueryGet, QueryHookSelect, QueryHooks, QueryLog, QueryLogObject, QueryLogOptions, QueryLogger, QueryMethods, QueryResult, QueryReturnType, QueryReturnsAll, QuerySourceItem, QueryTransform, QueryTransformFn, QueryUpsertOrCreate, QueryWithTable, RawSQL, RawSqlMethods, RealColumn, RelationConfigBase, RelationQuery, RelationQueryBase, RelationSubQueries, RelationsBase, SearchArg, SearchMethods, SearchWeight, Select, SelectAggMethods, SelectArg, SelectItem, SelectQueryBuilder, SelectQueryData, Selectable, SelectableBase, SelectableFromShape, SelectableOfType, SelectableOrExpression, SelectableOrExpressionOfType, SerialColumn, SerialColumnData, SetQueryKind, SetQueryReturns, SetQueryReturnsAll, SetQueryReturnsColumn, SetQueryReturnsColumnInfo, SetQueryReturnsColumnOptional, SetQueryReturnsOne, SetQueryReturnsOneOptional, SetQueryReturnsPluck, SetQueryReturnsRowCount, SetQueryReturnsRows, SetQueryReturnsValue, SetQueryReturnsValueOptional, SetQueryReturnsVoid, SetQueryTableAlias, SetQueryWith, SimpleJoinItem, SingleColumnIndexOptions, SmallIntColumn, SmallSerialColumn, SortDir, StringColumn, SubQueryBuilder, TableData, TextBaseColumn, TextColumn, TextColumnData, Then, TimeColumn, TimeInterval, TimestampColumn, TimestampTZColumn, ToSQLCtx, ToSQLOptions, Transaction, TransactionAdapter, TransactionOptions, TransformMethods, TruncateQueryData, TsQueryColumn, TsVectorColumn, TypeParsers, UUIDColumn, UnhandledTypeError, Union, UnionArg, UnionItem, UnionKind, UnknownColumn, Update, UpdateCtx, UpdateData, UpdateQueryData, UpdateQueryDataItem, UpdateQueryDataObject, UpdatedAtDataInjector, UpsertCreateArg, UpsertData, UpsertResult, UpsertThis, VarCharColumn, VirtualColumn, Where, WhereArg, WhereArgs, WhereInArg, WhereInColumn, WhereInItem, WhereInValues, WhereItem, WhereJsonPathEqualsItem, WhereOnItem, WhereOnJoinItem, WhereQueryBase, WhereQueryBuilder, WhereResult, WhereSearchItem, WhereSearchResult, WindowArg, WindowArgDeclaration, WindowDeclaration, WindowItem, With, WithDataBase, WithDataItem, WithItem, WithOptions, XMLColumn, addOr, addOrNot, addParserForRawExpression, addParserForSelectItem, addQueryOn, addQueryOrOn, addWhere, addWhereIn, addWhereNot, anyShape, checkIfASimpleQuery, cloneQueryArrays, columnCheckToCode, columnCode, columnForeignKeysToCode, columnIndexesToCode, columnTypes, columnsByType, columnsShapeToCode, constraintPropsToCode, constraintToCode, createDb, createOperator, foreignKeyArgumentToCode, getClonedQueryData, getColumnTypes, getConstraintKind, getQueryAs, getShapeFromSelect, getSubQueryBuilder, getTableData, handleResult, identityToCode, indexToCode, instantiateColumn, isQueryReturnsAll, isSelectingCount, joinSubQuery, logColors, logParamToLogObject, makeColumnFn, makeColumnFnClass, makeRegexToFindInSql, makeSQL, newTableData, parseRecord, parseResult, primaryKeyToCode, processSelectArg, pushQueryArray, pushQueryOn, pushQueryOrOn, pushQueryValue, queryMethodByReturnType, queryTypeWithLimitOne, quote, quoteString, raw, referencesArgsToCode, resetTableData, resolveSubQueryCallback, saveSearchAlias, setQueryObjectValue, simplifyColumnDefault, templateLiteralToSQL, testTransaction, throwIfNoWhere, toSQL, toSQLCacheKey };
+export { Adapter, AdapterConfig, AdapterOptions, AddQuerySelect, AddQueryWith, AfterHook, AggregateMethods, AggregateOptions, AliasOrTable, ArrayColumn, ArrayData, ArrayOfColumnsObjects, AsMethods, BaseOperators, BigIntColumn, BigSerialColumn, BitColumn, BitVaryingColumn, BooleanColumn, BooleanNullable, BoxColumn, ByteaColumn, CharColumn, CidrColumn, CircleColumn, CitextColumn, Clear, ClearStatement, ColumnData, ColumnExpression, ColumnFromDbParams, ColumnInfo, ColumnInfoMethods, ColumnInfoQueryData, ColumnOperators, ColumnType, ColumnTypes, ColumnsObject, ColumnsShape, CommonQueryData, CopyMethods, CopyOptions, CopyQueryData, Create, CreateCtx, CreateData, CreateKind, CreateMethodsNames, CustomTypeColumn, DateBaseColumn, DateColumn, DateTimeBaseClass, DateTimeTzBaseClass, Db, DbOptions, DbResult, DbTableOptions, DecimalBaseColumn, DecimalColumn, DefaultColumnTypes, Delete, DeleteMethodsNames, DeleteQueryData, DomainColumn, DoublePrecisionColumn, DropMode, EnumColumn, ExpressionOutput, FnExpression, FnExpressionArg, For, ForeignKey, ForeignKeyAction, ForeignKeyMatch, ForeignKeyOptions, From, FromArgs, FromResult, GetArg, GetQueryResult, GetStringArg, Having, HavingItem, HookAction, HookSelect, IdentityColumn, IndexColumnOptions, IndexOptions, InetColumn, InsertQueryData, IntegerBaseColumn, IntegerColumn, IntervalColumn, IsolationLevel, JSONColumn, JSONTextColumn, Join, JoinArgs, JoinCallback, JoinFirstArg, JoinItem, JoinLateralCallback, JoinLateralItem, JoinLateralResult, JoinOverrides, JoinResult, JoinedParsers, JoinedShapes, JsonItem, JsonMethods, JsonModifiers, LimitedTextBaseColumn, LineColumn, LsegColumn, MacAddr8Column, MacAddrColumn, MergeQuery, MergeQueryMethods, MoneyColumn, MoreThanOneRowError, NoPrimaryKeyOption, NotFoundError, NumberAsStringBaseColumn, NumberBaseColumn, NumberColumn, NumberColumnData, OnConflictItem, OnConflictMergeUpdate, OnConflictQueryBuilder, OnQueryBuilder, Operator, Operators, OrchidOrmError, OrchidOrmInternalError, OrderArg, OrderArgs, OrderItem, OrderTsQueryConfig, Over, PathColumn, PluckResultColumnType, PointColumn, PolygonColumn, Query, QueryAfterHook, QueryArraysResult, QueryBase, QueryBeforeHook, QueryData, QueryError, QueryErrorName, QueryGet, QueryHookSelect, QueryHooks, QueryLog, QueryLogObject, QueryLogOptions, QueryLogger, QueryMethods, QueryResult, QueryReturnType, QueryReturnsAll, QuerySourceItem, QueryTransform, QueryTransformFn, QueryUpsertOrCreate, QueryWithTable, RawSQL, RawSqlMethods, RealColumn, RelationConfigBase, RelationQuery, RelationQueryBase, RelationSubQueries, RelationsBase, SearchArg, SearchMethods, SearchWeight, Select, SelectAggMethods, SelectArg, SelectItem, SelectQueryBuilder, SelectQueryData, Selectable, SelectableBase, SelectableFromShape, SelectableOfType, SelectableOrExpression, SelectableOrExpressionOfType, SerialColumn, SerialColumnData, SetQueryKind, SetQueryReturns, SetQueryReturnsAll, SetQueryReturnsColumn, SetQueryReturnsColumnInfo, SetQueryReturnsColumnOptional, SetQueryReturnsOne, SetQueryReturnsOneOptional, SetQueryReturnsPluck, SetQueryReturnsRowCount, SetQueryReturnsRows, SetQueryReturnsValue, SetQueryReturnsValueOptional, SetQueryReturnsVoid, SetQueryTableAlias, SetQueryWith, SimpleJoinItem, SingleColumnIndexOptions, SmallIntColumn, SmallSerialColumn, SortDir, StringColumn, SubQueryBuilder, TableData, TextBaseColumn, TextColumn, TextColumnData, Then, TimeColumn, TimeInterval, TimestampColumn, TimestampTZColumn, ToSQLCtx, ToSQLOptions, Transaction, TransactionAdapter, TransactionOptions, TransformMethods, TruncateQueryData, TsQueryColumn, TsVectorColumn, TypeParsers, UUIDColumn, UnhandledTypeError, Union, UnionArg, UnionItem, UnionKind, UnknownColumn, Update, UpdateCtx, UpdateData, UpdateQueryData, UpdateQueryDataItem, UpdateQueryDataObject, UpdatedAtDataInjector, UpsertCreateArg, UpsertData, UpsertResult, UpsertThis, VarCharColumn, VirtualColumn, Where, WhereArg, WhereArgs, WhereInArg, WhereInColumn, WhereInItem, WhereInValues, WhereItem, WhereJsonPathEqualsItem, WhereOnItem, WhereOnJoinItem, WhereQueryBase, WhereQueryBuilder, WhereResult, WhereSearchItem, WhereSearchResult, WindowArg, WindowArgDeclaration, WindowDeclaration, WindowItem, With, WithDataBase, WithDataItem, WithItem, WithOptions, XMLColumn, addOr, addOrNot, addParserForRawExpression, addParserForSelectItem, addQueryOn, addWhere, addWhereIn, addWhereNot, anyShape, checkIfASimpleQuery, cloneQueryArrays, columnCheckToCode, columnCode, columnForeignKeysToCode, columnIndexesToCode, columnTypes, columnsByType, columnsShapeToCode, constraintPropsToCode, constraintToCode, createDb, createOperator, foreignKeyArgumentToCode, getClonedQueryData, getColumnTypes, getConstraintKind, getQueryAs, getShapeFromSelect, getSubQueryBuilder, getTableData, handleResult, identityToCode, indexToCode, instantiateColumn, isQueryReturnsAll, isSelectingCount, joinSubQuery, logColors, logParamToLogObject, makeColumnFn, makeColumnFnClass, makeRegexToFindInSql, makeSQL, newTableData, parseRecord, parseResult, primaryKeyToCode, processSelectArg, pushQueryArray, pushQueryOn, pushQueryOrOn, pushQueryValue, queryMethodByReturnType, queryTypeWithLimitOne, quote, quoteString, raw, referencesArgsToCode, resetTableData, resolveSubQueryCallback, saveSearchAlias, setQueryObjectValue, simplifyColumnDefault, templateLiteralToSQL, testTransaction, throwIfNoWhere, toSQL, toSQLCacheKey };