Skip to content

Commit

Permalink
chore: fix jsdoc errors and add some examples, pt. 2. (#1277)
Browse files Browse the repository at this point in the history
  • Loading branch information
@igalklebanov
igalklebanov authored Nov 24, 2024
1 parent c2d65e0 commit 671699f
Show file tree
Hide file tree
Showing 15 changed files with 726 additions and 275 deletions.
9 changes: 8 additions & 1 deletion deno.check.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import type {
interface Database {
person: PersonTable
pet: PetTable
toy: ToyTable
wine: WineTable
wine_stock_change: WineStockChangeTable
}
Expand Down Expand Up @@ -45,6 +46,12 @@ interface PetTable {
species: Species
}

interface ToyTable {
id: Generated<number>
pet_id: number
price: number
}

interface WineTable {
name: string
stock: number
Expand All @@ -61,7 +68,7 @@ export type PersonUpdate = Updateable<PersonTable>
export type Pet = Selectable<PetTable>
export type NewPet = Insertable<PetTable>
export type PetUpdate = Updateable<PetTable>
export type Species = 'dog' | 'cat'
export type Species = 'dog' | 'cat' | 'hamster'

declare global {
// @ts-ignore
Expand Down
123 changes: 35 additions & 88 deletions src/query-builder/function-module.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,9 +106,10 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('person')
* await db.selectFrom('person')
* .selectAll('person')
* .where(db.fn('upper', ['first_name']), '=', 'JENNIFER')
* .execute()
* ```
*
* The generated SQL (PostgreSQL):
Expand All @@ -122,9 +123,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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<string>`upper(first_name)`, '=', 'JENNIFER')
* .execute()
* ```
*/
<O, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(
Expand All @@ -145,11 +149,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('person')
* await db.selectFrom('person')
* .select(({ fn }) => [
* fn.agg<number>('rank').over().as('rank'),
* fn.agg<string>('group_concat', ['first_name']).distinct().as('first_names')
* ])
* .execute()
* ```
*
* The generated SQL (MySQL):
Expand Down Expand Up @@ -177,7 +182,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.avg('price').as('avg_price'))
* .execute()
* ```
Expand All @@ -188,14 +193,6 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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
Expand All @@ -207,7 +204,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* the first type argument:
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.avg<number>('price').as('avg_price'))
* .execute()
* ```
Expand All @@ -218,7 +215,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* function.
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.avg<number | null>('price').as('avg_price'))
* .execute()
* ```
Expand Down Expand Up @@ -251,35 +248,25 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('participant')
* .select((eb) => eb.fn.coalesce('nickname', sql<string>`'<anonymous>'`).as('nickname'))
* .where('room_id', '=', roomId)
* import { sql } from 'kysely'
*
* await db.selectFrom('person')
* .select((eb) => eb.fn.coalesce('nullable_column', sql.lit('<unknown>')).as('column'))
* .where('first_name', '=', 'Jessie')
* .execute()
* ```
*
* The generated SQL (PostgreSQL):
*
* ```sql
* select coalesce("nickname", '<anonymous>') 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<string>`'<anonymous>'`).as('nickname')
* )
* .where('room_id', '=', roomId)
* .execute()
* select coalesce("nullable_column", '<unknown>') 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<number | null>('age'), sql<number>`0`).as('avg_age'))
* await db.selectFrom('person')
* .select((eb) => eb.fn.coalesce(eb.fn.avg<number | null>('age'), eb.lit(0)).as('avg_age'))
* .where('first_name', '=', 'Jennifer')
* .execute()
* ```
Expand Down Expand Up @@ -357,7 +344,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.count('id').as('num_toys'))
* .execute()
* ```
Expand All @@ -379,18 +366,10 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* the type as the first type argument:
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.count<number>('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,
Expand All @@ -415,7 +394,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.countAll().as('num_toys'))
* .execute()
* ```
Expand All @@ -437,7 +416,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* the type as the first type argument:
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.countAll<number>().as('num_toys'))
* .execute()
* ```
Expand All @@ -446,7 +425,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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()
Expand All @@ -458,15 +437,6 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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<O extends number | string | bigint, T extends TB = TB>(
table: T,
Expand Down Expand Up @@ -494,7 +464,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.max('price').as('max_price'))
* .execute()
* ```
Expand All @@ -505,21 +475,13 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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<number | null>('price').as('max_price'))
* .execute()
* ```
Expand Down Expand Up @@ -553,7 +515,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.min('price').as('min_price'))
* .execute()
* ```
Expand All @@ -564,21 +526,13 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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<number | null>('price').as('min_price'))
* .execute()
* ```
Expand Down Expand Up @@ -608,7 +562,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* ### Examples
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.sum('price').as('total_price'))
* .execute()
* ```
Expand All @@ -619,14 +573,6 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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
Expand All @@ -638,7 +584,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* the first type argument:
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.sum<number>('price').as('total_price'))
* .execute()
* ```
Expand All @@ -649,7 +595,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* function.
*
* ```ts
* db.selectFrom('toy')
* await db.selectFrom('toy')
* .select((eb) => eb.fn.sum<number | null>('price').as('total_price'))
* .execute()
* ```
Expand All @@ -671,11 +617,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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()
* ```
*
*
Expand Down Expand Up @@ -711,7 +658,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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')
Expand Down Expand Up @@ -745,7 +692,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
* 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()
Expand Down
Loading

0 comments on commit 671699f

Please sign in to comment.