From dbf184dbffd460a76e9094643f63c58b5812479c Mon Sep 17 00:00:00 2001 From: igalklebanov Date: Sun, 24 Nov 2024 02:07:30 +0200 Subject: [PATCH] fix jsdocs @ function-module. --- deno.check.d.ts | 7 ++ src/query-builder/function-module.ts | 123 ++++++++------------------- 2 files changed, 42 insertions(+), 88 deletions(-) diff --git a/deno.check.d.ts b/deno.check.d.ts index 9a285dcae..48196b508 100644 --- a/deno.check.d.ts +++ b/deno.check.d.ts @@ -11,6 +11,7 @@ import type { interface Database { person: PersonTable pet: PetTable + toy: ToyTable wine: WineTable wine_stock_change: WineStockChangeTable } @@ -45,6 +46,12 @@ interface PetTable { species: Species } +interface ToyTable { + id: Generated + pet_id: number + price: number +} + interface WineTable { name: string stock: number diff --git a/src/query-builder/function-module.ts b/src/query-builder/function-module.ts index bb8748dd6..cfb7cda3c 100644 --- a/src/query-builder/function-module.ts +++ b/src/query-builder/function-module.ts @@ -106,9 +106,10 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('person') + * await db.selectFrom('person') * .selectAll('person') * .where(db.fn('upper', ['first_name']), '=', 'JENNIFER') + * .execute() * ``` * * The generated SQL (PostgreSQL): @@ -122,9 +123,12 @@ export interface FunctionModule { * If you prefer readability over type-safety, you can always use raw `sql`: * * ```ts - * db.selectFrom('person') + * import { sql } from 'kysely' + * + * await db.selectFrom('person') * .selectAll('person') * .where(sql`upper(first_name)`, '=', 'JENNIFER') + * .execute() * ``` */ = ReferenceExpression>( @@ -145,11 +149,12 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('person') + * await db.selectFrom('person') * .select(({ fn }) => [ * fn.agg('rank').over().as('rank'), * fn.agg('group_concat', ['first_name']).distinct().as('first_names') * ]) + * .execute() * ``` * * The generated SQL (MySQL): @@ -177,7 +182,7 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.avg('price').as('avg_price')) * .execute() * ``` @@ -188,14 +193,6 @@ export interface FunctionModule { * select avg("price") as "avg_price" from "toy" * ``` * - * You can limit column range to only columns participating in current query: - * - * ```ts - * db.selectFrom('toy') - * .select((eb) => eb.fn.avg('price').as('avg_price')) - * .execute() - * ``` - * * If this function is used in a `select` statement, the type of the selected * expression will be `number | string` by default. This is because Kysely can't know the * type the db driver outputs. Sometimes the output can be larger than the largest @@ -207,7 +204,7 @@ export interface FunctionModule { * the first type argument: * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.avg('price').as('avg_price')) * .execute() * ``` @@ -218,7 +215,7 @@ export interface FunctionModule { * function. * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.avg('price').as('avg_price')) * .execute() * ``` @@ -251,35 +248,25 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('participant') - * .select((eb) => eb.fn.coalesce('nickname', sql`''`).as('nickname')) - * .where('room_id', '=', roomId) + * import { sql } from 'kysely' + * + * await db.selectFrom('person') + * .select((eb) => eb.fn.coalesce('nullable_column', sql.lit('')).as('column')) + * .where('first_name', '=', 'Jessie') * .execute() * ``` * * The generated SQL (PostgreSQL): * * ```sql - * select coalesce("nickname", '') as "nickname" - * from "participant" where "room_id" = $1 - * ``` - * - * You can limit column range to only columns participating in current query: - * - * ```ts - * db.selectFrom('participant') - * .select((eb) => - * eb.fn.coalesce('nickname', sql`''`).as('nickname') - * ) - * .where('room_id', '=', roomId) - * .execute() + * select coalesce("nullable_column", '') as "column" from "person" where "first_name" = $1 * ``` * * You can combine this function with other helpers in this module: * * ```ts - * db.selectFrom('person') - * .select((eb) => eb.fn.coalesce(eb.fn.avg('age'), sql`0`).as('avg_age')) + * await db.selectFrom('person') + * .select((eb) => eb.fn.coalesce(eb.fn.avg('age'), eb.lit(0)).as('avg_age')) * .where('first_name', '=', 'Jennifer') * .execute() * ``` @@ -357,7 +344,7 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.count('id').as('num_toys')) * .execute() * ``` @@ -379,18 +366,10 @@ export interface FunctionModule { * the type as the first type argument: * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.count('id').as('num_toys')) * .execute() * ``` - * - * You can limit column range to only columns participating in current query: - * - * ```ts - * db.selectFrom('toy') - * .select((eb) => eb.fn.count('id').as('num_toys')) - * .execute() - * ``` */ count< O extends number | string | bigint, @@ -415,7 +394,7 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.countAll().as('num_toys')) * .execute() * ``` @@ -437,7 +416,7 @@ export interface FunctionModule { * the type as the first type argument: * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.countAll().as('num_toys')) * .execute() * ``` @@ -446,7 +425,7 @@ export interface FunctionModule { * table: * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .innerJoin('pet', 'pet.id', 'toy.pet_id') * .select((eb) => eb.fn.countAll('toy').as('num_toys')) * .execute() @@ -458,15 +437,6 @@ export interface FunctionModule { * select count("toy".*) as "num_toys" * from "toy" inner join "pet" on "pet"."id" = "toy"."pet_id" * ``` - * - * You can limit table range to only tables participating in current query: - * - * ```ts - * db.selectFrom('toy') - * .innerJoin('pet', 'pet.id', 'toy.pet_id') - * .select((eb) => eb.fn.countAll('toy').as('num_toys')) - * .execute() - * ``` */ countAll( table: T, @@ -494,7 +464,7 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.max('price').as('max_price')) * .execute() * ``` @@ -505,21 +475,13 @@ export interface FunctionModule { * select max("price") as "max_price" from "toy" * ``` * - * You can limit column range to only columns participating in current query: - * - * ```ts - * db.selectFrom('toy') - * .select((eb) => eb.fn.max('price').as('max_price')) - * .execute() - * ``` - * * Sometimes a null is returned, e.g. when row count is 0, and no `group by` * was used. It is highly recommended to include null in the output type union * and handle null values in post-execute code, or wrap the function with a {@link coalesce} * function. * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.max('price').as('max_price')) * .execute() * ``` @@ -553,7 +515,7 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.min('price').as('min_price')) * .execute() * ``` @@ -564,21 +526,13 @@ export interface FunctionModule { * select min("price") as "min_price" from "toy" * ``` * - * You can limit column range to only columns participating in current query: - * - * ```ts - * db.selectFrom('toy') - * .select((eb) => eb.fn.min('price').as('min_price')) - * .execute() - * ``` - * * Sometimes a null is returned, e.g. when row count is 0, and no `group by` * was used. It is highly recommended to include null in the output type union * and handle null values in post-execute code, or wrap the function with a {@link coalesce} * function. * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.min('price').as('min_price')) * .execute() * ``` @@ -608,7 +562,7 @@ export interface FunctionModule { * ### Examples * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.sum('price').as('total_price')) * .execute() * ``` @@ -619,14 +573,6 @@ export interface FunctionModule { * select sum("price") as "total_price" from "toy" * ``` * - * You can limit column range to only columns participating in current query: - * - * ```ts - * db.selectFrom('toy') - * .select((eb) => eb.fn.sum('price').as('total_price')) - * .execute() - * ``` - * * If this function is used in a `select` statement, the type of the selected * expression will be `number | string` by default. This is because Kysely can't know the * type the db driver outputs. Sometimes the output can be larger than the largest @@ -638,7 +584,7 @@ export interface FunctionModule { * the first type argument: * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.sum('price').as('total_price')) * .execute() * ``` @@ -649,7 +595,7 @@ export interface FunctionModule { * function. * * ```ts - * db.selectFrom('toy') + * await db.selectFrom('toy') * .select((eb) => eb.fn.sum('price').as('total_price')) * .execute() * ``` @@ -671,11 +617,12 @@ export interface FunctionModule { * In the following example, `nicknames` is assumed to be a column of type `string[]`: * * ```ts - * db.selectFrom('person') + * await db.selectFrom('person') * .selectAll('person') * .where((eb) => eb( * eb.val('Jen'), '=', eb.fn.any('person.nicknames') * )) + * .execute() * ``` * * @@ -711,7 +658,7 @@ export interface FunctionModule { * This function is only available on PostgreSQL. * * ```ts - * db.selectFrom('person') + * await db.selectFrom('person') * .innerJoin('pet', 'pet.owner_id', 'person.id') * .select((eb) => ['first_name', eb.fn.jsonAgg('pet').as('pets')]) * .groupBy('person.first_name') @@ -745,7 +692,7 @@ export interface FunctionModule { * This function is only available on PostgreSQL. * * ```ts - * db.selectFrom('person') + * await db.selectFrom('person') * .innerJoin('pet', 'pet.owner_id', 'person.id') * .select((eb) => ['first_name', eb.fn.toJson('pet').as('pet')]) * .execute()