chore: check jsdoc examples. (#1263)

.github/workflows/test.yml

@@ -82,17 +82,20 @@ jobs:
           node-version: 22.x
           cache: 'npm'
 
-      - name: Install dependencies
-        run: npm ci
-
       - name: Use Deno ${{ matrix.deno-version }}
         uses: denoland/setup-deno@v2
         with:
           deno-version: ${{ matrix.deno-version }}
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Run docker compose
         run: docker compose up -d
 
+      - name: Build
+        run: npm run build
+
       - name: Run deno tests
         run: npm run test:deno
 
@@ -210,3 +213,30 @@ jobs:
 
       - name: Run tests with older TypeScript
         run: npm run test:typings && npm run test:node:build
+
+  jsdocs:
+    name: JSDocs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: 'npm'
+
+      - name: Use Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: 2.0.x
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Type-check JSDocs code blocks
+        run: npm run test:jsdocs

deno.check.d.ts

@@ -0,0 +1,71 @@
+import type {
+  ColumnType,
+  Generated,
+  GeneratedAlways,
+  Insertable,
+  Kysely,
+  Selectable,
+  Updateable,
+} from './dist/esm'
+
+interface Database {
+  person: PersonTable
+  pet: PetTable
+  wine: WineTable
+  wine_stock_change: WineStockChangeTable
+}
+
+interface PersonTable {
+  id: Generated<number>
+  address: { city: string } | null
+  age: number | null
+  birthdate: ColumnType<Date | null, string | null | undefined, string | null>
+  created_at: GeneratedAlways<Date>
+  deleted_at: ColumnType<Date | null, string | null | undefined, string | null>
+  experience: { role: string }[] | null
+  first_name: string
+  gender: 'male' | 'female' | 'other' | null
+  has_pets: Generated<'Y' | 'N'>
+  last_name: string | null
+  middle_name: string | null
+  nicknames: string[] | null
+  nullable_column: string | null
+  profile: {
+    addresses: { city: string }[]
+    website: { url: string }
+  } | null
+  updated_at: ColumnType<Date | null, string | null | undefined, string | null>
+}
+
+interface PetTable {
+  id: Generated<number>
+  is_favorite: Generated<boolean>
+  name: string
+  owner_id: number
+  species: Species
+}
+
+interface WineTable {
+  name: string
+  stock: number
+}
+
+interface WineStockChangeTable {
+  stock_delta: number
+  wine_name: string
+}
+
+export type Person = Selectable<PersonTable>
+export type NewPerson = Insertable<PersonTable>
+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'
+
+declare global {
+  export const db: Kysely<Database>
+  export function functionThatExpectsPersonWithNonNullValue(
+    person: Person & { nullable_column: string },
+  ): void
+}

deno.check.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://deno.land/x/deno/cli/schemas/config-file.v1.json",
+  "compilerOptions": {
+    "types": ["./deno.check.d.ts"]
+  },
+  "imports": {
+    "better-sqlite3": "npm:better-sqlite3",
+    "kysely": "./dist/esm",
+    "kysely/helpers/postgres": "./dist/esm/helpers/postgres.js",
+    "mysql2": "npm:mysql2",
+    "pg": "npm:pg",
+    "pg-cursor": "npm:pg-cursor",
+    "tarn": "npm:tarn",
+    "tedious": "npm:tedious",
+    "type-editor": "./deno.check.d.ts"
+  }
+}

package.json

@@ -48,11 +48,12 @@
     "test:browser": "npm run build && npm run test:browser:build && node test/browser/test.js",
     "test:bun": "npm run build && bun link && cd test/bun && bun install && bun run test",
     "test:cloudflare-workers": "npm run build && cd test/cloudflare-workers && npm ci && npm test",
-    "test:deno": "npm run build && deno run --allow-env --allow-read --allow-net test/deno/local.test.ts && deno run --allow-env --allow-read --allow-net test/deno/cdn.test.ts",
+    "test:deno": "deno run --allow-env --allow-read --allow-net test/deno/local.test.ts && deno run --allow-env --allow-read --allow-net test/deno/cdn.test.ts",
     "test:typings": "tsd test/typings",
     "test:esmimports": "node scripts/check-esm-imports.js",
     "test:esbuild": "esbuild --bundle --platform=node --external:pg-native dist/esm/index.js --outfile=/dev/null",
     "test:exports": "attw --pack . && node scripts/check-exports.js",
+    "test:jsdocs": "deno check --doc-only --no-lock --unstable-sloppy-imports --config=\"deno.check.json\" ./src",
     "prettier": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
     "build": "npm run clean && (npm run build:esm & npm run build:cjs) && npm run script:module-fixup && npm run script:copy-interface-doc",
     "build:esm": "tsc -p tsconfig.json && npm run script:add-deno-type-references",

src/dialect/dialect-adapter.ts

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

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

@@ -41,7 +41,9 @@ export interface MssqlDialectConfig {
    *   // ...
    *   tedious: {
    *     ...Tedious,
-   *     connectionFactory: () => new Tedious.Connection({ ... }),
+   *     connectionFactory: () => new Tedious.Connection({
+   *       // ...
+   *     }),
    *   },
    * })
    * ```

src/expression/expression-builder.ts

@@ -995,7 +995,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
    * ```ts
    * db.selectFrom('person')
    *   .selectAll('person')
-   *   .where((eb) => eb(eb.parens('age', '+', 1), '/', 100), '<', 0.1))
+   *   .where((eb) => eb(eb.parens('age', '+', 1), '/', 100), '<', 0.1)
    * ```
    *
    * The generated SQL (PostgreSQL):
@@ -1015,7 +1015,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
    *     eb('age', '=', 1).or('age', '=', 2))
    *   ).and(
    *     eb('first_name', '=', 'Jennifer').or('first_name', '=', 'Arnold')
-   *   ))
+   *   )
    * ```
    *
    * The generated SQL (PostgreSQL):

