pqb 0.12.1 → 0.12.3

package/dist/index.d.ts

@@ -50,6 +50,14 @@ declare class TransactionAdapter implements Adapter {
 declare abstract class OrchidOrmError extends Error {
     abstract query: Query;
 }
+/**
+ * When we search for a single record, and it is not found, it can either throw an error, or return `undefined`.
+ *
+ * Unlike other database libraries, `Orchid ORM` decided to throw errors by default when using methods `take`, `find`, `findBy`, `get` and the record is not found.
+ * It is a [good practice](https://github.com/goldbergyoni/nodebestpractices/blob/master/sections/errorhandling/centralizedhandling.md) to catch common errors in a centralized place (see [global error handling](https://orchid-orm.netlify.app/guide/error-handling.html#global-error-handling)), and this allows for a more concise code.
+ *
+ * If it's more suitable to get the `undefined` value instead of throwing, use `takeOptional`, `findOptional`, `findByOptional`, `getOptional` instead.
+ */
 declare class NotFoundError extends OrchidOrmError {
     query: Query;
     constructor(query: Query, message?: string);
@@ -173,6 +181,11 @@ declare const toSql: (table: Query, options?: ToSqlOptions) => Sql;
 declare const makeSql: (table: Query, options?: ToSqlOptionsInternal) => Sql;
 
 declare abstract class QueryBase implements QueryBaseCommon {
+    /**
+     * Clones the current query chain, useful for re-using partial query snippets in other queries without mutating the original.
+     *
+     * Used under the hood, and not really needed on the app side.
+     */
     clone<T extends QueryBase>(this: T): T;
     abstract result: ColumnsShapeBase;
     query: QueryData;
@@ -451,6 +464,7 @@ type CommonQueryData = {
     logger: QueryLogger;
     autoPreparedStatements?: boolean;
     [toSqlCacheKey]?: Sql;
+    transform?: ((input: unknown) => unknown)[];
 };
 type SelectQueryData = CommonQueryData & {
     type: undefined;
@@ -603,7 +617,7 @@ declare const parseRecord: (parsers: ColumnsParsers, row: any) => any;
 
 type SelectArg<T extends QueryBase> = '*' | StringKey<keyof T['selectable']> | SelectAsArg<T>;
 type SelectAsArg<T extends QueryBase> = Record<string, SelectAsValue<T>>;
-type SelectAsValue<T extends QueryBase> = StringKey<keyof T['selectable']> | RawExpression | ((q: T) => Query) | ((q: T) => RawExpression) | ((q: T) => Query | RawExpression);
+type SelectAsValue<T extends QueryBase> = StringKey<keyof T['selectable']> | RawExpression | ((q: T) => QueryBase) | ((q: T) => RawExpression) | ((q: T) => QueryBase | RawExpression);
 type SelectObjectResultTuple = [ColumnsShapeBase, SelectableBase];
 type SelectResult<T extends Query, Args extends SelectArg<T>[], SelectStringsResult extends ColumnsShapeBase = SelectStringArgsResult<T, Args>, StringsKeys extends keyof SelectStringsResult = keyof SelectStringsResult, SelectAsResult extends SelectObjectResultTuple = SpreadSelectObjectArgs<T, Args, [
     EmptyObject,
@@ -622,7 +636,7 @@ type SelectStringArgsResult<T extends Query, Args extends SelectArg<T>[]> = {
 };
 type SpreadSelectObjectArgs<T extends Query, Args extends [...unknown[]], Result extends SelectObjectResultTuple> = Args extends [infer L, ...infer R] ? SpreadSelectObjectArgs<T, R, SelectAsResult<T, L, Result>> : Result;
 type SelectAsResult<T extends Query, Arg, Result extends SelectObjectResultTuple, Shape = Result[0], AddSelectable extends SelectableBase = {
-    [K in keyof Arg]: Arg[K] extends ((q: T) => infer R extends Query) ? (x: {
+    [K in keyof Arg]: Arg[K] extends ((q: T) => infer R extends QueryBase) ? (x: {
         [C in keyof R['result'] as `${StringKey<K>}.${StringKey<C>}`]: {
             as: C;
             column: R['result'][C];
@@ -636,8 +650,8 @@ type SelectAsResult<T extends Query, Arg, Result extends SelectObjectResultTuple
     },
     Result[1] & AddSelectable
 ] : Result;
-type SelectAsValueResult<T extends Query, Arg extends SelectAsValue<T>> = Arg extends keyof T['selectable'] ? T['selectable'][Arg]['column'] : Arg extends RawExpression ? Arg['__column'] : Arg extends (q: T) => infer R ? R extends Query ? SelectSubQueryResult<R> : R extends RawExpression ? R['__column'] : R extends Query | RawExpression ? SelectSubQueryResult<Exclude<R, RawExpression>> | Exclude<R, Query>['__column'] : never : never;
-type SelectSubQueryResult<Arg extends Query & {
+type SelectAsValueResult<T extends Query, Arg extends SelectAsValue<T>> = Arg extends keyof T['selectable'] ? T['selectable'][Arg]['column'] : Arg extends RawExpression ? Arg['__column'] : Arg extends (q: T) => infer R ? R extends QueryBase ? SelectSubQueryResult<R> : R extends RawExpression ? R['__column'] : R extends QueryBase | RawExpression ? SelectSubQueryResult<Exclude<R, RawExpression>> | Exclude<R, QueryBase>['__column'] : never : never;
+type SelectSubQueryResult<Arg extends QueryBase & {
     [isRequiredRelationKey]?: boolean;
 }> = QueryReturnsAll<Arg['returnType']> extends true ? ArrayOfColumnsObjects<Arg['result']> : Arg['returnType'] extends 'valueOrThrow' ? Arg['result']['value'] : Arg['returnType'] extends 'pluck' ? PluckResultColumnType<Arg['result']['pluck']> : Arg[isRequiredRelationKey] extends true ? ColumnsObject<Arg['result']> : NullableColumn<ColumnsObject<Arg['result']>>;
 declare const addParserForRawExpression: (q: Query, key: string | getValueKey, raw: RawExpression) => void;
@@ -746,6 +760,34 @@ type FromQueryResult<T extends Query, Q extends Query, Selectable extends Select
     } : K extends 'selectable' ? Selectable : K extends 'result' | 'shape' ? Q['result'] : K extends 'then' ? QueryThen<Data> : K extends 'catch' ? QueryCatch<Data> : T[K];
 };
 declare class From {
+    /**
+     * Set the `FROM` value, by default the table name is used.
+     *
+     * ```ts
+     * // accepts sub-query:
+     * db.table.from(Otherdb.table.select('foo', 'bar'));
+     *
+     * // accepts raw sql by template literal:
+     * const value = 123;
+     * db.table.from`value = ${value}`;
+     *
+     * // accepts raw sql:
+     * db.table.from(db.table.sql`value = ${value}`);
+     *
+     * // accepts alias of `WITH` expression:
+     * q.with('foo', Otherdb.table.select('id', 'name')).from('foo');
+     * ```
+     *
+     * Optionally takes a second argument of type `{ only?: boolean }`, (see `FROM ONLY` in Postgres docs, this is related to table inheritance).
+     *
+     * ```ts
+     * db.table.from(Otherdb.table.select('foo', 'bar'), {
+     *   only: true,
+     * });
+     * ```
+     *
+     * @param args - query, raw SQL, name of CTE table, or a template string
+     */
     from<T extends Query, Args extends FromArgs<T>>(this: T, ...args: Args): FromResult<T, Args>;
     _from<T extends Query, Args extends FromArgs<T>>(this: T, ...args: Args): FromResult<T, Args>;
 }
@@ -2471,6 +2513,106 @@ type SqlResult<T extends Query, Args extends SqlArgs<T>> = Args extends SqlColum
 }] | TemplateLiteralArgs ? RawExpression : SqlFn<ColumnType>;
 type RawArgs<CT extends ColumnTypesBase, C extends ColumnType> = [column: (types: CT) => C, sql: string, values?: Record<string, unknown>] | [sql: string, values?: Record<string, unknown>];
 declare class RawSqlMethods {
+    /**
+     * When there is a need to use a piece of raw SQL, use the `sql` method.
+     *
+     * To select with a raw SQL, need to specify a column type as a first argument, so the TS could use it to guess the result type of the query:
+     *
+     * ```ts
+     * const result: { num: number }[] = await db.table.select({
+     *   num: db.table.sql((t) => t.integer())`
+     *     random() * 100
+     *   `,
+     * });
+     * ```
+     *
+     * Other than for select, the column type can be omitted:
+     *
+     * ```ts
+     * await db.table.where(db.table.sql`
+     *   "someValue" = random() * 100
+     * `);
+     * ```
+     *
+     * Interpolating values in template literals is completely safe:
+     *
+     * ```ts
+     * // get value from user-provided params
+     * const { value } = req.params;
+     *
+     * // SQL injection is prevented by a library, this is safe:
+     * await db.table.where(db.table.sql`
+     *   column = ${value}
+     * `);
+     * ```
+     *
+     * SQL can be passed with a simple string, it's important to note that this is not safe to interpolate values in it.
+     *
+     * ```ts
+     * // no interpolation is okay
+     * await db.table.where(db.table.sql({ raw: 'column = random() * 100' }));
+     *
+     * // get value from user-provided params
+     * const { value } = req.params;
+     *
+     * // this is NOT safe, SQL injection is possible:
+     * await db.table.where(db.table.sql({ raw: `column = random() * ${value}` }));
+     * ```
+     *
+     * To inject values into `raw` SQL strings, define it with `$` in the string and provide `values` object.
+     *
+     * Use `$$` to provide column or/and table name. Column names will be quoted so don't quote them manually.
+     *
+     * ```ts
+     * // get value from user-provided params
+     * const { value } = req.params;
+     *
+     * // this is SAFE, SQL injection are prevented:
+     * await db.table.where(
+     *   db.table.sql({
+     *     values: {
+     *       column: 'someTable.someColumn', // or simply 'column'
+     *       one: value,
+     *       two: 123,
+     *     },
+     *     raw: '$$column = random() * $value',
+     *   }),
+     * );
+     * ```
+     *
+     * Summarizing:
+     *
+     * ```ts
+     * // simplest form:
+     * db.table`key = ${value}`;
+     *
+     * // with column type for select:
+     * db.table((t) => t.boolean())`key = ${value}`;
+     *
+     * // raw SQL string, not allowed to interpolate:
+     * db.table({ raw: 'random()' });
+     *
+     * // with values:
+     * db.table({
+     *   values: {
+     *     column: 'columnName',
+     *     one: 1,
+     *     two: 2,
+     *   },
+     *   raw: '$$columnName = $one + $two',
+     * });
+     *
+     * // with column type for select:
+     * db.table((t) => t.decimal(), { raw: 'random()' });
+     *
+     * // combine values and template literal:
+     * db.table({ values: { one: 1, two: 2 } })`
+     *   ($one + $two) / $one
+     * `;
+     * ```
+     *
+     * @param args - template string or a specific options
+     */
     sql<T extends Query, Args extends SqlArgs<T>>(this: T, ...args: Args): SqlResult<T, Args>;
     /**
      * @deprecated use `sql` method instead, `raw` will be removed
@@ -2530,10 +2672,87 @@ declare class CopyMethods {
 }
 
 declare abstract class AsMethods extends QueryBase {
+    /**
+     * Sets table alias:
+     *
+     * ```ts
+     * db.table.as('u').select('u.name');
+     *
+     * // Can be used in the join:
+     * db.table.join(Profile.as('p'), 'p.userId', 'user.id');
+     * ```
+     *
+     * @param as - alias for the table of this query
+     */
     as<T extends AsMethods, As extends string>(this: T, as: As): SetQueryTableAlias<T, As>;
     _as<T extends AsMethods, As extends string>(this: T, as: As): SetQueryTableAlias<T, As>;
 }
 
+type TransformFn<T extends Query> = (input: T['catch'] extends QueryCatch<infer Data> ? Data : never) => unknown;
+type QueryTransform<T extends QueryBase, Fn extends TransformFn<Query>, Data = ReturnType<Fn>> = {
+    [K in keyof QueryBase]: K extends 'returnType' ? 'valueOrThrow' : K extends 'result' ? {
+        value: ColumnTypeBase<Data>;
+    } : T[K];
+} & {
+    then: QueryThen<Data>;
+    catch: QueryCatch<Data>;
+};
+declare class TransformMethods {
+    /**
+     * Transform the result of the query right after loading it.
+     *
+     * `transform` method should be called in the last order, other methods can't be chained after calling it.
+     *
+     * The [hooks](/guide/hooks.html) that are going to run after the query will receive the query result **before** transferring.
+     *
+     * Consider the following example of a cursor-based pagination by `id`:
+     *
+     * ```ts
+     * const lastId: number | undefined = req.query.cursor;
+     *
+     * type Result = {
+     *   nodes: { id: number; text: string }[];
+     *   cursor?: number;
+     * };
+     *
+     * // result is only for demo, it will be inferred
+     * const posts: Result = await db.post
+     *   .select('id', 'text')
+     *   .where({ id: { lt: lastId } })
+     *   .order({ id: 'DESC' })
+     *   .limit(100)
+     *   .transform((nodes) => ({ nodes, cursor: nodes.at(-1)?.id }));
+     * ```
+     *
+     * You can also use the `tranform` on a nested sub-queries:
+     *
+     * ```ts
+     * type Result = {
+     *   nodes: {
+     *     id: number;
+     *     text: string;
+     *     comments: { nodes: { id: number; text: string }[]; cursor?: number };
+     *   }[];
+     *   cursor?: number;
+     * };
+     *
+     * const postsWithComments: Result = await db.post
+     *   .select('id', 'text')
+     *   .select({
+     *     comments: (q) =>
+     *       q.comments
+     *         .select('id', 'text')
+     *         .transform((nodes) => ({ nodes, cursor: nodes.at(-1)?.id })),
+     *   })
+     *   .transform((nodes) => ({ nodes, cursor: nodes.at(-1)?.id }));
+     * ```
+     *
+     * @param fn - function to transform query result with
+     */
+    transform<T extends Query, Fn extends TransformFn<T>>(this: T, fn: Fn): QueryTransform<T, Fn>;
+    _transform<T extends Query, Fn extends TransformFn<T>>(this: T, fn: Fn): QueryTransform<T, Fn>;
+}
+
 type WindowArg<T extends Query> = Record<string, WindowArgDeclaration<T> | RawExpression>;
 type WindowArgDeclaration<T extends Query = Query> = {
     partitionBy?: Expression<T> | Expression<T>[];
@@ -2552,7 +2771,7 @@ type FindArgs<T extends Query> = [T['shape'][T['singlePrimaryKey']]['type'] | Ra
 type QueryHelper<T extends Query, Args extends unknown[], Result> = <Q extends {
     [K in keyof T]: K extends 'then' ? QueryThen<unknown> : K extends 'result' ? ColumnsShapeBase : T[K];
 }>(q: Q, ...args: Args) => Result extends Query ? MergeQuery<Q, Result> : Result;
-interface QueryMethods extends Omit<AsMethods, 'result'>, Aggregate, Select, From, Join, With, Union, Omit<JsonModifiers, 'result'>, JsonMethods, Create, Update, Delete, Transaction, For, ColumnInfoMethods, Omit<Where, 'result'>, Clear, Having, Window, Then, QueryLog, QueryHooks, QueryUpsertOrCreate, QueryGet, MergeQueryMethods, RawSqlMethods, CopyMethods {
+interface QueryMethods extends Omit<AsMethods, 'result'>, Aggregate, Select, From, Join, With, Union, Omit<JsonModifiers, 'result'>, JsonMethods, Create, Update, Delete, Transaction, For, ColumnInfoMethods, Omit<Where, 'result'>, Clear, Having, Window, Then, QueryLog, QueryHooks, QueryUpsertOrCreate, QueryGet, MergeQueryMethods, RawSqlMethods, CopyMethods, TransformMethods {
 }
 declare class QueryMethods {
     windows: EmptyObject;
@@ -2629,6 +2848,22 @@ declare class QueryMethods {
     exec<T extends Query>(this: T): SetQueryReturnsVoid<T>;
     _exec<T extends Query>(this: T): SetQueryReturnsVoid<T>;
     toSql(this: Query, options?: ToSqlOptions): Sql;
+    /**
+     * Adds a `DISTINCT` keyword to `SELECT`:
+     *
+     * ```ts
+     * db.table.distinct().select('name');
+     * ```
+     *
+     * Can accept column names or raw expressions to place it to `DISTINCT ON (...)`:
+     *
+     * ```ts
+     * // Distinct on the name and raw SQL
+     * db.table.distinct('name', db.table.sql`raw sql`).select('id', 'name');
+     * ```
+     *
+     * @param columns - column names or a raw SQL
+     */
     distinct<T extends Query>(this: T, ...columns: Expression<T>[]): T;
     _distinct<T extends Query>(this: T, ...columns: Expression<T>[]): T;
     /**
@@ -2703,20 +2938,108 @@ declare class QueryMethods {
      */
     withSchema<T extends Query>(this: T, schema: string): T;
     _withSchema<T extends Query>(this: T, schema: string): T;
+    /**
+     * For the `GROUP BY` SQL statement, it is accepting column names or raw expressions.
+     *
+     * `group` is useful when aggregating values.
+     *
+     * ```ts
+     * // Select the category and sum of prices grouped by the category
+     * const results = Product.select('category')
+     *   .selectSum('price', { as: 'sumPrice' })
+     *   .group('category');
+     * ```
+     *
+     * @param columns - column names or a raw SQL
+     */
     group<T extends Query>(this: T, ...columns: Expression<T>[]): T;
     _group<T extends Query>(this: T, ...columns: Expression<T>[]): T;
     window<T extends Query, W extends WindowArg<T>>(this: T, arg: W): WindowResult<T, W>;
     _window<T extends Query, W extends WindowArg<T>>(this: T, arg: W): WindowResult<T, W>;
     wrap<T extends Query, Q extends Query, As extends string = 't'>(this: T, query: Q, as?: As): SetQueryTableAlias<Q, As>;
     _wrap<T extends Query, Q extends Query, As extends string = 't'>(this: T, query: Q, as?: As): SetQueryTableAlias<Q, As>;
+    /**
+     * Adds an order by clause to the query.
+     *
+     * Takes one or more arguments, each argument can be a column name, an object, or a raw expression.
+     *
+     * ```ts
+     * db.table.order('id', 'name'); // ASC by default
+     *
+     * db.table.order({
+     *   id: 'ASC', // or DESC
+     *
+     *   // to set nulls order:
+     *   name: 'ASC NULLS FIRST',
+     *   age: 'DESC NULLS LAST',
+     * });
+     *
+     * // order by raw SQL expression:
+     * db.table.order`raw sql`;
+     * // or
+     * db.table.order(db.table.sql`raw sql`);
+     * ```
+     *
+     * `order` can refer to the values returned from `select` sub-queries (unlike `where` which cannot).
+     * So you can select a count of related records and order by it.
+     *
+     * For example, `comment` has many `likes`.
+     * We are selecting few columns of `comment`, selecting `likesCount` by a sub-query in a select, and ordering comments by likes count:
+     *
+     * ```ts
+     * db.comment
+     *   .select('title', 'content', {
+     *     likesCount: (q) => q.likes.count(),
+     *   })
+     *   .order({
+     *     likesCount: 'DESC',
+     *   });
+     * ```
+     *
+     * @param args - column name(s), raw SQL, or an object with column names and sort directions.
+     */
     order<T extends Query>(this: T, ...args: OrderArgs<T>): T;
     _order<T extends Query>(this: T, ...args: OrderArgs<T>): T;
+    /**
+     * Adds a limit clause to the query.
+     *
+     * ```ts
+     * db.table.limit(10);
+     * ```
+     *
+     * @param arg - limit number
+     */
     limit<T extends Query>(this: T, arg: number | undefined): T;
     _limit<T extends Query>(this: T, arg: number | undefined): T;
+    /**
+     * Adds an offset clause to the query.
+     *
+     * ```ts
+     * db.table.offset(10);
+     * ```
+     *
+     * @param arg - offset number
+     */
     offset<T extends Query>(this: T, arg: number | undefined): T;
     _offset<T extends Query>(this: T, arg: number | undefined): T;
     exists<T extends Query>(this: T): SetQueryReturnsColumn<T, BooleanColumn>;
     _exists<T extends Query>(this: T): SetQueryReturnsColumn<T, BooleanColumn>;
+    /**
+     * Truncates the specified table.
+     *
+     * ```ts
+     * // simply truncate
+     * await db.table.truncate();
+     *
+     * // restart autoincrementing columns:
+     * await db.table.truncate({ restartIdentity: true });
+     *
+     * // truncate also dependant tables:
+     * await db.table.truncate({ cascade: true });
+     * ```
+     *
+     * @param options - truncate options, may have `cascade: true` and `restartIdentity: true`
+     */
     truncate<T extends Query>(this: T, options?: {
         restartIdentity?: boolean;
         cascade?: boolean;