chore: fix jsdoc errors and add some examples, pt. 3. (#1279)

deno.check.d.ts

@@ -5,10 +5,11 @@ import type {
   Insertable,
   Kysely,
   Selectable,
+  SqlBool,
   Updateable,
 } from './dist/esm'
 
-interface Database {
+export interface Database {
   person: PersonTable
   pet: PetTable
   toy: ToyTable
@@ -36,11 +37,13 @@ interface PersonTable {
     website: { url: string }
   } | null
   updated_at: ColumnType<Date | null, string | null | undefined, string | null>
+  marital_status: 'single' | 'married' | 'divorced' | 'widowed' | null
 }
 
 interface PetTable {
   id: Generated<number>
-  is_favorite: Generated<boolean>
+  created_at: GeneratedAlways<Date>
+  is_favorite: Generated<SqlBool>
   name: string
   owner_id: number
   species: Species

deno.check.json

@@ -6,7 +6,11 @@
   "imports": {
     "better-sqlite3": "npm:better-sqlite3",
     "kysely": "./dist/esm",
+    "kysely/helpers/mssql": "./dist/esm/helpers/mssql.js",
+    "kysely/helpers/mysql": "./dist/esm/helpers/mysql.js",
     "kysely/helpers/postgres": "./dist/esm/helpers/postgres.js",
+    "kysely/helpers/sqlite": "./dist/esm/helpers/sqlite.js",
+    "lodash/snakeCase": "npm:lodash/snakeCase",
     "mysql2": "npm:mysql2",
     "pg": "npm:pg",
     "pg-cursor": "npm:pg-cursor",

src/dialect/dialect-adapter.ts

@@ -57,10 +57,13 @@ export interface DialectAdapter {
    * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
    *
    * ```ts
-   * import { DialectAdapterBase, MigrationLockOptions, Kysely } from 'kysely'
+   * import { DialectAdapterBase, type MigrationLockOptions, Kysely } from 'kysely'
    *
    * export class MyAdapter extends DialectAdapterBase {
-   *   async override acquireMigrationLock(db: Kysely<any>, options: MigrationLockOptions): Promise<void> {
+   *   override async acquireMigrationLock(
+   *     db: Kysely<any>,
+   *     options: MigrationLockOptions
+   *   ): Promise<void> {
    *     const queryDb = options.lockTableSchema
    *       ? db.withSchema(options.lockTableSchema)
    *       : db
@@ -76,6 +79,10 @@ export interface DialectAdapter {
    *       .forUpdate()
    *       .execute()
    *   }
+   *
+   *   override async releaseMigrationLock() {
+   *     // noop
+   *   }
    * }
    * ```
    *

src/dialect/mssql/mssql-adapter.ts

@@ -4,19 +4,19 @@ import { sql } from '../../raw-builder/sql.js'
 import { DialectAdapterBase } from '../dialect-adapter-base.js'
 
 export class MssqlAdapter extends DialectAdapterBase {
-  get supportsCreateIfNotExists(): boolean {
+  override get supportsCreateIfNotExists(): boolean {
     return false
   }
 
-  get supportsTransactionalDdl(): boolean {
+  override get supportsTransactionalDdl(): boolean {
     return true
   }
 
-  get supportsOutput(): boolean {
+  override get supportsOutput(): boolean {
     return true
   }
 
-  async acquireMigrationLock(db: Kysely<any>): Promise<void> {
+  override async acquireMigrationLock(db: Kysely<any>): Promise<void> {
     // Acquire a transaction-level exclusive lock on the migrations table.
     // https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-getapplock-transact-sql?view=sql-server-ver16
     await sql`exec sp_getapplock @DbPrincipal = ${sql.lit(
@@ -26,7 +26,7 @@ export class MssqlAdapter extends DialectAdapterBase {
     )}`.execute(db)
   }
 
-  async releaseMigrationLock(): Promise<void> {
+  override async releaseMigrationLock(): Promise<void> {
     // Nothing to do here. `sp_getapplock` is automatically released at the
     // end of the transaction and since `supportsTransactionalDdl` true, we know
     // the `db` instance passed to acquireMigrationLock is actually a transaction.

src/dialect/mssql/mssql-dialect-config.ts

@@ -6,21 +6,23 @@ export interface MssqlDialectConfig {
    * (excluding `create`, `destroy` and `validate` functions which are controlled by this dialect),
    * `min` & `max` connections at the very least.
    *
-   * Example:
+   * ### Examples
    *
    * ```ts
+   * import { MssqlDialect } from 'kysely'
    * import * as Tarn from 'tarn'
+   * import * as Tedious from 'tedious'
    *
    * const dialect = new MssqlDialect({
-   *   // ...
-   *   tarn: {
-   *     ...Tarn,
-   *     options: {
+   *   tarn: { ...Tarn, options: { max: 10, min: 0 } },
+   *   tedious: {
+   *     ...Tedious,
+   *     connectionFactory: () => new Tedious.Connection({
    *       // ...
-   *       min: 0,
-   *       max: 10,
-   *     },
-   *   },
+   *       server: 'localhost',
+   *       // ...
+   *     }),
+   *   }
    * })
    * ```
    */
@@ -32,19 +34,23 @@ export interface MssqlDialectConfig {
    * you need to pass the `tedious` package itself. You also need to pass a factory
    * function that creates new `tedious` `Connection` instances on demand.
    *
-   * Example:
+   * ### Examples
    *
    * ```ts
+   * import { MssqlDialect } from 'kysely'
+   * import * as Tarn from 'tarn'
    * import * as Tedious from 'tedious'
    *
    * const dialect = new MssqlDialect({
-   *   // ...
+   *   tarn: { ...Tarn, options: { max: 10, min: 0 } },
    *   tedious: {
    *     ...Tedious,
    *     connectionFactory: () => new Tedious.Connection({
    *       // ...
+   *       server: 'localhost',
+   *       // ...
    *     }),
-   *   },
+   *   }
    * })
    * ```
    */
@@ -163,20 +169,6 @@ export interface Tarn {
 
   /**
    * Tarn.js' Pool class.
-   *
-   * Example:
-   *
-   * ```ts
-   * import { Pool } from 'tarn'
-   *
-   * const dialect = new MssqlDialect({
-   *   // ...
-   *   tarn: {
-   *     // ...
-   *     Pool,
-   *   },
-   * })
-   * ```
    */
   Pool: typeof TarnPool
 }

src/dialect/mysql/mysql-adapter.ts

@@ -7,15 +7,15 @@ const LOCK_ID = 'ea586330-2c93-47c8-908d-981d9d270f9d'
 const LOCK_TIMEOUT_SECONDS = 60 * 60
 
 export class MysqlAdapter extends DialectAdapterBase {
-  get supportsTransactionalDdl(): boolean {
+  override get supportsTransactionalDdl(): boolean {
     return false
   }
 
-  get supportsReturning(): boolean {
+  override get supportsReturning(): boolean {
     return false
   }
 
-  async acquireMigrationLock(
+  override async acquireMigrationLock(
     db: Kysely<any>,
     _opt: MigrationLockOptions,
   ): Promise<void> {
@@ -30,7 +30,7 @@ export class MysqlAdapter extends DialectAdapterBase {
     )})`.execute(db)
   }
 
-  async releaseMigrationLock(
+  override async releaseMigrationLock(
     db: Kysely<any>,
     _opt: MigrationLockOptions,
   ): Promise<void> {

src/dialect/postgres/postgres-adapter.ts

@@ -7,23 +7,23 @@ import { MigrationLockOptions } from '../dialect-adapter.js'
 const LOCK_ID = BigInt('3853314791062309107')
 
 export class PostgresAdapter extends DialectAdapterBase {
-  get supportsTransactionalDdl(): boolean {
+  override get supportsTransactionalDdl(): boolean {
     return true
   }
 
-  get supportsReturning(): boolean {
+  override get supportsReturning(): boolean {
     return true
   }
 
-  async acquireMigrationLock(
+  override async acquireMigrationLock(
     db: Kysely<any>,
     _opt: MigrationLockOptions,
   ): Promise<void> {
     // Acquire a transaction level advisory lock.
     await sql`select pg_advisory_xact_lock(${sql.lit(LOCK_ID)})`.execute(db)
   }
 
-  async releaseMigrationLock(
+  override async releaseMigrationLock(
     _db: Kysely<any>,
     _opt: MigrationLockOptions,
   ): Promise<void> {

src/dialect/postgres/postgres-dialect-config.ts

@@ -15,13 +15,16 @@ export interface PostgresDialectConfig {
 
   /**
    * https://github.com/brianc/node-postgres/tree/master/packages/pg-cursor
+   *
    * ```ts
+   * import { PostgresDialect } from 'kysely'
+   * import { Pool } from 'pg'
    * import Cursor from 'pg-cursor'
-   * // or
-   * import * as Cursor from 'pg-cursor'
+   * // or import * as Cursor from 'pg-cursor'
    *
    * new PostgresDialect({
-   *  cursor: Cursor
+   *  cursor: Cursor,
+   *  pool: new Pool('postgres://localhost:5432/mydb')
    * })
    * ```
    */

src/dialect/sqlite/sqlite-adapter.ts

@@ -3,15 +3,15 @@ import { DialectAdapterBase } from '../dialect-adapter-base.js'
 import { MigrationLockOptions } from '../dialect-adapter.js'
 
 export class SqliteAdapter extends DialectAdapterBase {
-  get supportsTransactionalDdl(): boolean {
+  override get supportsTransactionalDdl(): boolean {
     return false
   }
 
-  get supportsReturning(): boolean {
+  override get supportsReturning(): boolean {
     return true
   }
 
-  async acquireMigrationLock(
+  override async acquireMigrationLock(
     _db: Kysely<any>,
     _opt: MigrationLockOptions,
   ): Promise<void> {
@@ -20,7 +20,7 @@ export class SqliteAdapter extends DialectAdapterBase {
     // We don't need to do anything here.
   }
 
-  async releaseMigrationLock(
+  override async releaseMigrationLock(
     _db: Kysely<any>,
     _opt: MigrationLockOptions,
   ): Promise<void> {

src/driver/dummy-driver.ts

@@ -11,20 +11,21 @@ import { Driver } from './driver.js'
  * This example creates a Kysely instance for building postgres queries:
  *
  * ```ts
+ * import {
+ *   DummyDriver,
+ *   Kysely,
+ *   PostgresAdapter,
+ *   PostgresIntrospector,
+ *   PostgresQueryCompiler
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
  * const db = new Kysely<Database>({
  *   dialect: {
- *     createAdapter() {
- *       return new PostgresAdapter()
- *     },
- *     createDriver() {
- *       return new DummyDriver()
- *     },
- *     createIntrospector(db: Kysely<any>) {
- *       return new PostgresIntrospector(db)
- *     },
- *     createQueryCompiler() {
- *       return new PostgresQueryCompiler()
- *     },
+ *     createAdapter: () => new PostgresAdapter(),
+ *     createDriver: () => new DummyDriver(),
+ *     createIntrospector: (db: Kysely<any>) => new PostgresIntrospector(db),
+ *     createQueryCompiler: () => new PostgresQueryCompiler(),
  *   },
  * })
  * ```

src/dynamic/dynamic.ts

@@ -62,11 +62,11 @@ export class DynamicModule {
    * const { ref } = db.dynamic
    *
    * // Some column name provided by the user. Value not known at compile time.
-   * const columnFromUserInput = req.query.select;
+   * const columnFromUserInput: PossibleColumns = 'birthdate';
    *
    * // A type that lists all possible values `columnFromUserInput` can have.
    * // You can use `keyof Person` if any column of an interface is allowed.
-   * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
+   * type PossibleColumns = 'last_name' | 'first_name' | 'birthdate'
    *
    * const [person] = await db.selectFrom('person')
    *   .select([
@@ -78,12 +78,12 @@ export class DynamicModule {
    * // The resulting type contains all `PossibleColumns` as optional fields
    * // because we cannot know which field was actually selected before
    * // running the code.
-   * const lastName: string | undefined = person.last_name
-   * const firstName: string | undefined = person.first_name
-   * const birthDate: string | undefined = person.birth_date
+   * const lastName: string | null | undefined = person?.last_name
+   * const firstName: string | undefined = person?.first_name
+   * const birthDate: Date | null | undefined = person?.birthdate
    *
    * // The result type also contains the compile time selection `id`.
-   * person.id
+   * person?.id
    * ```
    */
   ref<R extends string = never>(reference: string): DynamicReferenceBuilder<R> {