kysely 0.27.4 → 0.27.6

package/dist/esm/schema/create-table-builder.js

@@ -73,7 +73,7 @@ export class CreateTableBuilder {
      *
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey()),
+     *   .addColumn('id', 'integer', (col) => col.autoIncrement().primaryKey())
      *   .addColumn('first_name', 'varchar(50)', (col) => col.notNull())
      *   .addColumn('last_name', 'varchar(255)')
      *   .addColumn('bank_balance', 'numeric(8, 2)')
@@ -81,7 +81,7 @@ export class CreateTableBuilder {
      *   // don't include it.
      *   .addColumn('data', sql`any_type_here`)
      *   .addColumn('parent_id', 'integer', (col) =>
-     *     col.references('person.id').onDelete('cascade'))
+     *     col.references('person.id').onDelete('cascade')
      *   )
      * ```
      *
@@ -92,11 +92,18 @@ export class CreateTableBuilder {
      * `create table` query. See the next example:
      *
      * ```ts
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', (col) => col.primaryKey())
      *   .addColumn('parent_id', 'integer')
      *   .addForeignKeyConstraint(
-     *     'person_parent_id_fk', ['parent_id'], 'person', ['id'],
+     *     'person_parent_id_fk',
+     *     ['parent_id'],
+     *     'person',
+     *     ['id'],
      *     (cb) => cb.onDelete('cascade')
      *   )
+     *   .execute()
      * ```
      *
      * Another good example is that PostgreSQL doesn't support the `auto_increment`
@@ -106,7 +113,8 @@ export class CreateTableBuilder {
      * ```ts
      * await db.schema
      *   .createTable('person')
