pqb 0.30.5 → 0.30.6

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as orchid_core from 'orchid-core';
-import { QueryResultRow, AdapterConfigBase, AdapterBase, QueryInput, Sql, RecordUnknown, RecordKeyTrue, EmptyObject, QueryBaseCommon, QueryColumns, QueryMetaBase, QueryReturnType, QueryThen, Expression, QueryColumn, MaybeArray, SelectableBase, TemplateLiteralArgs, PickOutputTypeAndOperators, PickQueryResult, OperatorToSQL, ColumnsShapeBase, ColumnsParsers, RecordString, PickQueryTable, FnUnknownToUnknown, ExpressionChain, getValueKey, PickQueryShape, PickQueryTableMetaResult, EmptyTuple, PickQueryMeta, PickQueryMetaResultReturnType, QueryColumnToNullable, PickQueryMetaShape, PickQueryTableMetaResultShape, PickQueryMetaResultWindows, QueryColumnBooleanOrNull, ExpressionData, ValExpression, PickOutputType, SQLQueryArgs, ColumnSchemaConfig, DateColumnData, Code, TimeInterval, ColumnTypeSchemaArg, ColumnDataBase, ArrayMethodsData, RawSQLBase, RawSQLValues, ExpressionTypeMethod, DynamicSQLArg, StaticSQLArgs, ForeignKeyTable, ColumnNameOfTable, BaseNumberData, PickColumnBaseData, ColumnWithDefault, StringTypeData, PrimaryKeyColumn, ParseColumn, EncodeColumn, PickQueryMetaResult, QueryColumnsInit, DefaultSelectColumns, CoreQueryScopes, DbBase, QueryCatch, TransactionState, ColumnTypeBase, CoreBaseOperators, PickQueryUniqueProperties, IsQuery, PickQueryMetaShapeResultReturnType, MergeObjects, PickQueryResultUniqueColumns, QueryInternalBase, PickQueryReturnType, PickType, ColumnShapeOutput, PickQueryMetaReturnType, UniqueColumn, TimestampHelpers, Codes, ColumnDataCheckBase, PickQueryTableMetaShape } from 'orchid-core';
+import { QueryResultRow, AdapterConfigBase, AdapterBase, QueryInput, Sql, RecordUnknown, RecordKeyTrue, EmptyObject, QueryBaseCommon, QueryColumns, QueryMetaBase, QueryReturnType, QueryThen, Expression, QueryColumn, MaybeArray, SelectableBase, TemplateLiteralArgs, PickOutputTypeAndOperators, PickQueryResult, OperatorToSQL, ColumnsShapeBase, ColumnsParsers, RecordString, PickQueryTable, FnUnknownToUnknown, ExpressionChain, getValueKey, PickQueryShape, PickQueryTableMetaResult, EmptyTuple, PickQueryMeta, PickQueryMetaResultReturnType, QueryColumnToNullable, PickQueryMetaShape, PickQueryTableMetaResultShape, PickQueryMetaResultWindows, QueryColumnBooleanOrNull, ExpressionData, ValExpression, PickOutputType, SQLQueryArgs, ColumnSchemaConfig, DateColumnData, Code, TimeInterval, ColumnTypeSchemaArg, ColumnDataBase, ArrayMethodsData, RawSQLBase, RawSQLValues, ExpressionTypeMethod, DynamicSQLArg, StaticSQLArgs, ForeignKeyTable, ColumnNameOfTable, BaseNumberData, PickColumnBaseData, ColumnWithDefault, StringTypeData, PrimaryKeyColumn, ParseColumn, EncodeColumn, PickQueryMetaResult, QueryColumnsInit, DefaultSelectColumns, CoreQueryScopes, DbBase, QueryCatch, TransactionState, ColumnTypeBase, CoreBaseOperators, PickQueryUniqueProperties, IsQuery, PickQueryMetaShapeResultReturnType, MergeObjects, PickQueryResultUniqueColumns, QueryInternalBase, PickQueryReturnType, PickType, ColumnShapeOutput, OperatorsNullable, PickQueryMetaReturnType, UniqueColumn, TimestampHelpers, Codes, ColumnDataCheckBase, PickQueryTableMetaShape } from 'orchid-core';
 import { PoolConfig, Pool, PoolClient } from 'pg';
 import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -2155,6 +2155,15 @@ declare class Where {
      * ```ts
      * db.table.whereIn(['id', 'name'], sql`((1, 'one'), (2, 'two'))`);
      * ```
+     *
+     * When empty set of values is given, `whereIn` will resolve into a {@link QueryMethods.none} query that has a special behavior.
+     *
+     * ```ts
+     * // following queries resolves into `none`:
+     * db.table.where('id', [])
+     * db.table.where(['id', 'name'], [])
+     * db.table.where({ id: [] })
+     * ```
      */
     whereIn<T extends PickQueryMetaRelations, Column extends WhereInColumn<T>>(this: T, ...args: [column: Column, values: WhereInValues<T, Column>] | [arg: WhereInArg<T>]): WhereResult<T>;
     /**
@@ -4124,6 +4133,7 @@ declare class Create {
      * db.table.create(data).onConflictDoNothing();
      *
      * // single column:
+     * // (this requires a composite primary key or unique index, see below)
      * db.table.create(data).onConfict('email').merge();
      *
      * // array of columns:
@@ -4139,6 +4149,34 @@ declare class Create {
      *   .merge();
      * ```
      *
+     * :::info
+     * A primary key or a unique index for a **single** column can be fined on a column:
+     *
+     * ```ts
+     * export class MyTable extends BaseTable {
+     *   columns = this.setColumns((t) => ({
+     *     pkey: t.uuid().primaryKey(),
+     *     unique: t.string().unique(),
+     *   }));
+     * }
+     * ```
+     *
+     * But for composite primary keys or indexes (having multiple columns), define it in a separate function:
+     *
+     * ```ts
+     * export class MyTable extends BaseTable {
+     *   columns = this.setColumns(
+     *     (t) => ({
+     *       one: t.integer(),
+     *       two: t.string(),
+     *       three: t.boolean(),
+     *     }),
+     *     (t) => [t.primaryKey(['one', 'two']), t.unique(['two', 'three'])],
+     *   );
+     * }
+     * ```
+     * :::
+     *
      * You can use the `sql` function exported from your `BaseTable` file in onConflict.
      * It can be useful to specify a condition when you have a partial index:
      *
@@ -4963,10 +5001,10 @@ type SelectAsSelectable<Arg> = {
     } : never;
 }[keyof Arg];
 type SelectAsValueResult<T extends SelectSelf, Arg> = Arg extends keyof T['meta']['selectable'] ? T['meta']['selectable'][Arg]['column'] : Arg extends Expression ? Arg['result']['value'] : Arg extends (q: never) => QueryBase ? SelectSubQueryResult<ReturnType<Arg>> : Arg extends (q: never) => Expression ? ReturnType<Arg>['result']['value'] : Arg extends (q: never) => QueryBase | Expression ? SelectSubQueryResult<Exclude<ReturnType<Arg>, Expression>> | Exclude<ReturnType<Arg>, QueryBase>['result']['value'] : never;
-type SelectSubQueryResult<Arg extends SelectSelf> = QueryReturnsAll<Arg['returnType']> extends true ? ColumnsShapeToObjectArray<Arg['result']> : Arg['returnType'] extends 'valueOrThrow' ? Arg['result']['value'] : Arg['returnType'] extends 'pluck' ? ColumnsShapeToPluck<Arg['result']> : Arg['returnType'] extends 'one' ? ColumnsShapeToNullableObject<Arg['result']> : ColumnsShapeToObject<Arg['result']>;
+type SelectSubQueryResult<Arg extends SelectSelf> = QueryReturnsAll<Arg['returnType']> extends true ? ColumnsShapeToObjectArray<Arg['result']> : Arg['returnType'] extends 'value' | 'valueOrThrow' ? Arg['result']['value'] : Arg['returnType'] extends 'pluck' ? ColumnsShapeToPluck<Arg['result']> : Arg['returnType'] extends 'one' ? ColumnsShapeToNullableObject<Arg['result']> : ColumnsShapeToObject<Arg['result']>;
 declare const addParserForRawExpression: (q: PickQueryQ, key: string | getValueKey, raw: Expression) => void;
 declare const addParserForSelectItem: <T extends PickQueryMeta>(q: T, as: string | getValueKey | undefined, key: string, arg: SelectableOrExpression<T> | Query) => string | Expression | Query;
-declare const processSelectArg: <T extends SelectSelf>(q: T, as: string | undefined, arg: SelectArg<T>, columnAs?: string | getValueKey) => SelectItem;
+declare const processSelectArg: <T extends SelectSelf>(q: T, as: string | undefined, arg: SelectArg<T>, columnAs?: string | getValueKey) => SelectItem | undefined;
 declare const setParserForSelectedString: (q: PickQueryQ, arg: string, as: string | getValueKey | undefined, columnAs?: string | getValueKey) => string;
 declare const getShapeFromSelect: (q: QueryBase, isSubQuery?: boolean) => QueryColumns;
 declare function _querySelect<T extends SelectSelf, Columns extends SelectArg<T>[]>(q: T, columns: Columns): SelectResult<T, Columns>;
@@ -6620,6 +6658,55 @@ declare class QueryMethods<ColumnTypes> {
      * await db.table.all().update(data); // -> 0
      * await db.table.all().delete(); // -> 0
      * ```
+     *
+     * When it's being used in sub-selects, it will return empty arrays, `undefined`'s, or `0` for count,
+     * or it will throw if the sub-query require a result:
+     *
+     * ```ts
+     * await db.user.select({
+     *   // returns empty array
+     *   pets: (q) => q.pets.none(),
+     *   // returns `undefined`
+     *   firstPet: (q) => q.pets.none().takeOptional(),
+     *   // throws NotFound error
+     *   requriedFirstPet: (q) => q.pets.none().take(),
+     *   // returns `undefined`
+     *   firstPetName: (q) => q.pets.none().getOptional('name'),
+     *   // throws NotFound error
+     *   requiredFirstPetName: (q) => q.pets.none().get('name'),
+     *   // returns empty array
+     *   petsNames: (q) => q.pets.none().pluck('name'),
+     *   // returns 0
+     *   petsCount: (q) => q.pets.none().count(),
+     * });
+     * ```
+     *
+     * When the `none` query is being used for joins that require match, the host query will return an empty result:
+     *
+     * ```ts
+     * // all the following queries will resolve into empty arrays
+     *
+     * await db.user.select({
+     *   pets: (q) => q.pets.join().none(),
+     * });
+     *
+     * await db.user.join(
+     *   (q) => q.pets.none(),
+     *   (q) => q,
+     * );
+     *
+     * await db.user.join('pets', (q) => q.none());
+     * ```
+     *
+     * When it's being used in `leftJoin` or `fullJoin`, it implicitly adds `ON false` into the join's SQL.
+     *
+     * ```ts
+     * // this query can return user records
+     * await db.user.leftJoin('pets', (q) => q.none());
+     *
+     * // this query won't return user records, because of the added where condition
+     * await db.user.leftJoin('pets', (q) => q.none()).where({ 'pets.name': 'Kitty' });
+     * ```
      */
     none<T>(this: T): T;
     /**
@@ -6967,7 +7054,9 @@ type SetQueryReturnsPluckColumnKindResult<T extends PickQueryMetaResult, Kind ex
     } : K extends 'returnType' ? 'pluck' : K extends 'result' ? Result : K extends 'then' ? QueryThen<T['result']['value']['outputType'][]> : T[K];
 } & QueryMetaHasSelect;
 type SetQueryReturnsValueOrThrow<T extends PickQueryMeta, Arg extends GetStringArg<T>> = SetQueryReturnsColumnOrThrow<T, T['meta']['selectable'][Arg]['column']> & T['meta']['selectable'][Arg]['column']['operators'];
-type SetQueryReturnsValueOptional<T extends PickQueryMeta, Arg extends GetStringArg<T>> = SetQueryReturnsColumnOptional<T, T['meta']['selectable'][Arg]['column']> & T['meta']['selectable'][Arg]['column']['operators'];
+type SetQueryReturnsValueOptional<T extends PickQueryMeta, Arg extends GetStringArg<T>> = SetQueryReturnsColumnOptional<T, {
+    [K in keyof T['meta']['selectable'][Arg]['column']]: K extends 'outputType' ? T['meta']['selectable'][Arg]['column'][K] | undefined : T['meta']['selectable'][Arg]['column'][K];
+}> & Omit<T['meta']['selectable'][Arg]['column']['operators'], 'equals' | 'not'> & OperatorsNullable<T['meta']['selectable'][Arg]['column']>;
 type SetQueryReturnsColumnOrThrow<T, Column extends PickOutputType> = {
     [K in keyof T]: K extends 'result' ? {
         value: Column;
@@ -7444,7 +7533,7 @@ interface ColumnsShapeToObject<Shape extends QueryColumns> {
 interface ColumnsShapeToNullableObject<Shape extends QueryColumns> {
     dataType: 'object';
     type: ObjectType<Shape>;
-    outputType: ObjectOutput<Shape> | null;
+    outputType: ObjectOutput<Shape> | undefined;
     queryType: ObjectQuery<Shape> | null;
     operators: OperatorsAny;
 }

package/dist/index.js

@@ -2593,6 +2593,32 @@ const makeJoinQueryBuilder = (joinedQuery, joinedShapes, joinTo) => {
   return q;
 };
 
+const noneMethods = {
+  // `then` resolves or rejects based on return type of the query.
+  // It is `async` so it returns a chainable Promise.
+  async then(resolve, reject) {
+    const type = this.q.returnType;
+    if (!type || type === "all" || type === "rows" || type === "pluck")
+      resolve == null ? void 0 : resolve([]);
+    else if (type === "one" || type === "value" || type === "void")
+      resolve == null ? void 0 : resolve();
+    else if (type === "rowCount")
+      resolve == null ? void 0 : resolve(0);
+    else
+      reject == null ? void 0 : reject(new NotFoundError(this));
+  },
+  // `catch` returns a Promise, so it is chainable with then/catch.
+  catch: () => new Promise(orchidCore.noop)
+};
+const _queryNone = (q) => {
+  if (isQueryNone(q))
+    return q;
+  q = extendQuery(q, noneMethods);
+  pushQueryValue(q, "and", new RawSQL("false"));
+  return q;
+};
+const isQueryNone = (q) => q.then === noneMethods.then;
+
 var __defProp$b = Object.defineProperty;
 var __defProps$3 = Object.defineProperties;
 var __getOwnPropDescs$3 = Object.getOwnPropertyDescriptors;
@@ -2612,36 +2638,39 @@ var __spreadValues$b = (a, b) => {
   return a;
 };
 var __spreadProps$3 = (a, b) => __defProps$3(a, __getOwnPropDescs$3(b));
-const _join = (q, require2, type, first, args) => {
+const _join = (query, require2, type, first, args) => {
   var _a, _b;
   let joinKey;
   let shape;
   let parsers;
   let joinSubQuery = false;
   if (typeof first === "function") {
-    first = first(q.relations);
+    first = first(query.relations);
     first.joinQueryAfterCallback = first.joinQuery;
   }
   if (typeof first === "object") {
-    const q2 = first;
-    joinSubQuery = getIsJoinSubQuery(q2);
-    joinKey = q2.q.as || q2.table;
+    if (require2 && isQueryNone(first)) {
+      return _queryNone(query);
+    }
+    const q = first;
+    joinSubQuery = getIsJoinSubQuery(q);
+    joinKey = q.q.as || q.table;
     if (joinKey) {
-      shape = getShapeFromSelect(q2, joinSubQuery);
-      parsers = q2.q.parsers;
+      shape = getShapeFromSelect(q, joinSubQuery);
+      parsers = q.q.parsers;
       if (joinSubQuery) {
-        first = q2.clone();
+        first = q.clone();
         first.shape = shape;
       }
     }
   } else {
     joinKey = first;
-    const relation = q.relations[joinKey];
+    const relation = query.relations[joinKey];
     if (relation) {
       shape = getShapeFromSelect(relation.relationConfig.query);
       parsers = relation.relationConfig.query.q.parsers;
     } else {
-      shape = (_a = q.q.withShapes) == null ? void 0 : _a[joinKey];
+      shape = (_a = query.q.withShapes) == null ? void 0 : _a[joinKey];
       if (shape) {
         if (!require2)
           shape = __spreadValues$b({}, shape);
@@ -2657,20 +2686,20 @@ const _join = (q, require2, type, first, args) => {
   }
   if (joinKey) {
     setQueryObjectValue(
-      q,
+      query,
       "joinedShapes",
       joinKey,
       shape
     );
     setQueryObjectValue(
-      q,
+      query,
       "joinedParsers",
       joinKey,
       parsers
     );
   }
   const joinArgs = processJoinArgs(
-    q,
+    query,
     first,
     args,
     joinSubQuery
@@ -2680,20 +2709,22 @@ const _join = (q, require2, type, first, args) => {
     if (j.q.select || !j.internal.columnsForSelectAll) {
       const shape2 = getShapeFromSelect(j, true);
       setQueryObjectValue(
-        q,
+        query,
         "joinedShapes",
         joinKey,
         shape2
       );
       setQueryObjectValue(
-        q,
+        query,
         "joinedParsers",
         joinKey,
         j.q.parsers
       );
     }
+  } else if (require2 && "r" in joinArgs && isQueryNone(joinArgs.r)) {
+    return _queryNone(query);
   }
-  return pushQueryValue(q, "join", {
+  return pushQueryValue(query, "join", {
     type,
     args: joinArgs
   });
@@ -3328,6 +3359,26 @@ const addParserForSelectItem = (q, as, key, arg) => {
           );
         });
       }
+      if (query.returnType === "valueOrThrow" || query.returnType === "oneOrThrow") {
+        pushQueryValue(
+          q,
+          "transform",
+          (data) => {
+            if (Array.isArray(data)) {
+              for (const item of data) {
+                if (item[key] === void 0) {
+                  throw new NotFoundError(q);
+                }
+              }
+            } else {
+              if (data[key] === void 0) {
+                throw new NotFoundError(q);
+              }
+            }
+            return data;
+          }
+        );
+      }
     }
     return arg;
   }
@@ -3344,7 +3395,11 @@ const processSelectArg = (q, as, arg, columnAs) => {
     let value = arg[key];
     if (typeof value === "function") {
       value = resolveSubQueryCallback(q, value);
-      if (!orchidCore.isExpression(value) && value.joinQuery) {
+      if (isQueryNone(value)) {
+        if (value.q.innerJoinLateral) {
+          return;
+        }
+      } else if (!orchidCore.isExpression(value) && value.joinQuery) {
         value = value.joinQuery(value, q);
         let query;
         const returnType = value.q.returnType;
@@ -3501,11 +3556,18 @@ const maybeUnNameColumn = (column, isSubQuery) => {
   return isSubQuery && (column == null ? void 0 : column.data.name) ? orchidCore.setColumnData(column, "name", void 0) : column;
 };
 function _querySelect(q, args) {
-  if (!args.length) {
+  const len = args.length;
+  if (!len) {
     return q;
   }
   const as = q.q.as || q.table;
-  const selectArgs = args.map((item) => processSelectArg(q, as, item));
+  const selectArgs = new Array(len);
+  for (let i = 0; i < len; i++) {
+    selectArgs[i] = processSelectArg(q, as, args[i]);
+    if (!selectArgs[i]) {
+      return _queryNone(q);
+    }
+  }
   return pushQueryArray(q, "select", selectArgs);
 }
 class Select {
@@ -3855,7 +3917,37 @@ const selectAllSql = (table, query, quotedAs) => {
   return ((_a = query.join) == null ? void 0 : _a.length) ? ((_b = table.internal.columnsForSelectAll) == null ? void 0 : _b.map((item) => `${quotedAs}.${item}`).join(", ")) || `${quotedAs}.*` : ((_c = table.internal.columnsForSelectAll) == null ? void 0 : _c.join(", ")) || "*";
 };
 const pushSubQuerySql = (ctx, query, as, list, quotedAs) => {
+  var _a;
   const { returnType = "all" } = query.q;
+  if (isQueryNone(query)) {
+    let sql;
+    switch (returnType) {
+      case "one":
+      case "oneOrThrow":
+      case "void":
+        return;
+      case "value":
+      case "valueOrThrow":
+        if (((_a = query.q.expr) == null ? void 0 : _a.result.value) instanceof IntegerBaseColumn) {
+          sql = "0";
+        } else {
+          return;
+        }
+        break;
+      case "all":
+      case "pluck":
+      case "rows":
+        sql = `'[]'::json`;
+        break;
+      case "rowCount":
+        sql = "0";
+        break;
+      default:
+        throw new UnhandledTypeError(query, returnType);
+    }
+    list.push(`${sql} "${as}"`);
+    return;
+  }
   if (query.q.joinedForSelect) {
     let sql;
     switch (returnType) {
@@ -6509,6 +6601,7 @@ class Create {
    * db.table.create(data).onConflictDoNothing();
    *
    * // single column:
+   * // (this requires a composite primary key or unique index, see below)
    * db.table.create(data).onConfict('email').merge();
    *
    * // array of columns:
@@ -6524,6 +6617,34 @@ class Create {
    *   .merge();
    * ```
    *
+   * :::info
+   * A primary key or a unique index for a **single** column can be fined on a column:
+   *
+   * ```ts
+   * export class MyTable extends BaseTable {
+   *   columns = this.setColumns((t) => ({
+   *     pkey: t.uuid().primaryKey(),
+   *     unique: t.string().unique(),
+   *   }));
+   * }
+   * ```
+   *
+   * But for composite primary keys or indexes (having multiple columns), define it in a separate function:
+   *
+   * ```ts
+   * export class MyTable extends BaseTable {
+   *   columns = this.setColumns(
+   *     (t) => ({
+   *       one: t.integer(),
+   *       two: t.string(),
+   *       three: t.boolean(),
+   *     }),
+   *     (t) => [t.primaryKey(['one', 'two']), t.unique(['two', 'three'])],
+   *   );
+   * }
+   * ```
+   * :::
+   *
    * You can use the `sql` function exported from your `BaseTable` file in onConflict.
    * It can be useful to specify a condition when you have a partial index:
    *
@@ -8431,6 +8552,9 @@ const _queryOrNot = (q, args) => {
 const _queryWhereIn = (q, and, arg, values, not) => {
   let item;
   if (values) {
+    if ("length" in values && !values.length) {
+      return _queryNone(q);
+    }
     if (Array.isArray(arg)) {
       item = {
         IN: {
@@ -8444,7 +8568,11 @@ const _queryWhereIn = (q, and, arg, values, not) => {
   } else {
     item = {};
     for (const key in arg) {
-      item[key] = { in: arg[key] };
+      const values2 = arg[key];
+      if ("length" in values2 && !values2.length) {
+        return _queryNone(q);
+      }
+      item[key] = { in: values2 };
     }
   }
   if (not)
@@ -8993,6 +9121,15 @@ class Where {
    * ```ts
    * db.table.whereIn(['id', 'name'], sql`((1, 'one'), (2, 'two'))`);
    * ```
+   *
+   * When empty set of values is given, `whereIn` will resolve into a {@link QueryMethods.none} query that has a special behavior.
+   *
+   * ```ts
+   * // following queries resolves into `none`:
+   * db.table.where('id', [])
+   * db.table.where(['id', 'name'], [])
+   * db.table.where({ id: [] })
+   * ```
    */
   whereIn(...args) {
     return _queryWhereIn(
@@ -10197,24 +10334,6 @@ class TransformMethods {
   }
 }
 
-const noneMethods = {
-  // `then` resolves or rejects based on return type of the query.
-  // It is `async` so it returns a chainable Promise.
-  async then(resolve, reject) {
-    const type = this.q.returnType;
-    if (!type || type === "all" || type === "rows" || type === "pluck")
-      resolve == null ? void 0 : resolve([]);
-    else if (type === "one" || type === "value" || type === "void")
-      resolve == null ? void 0 : resolve();
-    else if (type === "rowCount")
-      resolve == null ? void 0 : resolve(0);
-    else
-      reject == null ? void 0 : reject(new NotFoundError(this));
-  },
-  // `catch` returns a Promise, so it is chainable with then/catch.
-  catch: () => new Promise(orchidCore.noop)
-};
-
 class ScopeMethods {
   /**
    * See {@link ScopeMethods}
@@ -10998,9 +11117,58 @@ class QueryMethods {
    * await db.table.all().update(data); // -> 0
    * await db.table.all().delete(); // -> 0
    * ```
+   *
+   * When it's being used in sub-selects, it will return empty arrays, `undefined`'s, or `0` for count,
+   * or it will throw if the sub-query require a result:
+   *
+   * ```ts
+   * await db.user.select({
+   *   // returns empty array
+   *   pets: (q) => q.pets.none(),
+   *   // returns `undefined`
+   *   firstPet: (q) => q.pets.none().takeOptional(),
+   *   // throws NotFound error
+   *   requriedFirstPet: (q) => q.pets.none().take(),
+   *   // returns `undefined`
+   *   firstPetName: (q) => q.pets.none().getOptional('name'),
+   *   // throws NotFound error
+   *   requiredFirstPetName: (q) => q.pets.none().get('name'),
+   *   // returns empty array
+   *   petsNames: (q) => q.pets.none().pluck('name'),
+   *   // returns 0
+   *   petsCount: (q) => q.pets.none().count(),
+   * });
+   * ```
+   *
+   * When the `none` query is being used for joins that require match, the host query will return an empty result:
+   *
+   * ```ts
+   * // all the following queries will resolve into empty arrays
+   *
+   * await db.user.select({
+   *   pets: (q) => q.pets.join().none(),
+   * });
+   *
+   * await db.user.join(
+   *   (q) => q.pets.none(),
+   *   (q) => q,
+   * );
+   *
+   * await db.user.join('pets', (q) => q.none());
+   * ```
+   *
+   * When it's being used in `leftJoin` or `fullJoin`, it implicitly adds `ON false` into the join's SQL.
+   *
+   * ```ts
+   * // this query can return user records
+   * await db.user.leftJoin('pets', (q) => q.none());
+   *
+   * // this query won't return user records, because of the added where condition
+   * await db.user.leftJoin('pets', (q) => q.none()).where({ 'pets.name': 'Kitty' });
+   * ```
    */
   none() {
-    return this.then === noneMethods.then ? this : extendQuery(this, noneMethods);
+    return _queryNone(this);
   }
   /**
    * `modify` allows modifying the query with your function: