fix jsdocs.

kysely-org · Dec 1, 2024 · 1c5e03a · 1c5e03a
1 parent f348dfb
commit 1c5e03a
Show file tree

Hide file tree

Showing 4 changed files with 82 additions and 37 deletions.
diff --git a/deno.check.d.ts b/deno.check.d.ts
@@ -10,13 +10,18 @@ import type {
 } from './dist/esm'
 
 export interface Database {
+  audit: AuditTable
   person: PersonTable
   pet: PetTable
   toy: ToyTable
   wine: WineTable
   wine_stock_change: WineStockChangeTable
 }
 
+interface AuditTable {
+  action: string
+}
+
 interface PersonTable {
   id: Generated<number>
   address: { city: string } | null
@@ -51,6 +56,7 @@ interface PetTable {
 
 interface ToyTable {
   id: Generated<number>
+  name: string
   pet_id: number
   price: number
 }

diff --git a/src/kysely.ts b/src/kysely.ts
@@ -341,7 +341,7 @@ export class Kysely<DB>
    *
    *   await trx.commit().execute()
    *
-   *   return catto
+   *   // ...
    * } catch (error) {
    *   await trx.rollback().execute()
    * }
@@ -375,20 +375,19 @@ export class Kysely<DB>
    *   const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
    *
    *   try {
-   *     const bone = await trxAfterJennifer
-   *       .insertInto('toy')
-   *       .values({ name: 'Bone', price: 1.99 })
-   *       .returning('id')
-   *       .executeTakeFirstOrThrow()
-   *
-   *     await trxAfterJennifer
+   *     const catto = await trxAfterJennifer
    *       .insertInto('pet')
    *       .values({
    *         owner_id: jennifer.id,
    *         name: 'Catto',
    *         species: 'cat',
-   *         favorite_toy_id: bone.id,
    *       })
+   *       .returning('id')
+   *       .executeTakeFirstOrThrow()
+   *
+   *     await trxAfterJennifer
+   *       .insertInto('toy')
+   *       .values({ name: 'Bone', price: 1.99, pet_id: catto.id })
    *       .execute()
    *   } catch (error) {
    *     await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
@@ -838,13 +837,20 @@ export class ControlledTransaction<
    * ### Examples
    *
    * ```ts
+   * import type { Kysely } from 'kysely'
+   * import type { Database } from 'type-editor' // imaginary module
+   *
+   * const trx = await db.startTransaction().execute()
+   *
    * try {
    *   await doSomething(trx)
    *
    *   await trx.commit().execute()
    * } catch (error) {
    *   await trx.rollback().execute()
    * }
+   *
+   * async function doSomething(kysely: Kysely<Database>) {}
    * ```
    */
   commit(): Command<void> {
@@ -865,13 +871,20 @@ export class ControlledTransaction<
    * ### Examples
    *
    * ```ts
+   * import type { Kysely } from 'kysely'
+   * import type { Database } from 'type-editor' // imaginary module
+   *
+   * const trx = await db.startTransaction().execute()
+   *
    * try {
    *   await doSomething(trx)
    *
    *   await trx.commit().execute()
    * } catch (error) {
    *   await trx.rollback().execute()
    * }
+   *
+   * async function doSomething(kysely: Kysely<Database>) {}
    * ```
    */
   rollback(): Command<void> {
@@ -894,15 +907,23 @@ export class ControlledTransaction<
    * ### Examples
    *
    * ```ts
-   *   await insertJennifer(trx)
+   * import type { Kysely } from 'kysely'
+   * import type { Database } from 'type-editor' // imaginary module
    *
-   *   const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+   * const trx = await db.startTransaction().execute()
    *
-   *   try {
-   *     await doSomething(trxAfterJennifer)
-   *   } catch (error) {
-   *     await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
-   *   }
+   * await insertJennifer(trx)
+   *
+   * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+   *
+   * try {
+   *   await doSomething(trxAfterJennifer)
+   * } catch (error) {
+   *   await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
+   * }
+   *
+   * async function insertJennifer(kysely: Kysely<Database>) {}
+   * async function doSomething(kysely: Kysely<Database>) {}
    * ```
    */
   savepoint<SN extends string>(
@@ -932,15 +953,23 @@ export class ControlledTransaction<
    * ### Examples
    *
    * ```ts
-   *   await insertJennifer(trx)
+   * import type { Kysely } from 'kysely'
+   * import type { Database } from 'type-editor' // imaginary module
    *
-   *   const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+   * const trx = await db.startTransaction().execute()
    *
-   *   try {
-   *     await doSomething(trxAfterJennifer)
-   *   } catch (error) {
-   *     await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
-   *   }
+   * await insertJennifer(trx)
+   *
+   * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+   *
+   * try {
+   *   await doSomething(trxAfterJennifer)
+   * } catch (error) {
+   *   await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
+   * }
+   *
+   * async function insertJennifer(kysely: Kysely<Database>) {}
+   * async function doSomething(kysely: Kysely<Database>) {}
    * ```
    */
   rollbackToSavepoint<SN extends S[number]>(
@@ -972,19 +1001,28 @@ export class ControlledTransaction<
    * ### Examples
    *
    * ```ts
-   *   await insertJennifer(trx)
+   * import type { Kysely } from 'kysely'
+   * import type { Database } from 'type-editor' // imaginary module
    *
-   *   const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+   * const trx = await db.startTransaction().execute()
    *
-   *   try {
-   *     await doSomething(trxAfterJennifer)
-   *   } catch (error) {
-   *     await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
-   *   }
+   * await insertJennifer(trx)
    *
-   *   await trxAfterJennifer.releaseSavepoint('after_jennifer').execute()
+   * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+   *
+   * try {
+   *   await doSomething(trxAfterJennifer)
+   * } catch (error) {
+   *   await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
+   * }
+   *
+   * await trxAfterJennifer.releaseSavepoint('after_jennifer').execute()
+   *
+   * await doSomethingElse(trx)
    *
-   *   await doSomethingElse(trx)
+   * async function insertJennifer(kysely: Kysely<Database>) {}
+   * async function doSomething(kysely: Kysely<Database>) {}
+   * async function doSomethingElse(kysely: Kysely<Database>) {}
    * ```
    */
   releaseSavepoint<SN extends S[number]>(

diff --git a/src/query-builder/select-query-builder.ts b/src/query-builder/select-query-builder.ts
@@ -259,7 +259,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O>
    *     ]).as('is_jennifer_or_arnold'),
    *
    *     // Select a raw sql expression
-   *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name').
+   *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
    *
    *     // Select a static string value
    *     val('Some value').as('string_value'),
@@ -1961,13 +1961,15 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O>
    * instances as inputs:
    *
    * ```ts
+   * import type { Expression } from 'kysely'
+   *
    * function doStuff(expr: Expression<string>) {
-   *   ...
+   *   // ...
    * }
    *
    * // Error! This is not ok because the expression type is
    * // `{ first_name: string }` instead of `string`.
-   * doStuff(db.selectFrom('person').select('first_name'))
+   * // doStuff(db.selectFrom('person').select('first_name'))
    *
    * // Ok! This is ok since we've plucked the `string` type of the
    * // only column in the output type.

diff --git a/src/query-builder/update-query-builder.ts b/src/query-builder/update-query-builder.ts
@@ -54,7 +54,6 @@ import {
   NoResultError,
   NoResultErrorConstructor,
 } from './no-result-error.js'
-import { Selectable } from '../util/column-type.js'
 import { Explainable, ExplainFormat } from '../util/explainable.js'
 import { AliasedExpression, Expression } from '../expression/expression.js'
 import {
@@ -649,7 +648,7 @@ export class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O>
    *   .set('person.first_name', 'Updated person')
    *   .set('pet.name', 'Updated doggo')
    *   .whereRef('person.id', '=', 'pet.owner_id')
-   *   .where('person.id', '=', '1')
+   *   .where('person.id', '=', 1)
    *   .executeTakeFirst()
    * ```
    *