-     *   .addColumn('id', 'serial', (col) => col.primaryKey()),
+     *   .addColumn('id', 'serial', (col) => col.primaryKey())
+     *   .execute()
      * ```
      */
     addColumn(columnName, dataType, build = noop) {
@@ -125,7 +133,12 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addPrimaryKeyConstraint('primary_key', ['first_name', 'last_name'])
+     *   .execute()
      * ```
      */
     addPrimaryKeyConstraint(constraintName, columns) {
@@ -143,12 +156,30 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'])
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addUniqueConstraint(
+     *     'first_name_last_name_unique',
+     *     ['first_name', 'last_name']
+     *   )
+     *   .execute()
      * ```
      *
      * In dialects such as PostgreSQL you can specify `nulls not distinct` as follows:
+     *
      * ```ts
-     * addUniqueConstraint('first_name_last_name_unique', ['first_name', 'last_name'], (builder) => builder.nullsNotDistinct())
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('first_name', 'varchar(64)')
+     *   .addColumn('last_name', 'varchar(64)')
+     *   .addUniqueConstraint(
+     *     'first_name_last_name_unique',
+     *     ['first_name', 'last_name'],
+     *     (cb) => cb.nullsNotDistinct()
+     *   )
+     *   .execute()
      * ```
      */
     addUniqueConstraint(constraintName, columns, build = noop) {
@@ -169,7 +200,11 @@ export class CreateTableBuilder {
      * ```ts
      * import { sql } from 'kysely'
      *
-     * addCheckConstraint('check_legs', sql`number_of_legs < 5`)
+     * await db.schema
+     *   .createTable('animal')
+     *   .addColumn('number_of_legs', 'integer')
+     *   .addCheckConstraint('check_legs', sql`number_of_legs < 5`)
+     *   .execute()
      * ```
      */
     addCheckConstraint(constraintName, checkExpression) {
@@ -187,24 +222,33 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * addForeignKeyConstraint(
-     *   'owner_id_foreign',
-     *   ['owner_id'],
-     *   'person',
-     *   ['id'],
-     * )
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'owner_id_foreign',
+     *     ['owner_id'],
+     *     'person',
+     *     ['id'],
+     *   )
+     *   .execute()
      * ```
      *
      * Add constraint for multiple columns:
      *
      * ```ts
-     * addForeignKeyConstraint(
-     *   'owner_id_foreign',
-     *   ['owner_id1', 'owner_id2'],
-     *   'person',
-     *   ['id1', 'id2'],
-     *   (cb) => cb.onDelete('cascade')
-     * )
+     * await db.schema
+     *   .createTable('pet')
+     *   .addColumn('owner_id1', 'integer')
+     *   .addColumn('owner_id2', 'integer')
+     *   .addForeignKeyConstraint(
+     *     'owner_id_foreign',
+     *     ['owner_id1', 'owner_id2'],
+     *     'person',
+     *     ['id1', 'id2'],
+     *     (cb) => cb.onDelete('cascade')
+     *   )
+     *   .execute()
      * ```
      */
     addForeignKeyConstraint(constraintName, columns, targetTable, targetColumns, build = noop) {
@@ -222,11 +266,14 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
      *   .modifyFront(sql`global temporary`)
      *   .addColumn('id', 'integer', col => col.primaryKey())
      *   .addColumn('first_name', 'varchar(64)', col => col.notNull())
-     *   .addColumn('last_name', 'varchar(64), col => col.notNull())
+     *   .addColumn('last_name', 'varchar(64)', col => col.notNull())
      *   .execute()
      * ```
      *
@@ -254,10 +301,13 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('person')
-     *   .addColumn('id', 'integer', col => col => primaryKey())
+     * import { sql } from 'kysely'
+     *
+     * await db.schema
+     *   .createTable('person')
+     *   .addColumn('id', 'integer', col => col.primaryKey())
      *   .addColumn('first_name', 'varchar(64)', col => col.notNull())
-     *   .addColumn('last_name', 'varchar(64), col => col.notNull())
+     *   .addColumn('last_name', 'varchar(64)', col => col.notNull())
      *   .modifyEnd(sql`collate utf8_unicode_ci`)
      *   .execute()
      * ```
@@ -284,7 +334,8 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema.createTable('copy')
+     * await db.schema
+     *   .createTable('copy')
      *   .temporary()
      *   .as(db.selectFrom('person').select(['first_name', 'last_name']))
      *   .execute()
@@ -311,17 +362,19 @@ export class CreateTableBuilder {
      * ### Examples
      *
      * ```ts
-     * db.schema
+     * await db.schema
      *   .createTable('test')
      *   .$call((builder) => builder.addColumn('id', 'integer'))
      *   .execute()
      * ```
      *
+     * This is useful for creating reusable functions that can be called with a builder.
+     *
      * ```ts
-     * const addDefaultColumns = <T extends string, C extends string = never>(
-     *   builder: CreateTableBuilder<T, C>
-     * ) => {
-     *   return builder
+     * import { type CreateTableBuilder, sql } from 'kysely'
+     *
+     * const addDefaultColumns = (ctb: CreateTableBuilder<any, any>) => {
+     *   return ctb
      *     .addColumn('id', 'integer', (col) => col.notNull())
      *     .addColumn('created_at', 'date', (col) =>
      *       col.notNull().defaultTo(sql`now()`)
@@ -331,7 +384,7 @@ export class CreateTableBuilder {
      *     )
      * }
      *
-     * db.schema
+     * await db.schema
      *   .createTable('test')
      *   .$call(addDefaultColumns)
      *   .execute()

package/dist/esm/util/column-type.d.ts

@@ -15,7 +15,7 @@ import { DrainOuterGeneric } from './type-utils.js';
  * type is actually just a shortcut for the type in this example:
  *
  * ```ts
- * ColumnType<number, number | undefined, number>
+ * type GeneratedNumber = ColumnType<number, number | undefined, number>
  * ```
  *
  * The above example makes the column optional in inserts
@@ -24,14 +24,14 @@ import { DrainOuterGeneric } from './type-utils.js';
  * can se the type as `never`:
  *
  * ```ts
- * ColumnType<number, never, never>
+ * type ReadonlyNumber = ColumnType<number, never, never>
  * ```
  *
  * Here's one more example where the type is different
  * for each different operation:
  *
  * ```ts
- * ColumnType<Date, string, never>
+ * type UnupdateableDate = ColumnType<Date, string, never>
  * ```
  */
 export type ColumnType<SelectType, InsertType = SelectType, UpdateType = SelectType> = {
@@ -44,12 +44,8 @@ export type ColumnType<SelectType, InsertType = SelectType, UpdateType = SelectT
  * is the same for all selects, inserts and updates but the
  * column is optional for inserts and updates.
  *
- * The implementation:
- *
- * ```ts
- * // The update type is `S` instead of `S | undefined` because
- * // updates are always optional --> no need to specify optionality.
- * type Generated<S> = ColumnType<S, S | undefined, S>
+ * The update type is `S` instead of `S | undefined` because updates are always
+ * optional --> no need to specify optionality.
  * ```
  */
 export type Generated<S> = ColumnType<S, S | undefined, S>;

package/dist/esm/util/require-all-props.d.ts

@@ -26,14 +26,16 @@ type AllProps<T> = T & {
  * 1. Omit checked type - all checked properties will be expect as of type never
  *
  * ```ts
- * const z: SomeType = requireAllProps({ propC: "no type will work" });
+ * type SomeType = { propA: string; propB?: number; }
+ * // const z: SomeType = requireAllProps({ propC: "no type will work" }); // Property 'propA' is missing in type '{ propC: string; }' but required in type 'SomeType'.
  * ```
  *
  * 2. Apply to spreaded object - there is no way how to check in compile time if spreaded object contains all properties
  *
  * ```ts
+ * type SomeType = { propA: string; propB?: number; }
  * const y: SomeType = { propA: "" }; // valid object according to SomeType declaration
- * const x = requireAllProps<SomeType>( { ... y } );
+ * // const x = requireAllProps<SomeType>({ ...y }); // Argument of type '{ propA: string; propB?: number; }' is not assignable to parameter of type 'AllProps<SomeType>'.
  * ```
  *
  * @param obj object to check if all properties has been used

package/dist/esm/util/require-all-props.js

@@ -19,14 +19,16 @@
  * 1. Omit checked type - all checked properties will be expect as of type never
  *
  * ```ts
- * const z: SomeType = requireAllProps({ propC: "no type will work" });
+ * type SomeType = { propA: string; propB?: number; }
+ * // const z: SomeType = requireAllProps({ propC: "no type will work" }); // Property 'propA' is missing in type '{ propC: string; }' but required in type 'SomeType'.
  * ```
  *
  * 2. Apply to spreaded object - there is no way how to check in compile time if spreaded object contains all properties
  *
  * ```ts
+ * type SomeType = { propA: string; propB?: number; }
  * const y: SomeType = { propA: "" }; // valid object according to SomeType declaration
- * const x = requireAllProps<SomeType>( { ... y } );
+ * // const x = requireAllProps<SomeType>({ ...y }); // Argument of type '{ propA: string; propB?: number; }' is not assignable to parameter of type 'AllProps<SomeType>'.
  * ```
  *
  * @param obj object to check if all properties has been used

package/dist/esm/util/streamable.d.ts

@@ -8,7 +8,7 @@ export interface Streamable<O> {
      * ### Examples
      *
      * ```ts
-     * const stream = db.
+     * const stream = db
      *   .selectFrom('person')
      *   .select(['first_name', 'last_name'])
      *   .where('gender', '=', 'other')

package/dist/esm/util/type-utils.d.ts

@@ -125,7 +125,9 @@ export type NarrowPartial<O, T> = DrainOuterGeneric<T extends object ? {
  * Example:
  *
  * ```ts
- * const person = await db.selectFrom('person')
+ * import type { NotNull } from 'kysely'
+ *
+ * await db.selectFrom('person')
  *   .where('nullable_column', 'is not', null)
  *   .selectAll()
  *   .$narrowType<{ nullable_column: NotNull }>()
@@ -148,7 +150,7 @@ export type SqlBool = boolean | 0 | 1;
  *   A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<T>>>>>>>>>>>>>>>>>>>>>>>>
  * >
  *
- * type Error = Test<number> // Type instantiation is excessively deep and possibly infinite.ts (2589)
+ * // type Error = Test<number> // Type instantiation is excessively deep and possibly infinite.ts (2589)
  * ```
  *
  * To fix this, we can use `DrainOuterGeneric`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.27.4",
+  "version": "0.27.6",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -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": "node scripts/check-exports.js",
+    "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",
@@ -61,7 +62,9 @@
     "script:copy-interface-doc": "node scripts/copy-interface-documentation.js",
     "script:add-deno-type-references": "node scripts/add-deno-type-references.js",
     "script:align-site-version": "node scripts/align-site-version.js",
-    "prepublishOnly": "npm run build"
+    "script:generate-site-examples": "node scripts/generate-site-examples.js",
+    "prepublishOnly": "npm run build",
+    "release:preview": "pkg-pr-new publish --template './example'"
   },
   "author": "Sami Koskimäki <sami@jakso.me>",
   "license": "MIT",
@@ -70,32 +73,34 @@
     "Igal Klebanov <igalklebanov@gmail.com>"
   ],
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.8",
-    "@types/chai": "^4.3.11",
+    "@arethetypeswrong/cli": "^0.17.0",
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/chai": "^4.3.17",
     "@types/chai-as-promised": "^7.1.8",
     "@types/chai-subset": "^1.3.5",
-    "@types/mocha": "^10.0.6",
-    "@types/node": "^18.15.11",
-    "@types/pg": "^8.10.9",
+    "@types/mocha": "^10.0.7",
+    "@types/node": "^22.5.0",
+    "@types/pg": "^8.11.6",
     "@types/pg-cursor": "^2.7.2",
     "@types/sinon": "^17.0.2",
     "@types/tedious": "^4.0.9",
-    "better-sqlite3": "^9.6.0",
-    "chai": "^4.4.0",
-    "chai-as-promised": "^7.1.1",
+    "better-sqlite3": "^11.2.1",
+    "chai": "^4.5.0",
+    "chai-as-promised": "^7.1.2",
     "chai-subset": "^1.6.0",
-    "esbuild": "^0.19.11",
+    "esbuild": "^0.24.0",
     "lodash": "^4.17.21",
-    "mocha": "^10.2.0",
-    "mysql2": "^3.6.5",
-    "pg": "^8.11.3",
-    "pg-cursor": "^2.10.3",
-    "playwright": "^1.40.1",
-    "prettier": "^3.1.1",
-    "sinon": "^17.0.1",
+    "mocha": "^10.7.3",
+    "mysql2": "^3.11.0",
+    "pg": "^8.12.0",
+    "pg-cursor": "^2.11.0",
+    "pkg-pr-new": "^0.0.30",
+    "playwright": "^1.46.1",
+    "prettier": "^3.3.3",
+    "sinon": "^19.0.2",
     "tarn": "^3.0.2",
-    "tedious": "^18.2.0",
-    "tsd": "^0.30.3",
-    "typescript": "^5.5.2"
+    "tedious": "^19.0.0",
+    "tsd": "^0.31.1",
+    "typescript": "^5.6.3"
   }
 }