From c80e5958981cd561bb8c0e6945d6a814a25399c0 Mon Sep 17 00:00:00 2001 From: igalklebanov Date: Sun, 24 Nov 2024 18:08:32 +0200 Subject: [PATCH] fix jsdocs @ kysely. --- src/kysely.ts | 110 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 72 insertions(+), 38 deletions(-) diff --git a/src/kysely.ts b/src/kysely.ts index 987c8947e..dcb978f3f 100644 --- a/src/kysely.ts +++ b/src/kysely.ts @@ -42,33 +42,23 @@ import { DrainOuterGeneric } from './util/type-utils.js' * * ### Examples * - * This example assumes your database has tables `person` and `pet`: + * This example assumes your database has a "person" table: * * ```ts - * import { Kysely, Generated, PostgresDialect } from 'kysely' - * - * interface PersonTable { - * id: Generated - * first_name: string - * last_name: string - * } - * - * interface PetTable { - * id: Generated - * owner_id: number - * name: string - * species: 'cat' | 'dog' - * } + * import * as Sqlite from 'better-sqlite3' + * import { type Generated, Kysely, SqliteDialect } from 'kysely' * * interface Database { - * person: PersonTable, - * pet: PetTable + * person: { + * id: Generated + * first_name: string + * last_name: string | null + * } * } * * const db = new Kysely({ - * dialect: new PostgresDialect({ - * host: 'localhost', - * database: 'kysely_test', + * dialect: new SqliteDialect({ + * database: new Sqlite(':memory:'), * }) * }) * ``` @@ -165,30 +155,52 @@ export class Kysely } /** - * Returns a {@link FunctionModule} that can be used to write type safe function + * Returns a {@link FunctionModule} that can be used to write somewhat type-safe function * calls. * * ```ts + * const { count } = db.fn + * * await db.selectFrom('person') * .innerJoin('pet', 'pet.owner_id', 'person.id') - * .select((eb) => [ - * 'person.id', - * eb.fn.count('pet.id').as('pet_count') + * .select([ + * 'id', + * count('pet.id').as('person_count'), * ]) * .groupBy('person.id') - * .having((eb) => eb.fn.count('pet.id'), '>', 10) + * .having(count('pet.id'), '>', 10) * .execute() * ``` * * The generated SQL (PostgreSQL): * * ```sql - * select "person"."id", count("pet"."id") as "pet_count" + * select "person"."id", count("pet"."id") as "person_count" * from "person" * inner join "pet" on "pet"."owner_id" = "person"."id" * group by "person"."id" * having count("pet"."id") > $1 * ``` + * + * Why "somewhat" type-safe? Because the function calls are not bound to the + * current query context. They allow you to reference columns and tables that + * are not in the current query. E.g. remove the `innerJoin` from the previous + * query and TypeScript won't even complain. + * + * If you want to make the function calls fully type-safe, you can use the + * {@link ExpressionBuilder.fn} getter for a query context-aware, stricter {@link FunctionModule}. + * + * ```ts + * await db.selectFrom('person') + * .innerJoin('pet', 'pet.owner_id', 'person.id') + * .select((eb) => [ + * 'person.id', + * eb.fn.count('pet.id').as('pet_count') + * ]) + * .groupBy('person.id') + * .having((eb) => eb.fn.count('pet.id'), '>', 10) + * .execute() + * ``` */ get fn(): FunctionModule { return createFunctionModule() @@ -248,12 +260,18 @@ export class Kysely * Setting the isolation level: * * ```ts + * import type { Kysely } from 'kysely' + * * await db * .transaction() * .setIsolationLevel('serializable') * .execute(async (trx) => { * await doStuff(trx) * }) + * + * async function doStuff(kysely: typeof db) { + * // ... + * } * ``` */ transaction(): TransactionBuilder { @@ -274,6 +292,10 @@ export class Kysely * // the same connection. * await doStuff(db) * }) + * + * async function doStuff(kysely: typeof db) { + * // ... + * } * ``` */ connection(): ConnectionBuilder { @@ -303,7 +325,7 @@ export class Kysely /** * @override */ - withSchema(schema: string): Kysely { + override withSchema(schema: string): Kysely { return new Kysely({ ...this.#props, executor: this.#props.executor.withPluginAtFront( @@ -323,7 +345,6 @@ export class Kysely * * The following example adds and uses a temporary table: * - * @example * ```ts * await db.schema * .createTable('temp_table') @@ -401,23 +422,23 @@ export class Transaction extends Kysely { // The return type is `true` instead of `boolean` to make Kysely // unassignable to Transaction while allowing assignment the // other way around. - get isTransaction(): true { + override get isTransaction(): true { return true } - transaction(): TransactionBuilder { + override transaction(): TransactionBuilder { throw new Error( 'calling the transaction method for a Transaction is not supported', ) } - connection(): ConnectionBuilder { + override connection(): ConnectionBuilder { throw new Error( 'calling the connection method for a Transaction is not supported', ) } - async destroy(): Promise { + override async destroy(): Promise { throw new Error( 'calling the destroy method for a Transaction is not supported', ) @@ -437,10 +458,7 @@ export class Transaction extends Kysely { }) } - /** - * @override - */ - withSchema(schema: string): Transaction { + override withSchema(schema: string): Transaction { return new Transaction({ ...this.#props, executor: this.#props.executor.withPluginAtFront( @@ -485,16 +503,32 @@ export interface KyselyConfig { * * ### Examples * + * Setting up built-in logging for preferred log levels: + * * ```ts + * import * as Sqlite from 'better-sqlite3' + * import { Kysely, SqliteDialect } from 'kysely' + * import type { Database } from 'type-editor' // imaginary module + * * const db = new Kysely({ - * dialect: new PostgresDialect(postgresConfig), + * dialect: new SqliteDialect({ + * database: new Sqlite(':memory:'), + * }), * log: ['query', 'error'] * }) * ``` * + * Setting up custom logging: + * * ```ts + * import * as Sqlite from 'better-sqlite3' + * import { Kysely, SqliteDialect } from 'kysely' + * import type { Database } from 'type-editor' // imaginary module + * * const db = new Kysely({ - * dialect: new PostgresDialect(postgresConfig), + * dialect: new SqliteDialect({ + * database: new Sqlite(':memory:'), + * }), * log(event): void { * if (event.level === 'query') { * console.log(event.query.sql)