src/expression/expression-wrapper.ts

@@ -54,7 +54,7 @@ export class ExpressionWrapper<DB, TB extends keyof DB, T>
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * select "first_name" = $1 as "is_jennifer"
    * from "person"
    * ```
@@ -85,7 +85,7 @@ export class ExpressionWrapper<DB, TB extends keyof DB, T>
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * select *
    * from "person"
    * where (
@@ -107,13 +107,13 @@ export class ExpressionWrapper<DB, TB extends keyof DB, T>
    *       eb.selectFrom('pet')
    *         .select('id')
    *         .whereRef('pet.owner_id', '=', 'person.id')
-   *     )
+   *     ))
    *   )
    * ```
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * select *
    * from "person"
    * where (
@@ -168,7 +168,7 @@ export class ExpressionWrapper<DB, TB extends keyof DB, T>
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * select *
    * from "person"
    * where (
@@ -190,13 +190,13 @@ export class ExpressionWrapper<DB, TB extends keyof DB, T>
    *       eb.selectFrom('pet')
    *         .select('id')
    *         .whereRef('pet.owner_id', '=', 'person.id')
-   *     )
+   *     ))
    *   )
    * ```
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * select *
    * from "person"
    * where (
@@ -328,7 +328,7 @@ export class OrWrapper<DB, TB extends keyof DB, T extends SqlBool>
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * select "first_name" = $1 or "first_name" = $2 as "is_jennifer_or_sylvester"
    * from "person"
    * ```
@@ -410,7 +410,7 @@ export class AndWrapper<DB, TB extends keyof DB, T extends SqlBool>
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * select "first_name" = $1 and "first_name" = $2 as "is_jennifer_aniston"
    * from "person"
    * ```

src/expression/expression.ts

@@ -70,7 +70,7 @@ export interface AliasableExpression<T> extends Expression<T> {
    *   .selectFrom('person')
    *   .select((eb) =>
    *     // `eb.fn<string>` returns an AliasableExpression<string>
-   *     eb.fn<string>('concat', ['first_name' eb.val(' '), 'last_name']).as('full_name')
+   *     eb.fn<string>('concat', ['first_name', eb.val(' '), 'last_name']).as('full_name')
    *   )
    *   .executeTakeFirstOrThrow()
    *
@@ -80,7 +80,7 @@ export interface AliasableExpression<T> extends Expression<T> {
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * select
    *   concat("first_name", $1, "last_name") as "full_name"
    * from
@@ -109,7 +109,7 @@ export interface AliasableExpression<T> extends Expression<T> {
    *
    * The generated SQL (PostgreSQL):
    *
-   * ```ts
+   * ```sql
    * insert into "person" ("first_name", "last_name")
    * from (values (1, 'foo')) as t(a, b)
    * select "t"."a", "t"."b"

src/migration/file-migration-provider.ts

@@ -7,8 +7,8 @@ import { Migration, MigrationProvider } from './migrator.js'
  * ### Examples
  *
  * ```ts
- * import { promises as fs } from 'fs'
- * import path from 'path'
+ * import { promises as fs } from 'node:fs'
+ * import path from 'node:path'
  *
  * new FileMigrationProvider({
  *   fs,

src/migration/migrator.ts

@@ -36,8 +36,8 @@ export interface Migration {
  * other way.
  *
  * ```ts
- * import { promises as fs } from 'fs'
- * import path from 'path'
+ * import { promises as fs } from 'node:fs'
+ * import path from 'node:path'
  *
  * const migrator = new Migrator({
  *   db,

src/operation-node/operation-node-transformer.ts

@@ -111,7 +111,7 @@ import { OutputNode } from './output-node.js'
  * ```ts
  * class CamelCaseTransformer extends OperationNodeTransformer {
  *   transformIdentifier(node: IdentifierNode): IdentifierNode {
- *     node = super.transformIdentifier(node),
+ *     node = super.transformIdentifier(node)
  *
  *     return {
  *       ...node,

src/plugin/parse-json-results/parse-json-results-plugin.ts

@@ -32,8 +32,9 @@ type ObjectStrategy = 'in-place' | 'create'
  *
  * ```ts
  * const db = new Kysely<DB>({
- *   ...
+ *   // ...
  *   plugins: [new ParseJSONResultsPlugin()]
+ *   // ...
  * })
  * ```
  */

src/query-builder/delete-query-builder.ts

@@ -906,11 +906,11 @@ export class DeleteQueryBuilder<DB, TB extends keyof DB, O>
    * the code. In the example above the return type of the `deletePerson` function is:
    *
    * ```ts
-   * {
+   * Promise<{
    *   id: number
    *   first_name: string
    *   last_name?: string
-   * }
+   * }>
    * ```
    */
   $if<O2>(

src/query-builder/insert-query-builder.ts

@@ -561,7 +561,7 @@ export class InsertQueryBuilder<DB, TB extends keyof DB, O>
    *   .onConflict((oc) => oc
    *     .column('name')
    *     .doUpdateSet({ species: 'hamster' })
-   *     .where('excluded.name', '!=', 'Catto'')
+   *     .where('excluded.name', '!=', 'Catto')
    *   )
    *   .execute()
    * ```
@@ -829,11 +829,11 @@ export class InsertQueryBuilder<DB, TB extends keyof DB, O>
    * the code. In the example above the return type of the `insertPerson` function is:
    *
    * ```ts
-   * {
+   * Promise<{
    *   id: number
    *   first_name: string
    *   last_name?: string
-   * }
+   * }>
    * ```
    */
   $if<O2>(