pqb 0.30.5 → 0.30.7

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';
@@ -615,7 +615,7 @@ type JoinFirstArg<T extends PickQueryRelationsWithData> = PickQueryTableMetaResu
  * Arguments of `join` methods (not `joinLateral`).
  * See {@link join}
  */
-type JoinArgs<T extends PickQueryMetaShapeRelationsWithData, Arg extends JoinFirstArg<T>> = [JoinCallback<T, Arg>] | (Arg extends PickQueryTableMetaResult ? JoinQueryArgs<T, Arg> : Arg extends keyof T['relations'] ? EmptyTuple : Arg extends keyof T['withData'] ? JoinWithArgs<T, Arg> : never);
+type JoinArgs<T extends PickQueryMetaShapeRelationsWithData, Arg extends JoinFirstArg<T>> = [on?: JoinCallback<T, Arg>] | (Arg extends PickQueryTableMetaResult ? JoinQueryArgs<T, Arg> : Arg extends keyof T['relations'] ? EmptyTuple : Arg extends keyof T['withData'] ? JoinWithArgs<T, Arg> : never);
 /**
  * Column names of the joined table that can be used to join.
  * Derived from 'result', not from 'shape',
@@ -1382,7 +1382,7 @@ declare const _queryJoinOnJsonPathEquals: <T extends PickQueryMeta>(q: T, args:
  */
 type JoinQueryBuilder<T extends PickQueryMetaShape = PickQueryMetaShape, J extends PickQueryTableMetaResult = PickQueryTableMetaResult> = {
     [K in keyof J]: K extends 'meta' ? {
-        [K in keyof J['meta']]: K extends 'selectable' ? J['meta']['selectable'] & Omit<T['meta']['selectable'], keyof T['shape']> : J['meta'][K];
+        [K in keyof J['meta']]: K extends 'selectable' ? SelectableFromShape<J['result'], AliasOrTable<J>> & Omit<T['meta']['selectable'], keyof T['shape']> : J['meta'][K];
     } : J[K];
 } & OnMethods;
 declare class OnMethods {
@@ -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>;
     /**
@@ -3789,19 +3798,16 @@ interface CreateSelf extends QueryBase {
 }
 type CreateData<T extends CreateSelf, BelongsToData = CreateBelongsToData<T>> = RelationsBase extends T['relations'] ? CreateDataWithDefaults<T, keyof T['meta']['defaults']> : CreateRelationsData<T, BelongsToData>;
 type CreateDataWithDefaults<T extends CreateSelf, Defaults extends PropertyKey> = {
-    [K in keyof T['inputType'] as K extends Defaults ? never : K]: K extends Defaults ? never : CreateColumn<T['inputType'], K>;
+    [K in keyof T['inputType'] as K extends Defaults ? never : K]: K extends Defaults ? never : CreateColumn<T, K>;
 } & {
-    [K in Defaults]?: K extends keyof T['inputType'] ? CreateColumn<T['inputType'], K> : never;
+    [K in Defaults]?: K extends keyof T['inputType'] ? CreateColumn<T, K> : never;
 };
 type CreateDataWithDefaultsForRelations<T extends CreateSelf, Defaults extends keyof T['inputType'], OmitFKeys extends PropertyKey> = {
-    [K in keyof T['inputType'] as K extends Defaults | OmitFKeys ? never : K]: K extends Defaults | OmitFKeys ? never : CreateColumn<T['inputType'], K>;
+    [K in keyof T['inputType'] as K extends Defaults | OmitFKeys ? never : K]: K extends Defaults | OmitFKeys ? never : CreateColumn<T, K>;
 } & {
-    [K in Defaults as K extends OmitFKeys ? never : K]?: CreateColumn<T['inputType'], K>;
-};
-type CreateColumn<InputType, Key extends keyof InputType> = Expression | InputType[Key] | {
-    __isQuery: true;
-    then: QueryThen<InputType[Key]>;
+    [K in Defaults as K extends OmitFKeys ? never : K]?: CreateColumn<T, K>;
 };
+type CreateColumn<T extends CreateSelf, K extends keyof T['inputType']> = T['inputType'][K] | QueryOrExpression<T['inputType'][K]> | ((q: T) => QueryOrExpression<T['inputType'][K]>);
 type CreateRelationsData<T extends CreateSelf, BelongsToData> = CreateDataWithDefaultsForRelations<T, keyof T['meta']['defaults'], T['relations'][keyof T['relations']]['relationConfig']['omitForeignKeyInCreate']> & BelongsToData & T['relations'][keyof T['relations']]['relationConfig']['optionalDataForCreate'];
 type CreateBelongsToData<T extends CreateSelf> = CreateRelationsDataOmittingFKeys<T, T['relations'][keyof T['relations']]['relationConfig']['dataForCreate']>;
 type CreateRelationsDataOmittingFKeys<T extends CreateSelf, Union> = (Union extends RelationConfigDataForCreate ? (u: keyof Union['columns'] extends keyof T['meta']['defaults'] ? Omit<Union['columns'], keyof T['meta']['defaults']> & {
@@ -3909,7 +3915,7 @@ declare class Create {
      *
      * await db.table.create({
      *   // raw SQL
-     *   column1: sql`'John' || ' ' || 'Doe'`,
+     *   column1: (q) => q.sql`'John' || ' ' || 'Doe'`,
      *
      *   // query that returns a single value
      *   // returning multiple values will result in Postgres error
@@ -4124,6 +4130,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 +4146,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 +4998,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>;
@@ -5199,26 +5234,24 @@ declare class Union {
 }
 
 type UpdateSelf = {
-    [K in 'meta' | 'inputType' | 'relations' | 'shape' | 'result' | 'returnType' | keyof JsonModifiers]: Query[K];
+    [K in 'inputType' | 'relations' | UpdateColumnArgKeys]: Query[K];
 };
 type UpdateData<T extends UpdateSelf> = {
     [K in keyof T['inputType']]?: UpdateColumn<T, K>;
 } & {
     [K in keyof T['relations']]?: UpdateRelationData<T, T['relations'][K]['relationConfig']>;
 };
-type UpdateColumnArgKeys = keyof JsonModifiers | 'meta' | 'shape' | 'result' | 'returnType';
-type UpdateColumnCallbackResult = JsonItem | ResultRelationQueryBase;
-interface ResultRelationQueryBaseMeta extends QueryMetaBase {
-    kind: 'select';
-}
-interface ResultRelationQueryBase extends RelationQueryBase {
-    meta: ResultRelationQueryBaseMeta;
+type UpdateColumnArgKeys = keyof JsonModifiers | keyof ExpressionMethods | 'sql' | 'meta' | 'shape' | 'result' | 'returnType' | 'columnTypes';
+interface UpdateQueryOrExpression<T> extends QueryOrExpression<T> {
+    meta: {
+        kind: 'select';
+    };
 }
-type UpdateColumn<T extends UpdateSelf, Key extends keyof T['inputType']> = T['inputType'][Key] | Expression | {
+type UpdateColumn<T extends UpdateSelf, Key extends keyof T['inputType']> = T['inputType'][Key] | QueryOrExpression<T['inputType'][Key]> | {
     [K in keyof Query]: K extends 'then' ? QueryThen<T['inputType'][Key]> : Query[K];
 } | ((q: {
     [K in keyof T['relations'] | UpdateColumnArgKeys]: K extends keyof T['relations'] ? T['relations'][K] : K extends UpdateColumnArgKeys ? T[K] : never;
-}) => UpdateColumnCallbackResult);
+}) => JsonItem | UpdateQueryOrExpression<T['inputType'][Key]>);
 type UpdateRelationData<T extends UpdateSelf, Rel extends RelationConfigBase> = QueryReturnsAll<T['returnType']> extends true ? Rel['dataForUpdate'] : Rel['one'] extends true ? Rel['dataForUpdate'] | Rel['dataForUpdateOne'] : Rel['dataForUpdate'] & Rel['dataForUpdateOne'];
 type UpdateArg<T extends UpdateSelf> = T['meta']['hasWhere'] extends true ? UpdateData<T> : never;
 type UpdateRawArgs<T extends UpdateSelf> = T['meta']['hasWhere'] extends true ? SQLQueryArgs : never;
@@ -5292,7 +5325,7 @@ declare class Update {
      *   column1: 123,
      *
      *   // use raw SQL to update the column
-     *   column2: sql`2 + 2`,
+     *   column2: (q) => q.sql`2 + 2`,
      *
      *   // use query that returns a single value
      *   // returning multiple values will result in Postgres error
@@ -5401,7 +5434,7 @@ declare class Update {
      */
     update<T extends UpdateSelf>(this: T, arg: UpdateArg<T>): UpdateResult<T>;
     /**
-     * `updateRaw` is for updating records with raw expression.
+     * `updateSql` is for updating records with raw expression.
      *
      * The behavior is the same as a regular `update` method has:
      * `find` or `where` must precede calling this method,
@@ -5412,14 +5445,14 @@ declare class Update {
      * const value = 'new name';
      *
      * // update with SQL template string
-     * const updatedCount = await db.table.find(1).updateRaw`name = ${value}`;
+     * const updatedCount = await db.table.find(1).updateSql`name = ${value}`;
      *
      * // or update with `sql` function:
-     * await db.table.find(1).updateRaw(sql`name = ${value}`);
+     * await db.table.find(1).updateSql(sql`name = ${value}`);
      * ```
      * @param args - raw SQL via a template string or by using a `sql` method
      */
-    updateRaw<T extends UpdateSelf>(this: T, ...args: UpdateRawArgs<T>): UpdateResult<T>;
+    updateSql<T extends UpdateSelf>(this: T, ...args: UpdateRawArgs<T>): UpdateResult<T>;
     /**
      * To make sure that at least one row was updated use `updateOrThrow`:
      *
@@ -6620,6 +6653,52 @@ 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());
+     *
+     * 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 +7046,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 +7525,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;
 }