kysely 0.27.3 → 0.27.5

package/dist/esm/query-creator.js

@@ -70,7 +70,7 @@ export class QueryCreator {
      *     last_name: 'Aniston'
      *   })
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      */
     insertInto(table) {
@@ -139,24 +139,77 @@ export class QueryCreator {
      *
      * ### Examples
      *
+     * <!-- siteExample("cte", "Simple selects", 10) -->
+     *
+     * Common table expressions (CTE) are a great way to modularize complex queries.
+     * Essentially they allow you to run multiple separate queries within a
+     * single roundtrip to the DB.
+     *
+     * Since CTEs are a part of the main query, query optimizers inside DB
+     * engines are able to optimize the overall query. For example, postgres
+     * is able to inline the CTEs inside the using queries if it decides it's
+     * faster.
+     *
      * ```ts
-     * await db
+     * const result = await db
+     *   // Create a CTE called `jennifers` that selects all
+     *   // persons named 'Jennifer'.
      *   .with('jennifers', (db) => db
      *     .selectFrom('person')
      *     .where('first_name', '=', 'Jennifer')
      *     .select(['id', 'age'])
      *   )
+     *   // Select all rows from the `jennifers` CTE and
+     *   // further filter it.
      *   .with('adult_jennifers', (db) => db
      *     .selectFrom('jennifers')
      *     .where('age', '>', 18)
      *     .select(['id', 'age'])
      *   )
+     *   // Finally select all adult jennifers that are
+     *   // also younger than 60.
      *   .selectFrom('adult_jennifers')
      *   .where('age', '<', 60)
      *   .selectAll()
      *   .execute()
      * ```
      *
+     * <!-- siteExample("cte", "Inserts, updates and deletions", 20) -->
+     *
+     * Some databases like postgres also allow you to run other queries than selects
+     * in CTEs. On these databases CTEs are extremely powerful:
+     *
+     * ```ts
+     * const result = await db
+     *   .with('new_person', (db) => db
+     *     .insertInto('person')
+     *     .values({
+     *       first_name: 'Jennifer',
+     *       age: 35,
+     *     })
+     *     .returning('id')
+     *   )
+     *   .with('new_pet', (db) => db
+     *     .insertInto('pet')
+     *     .values({
+     *       name: 'Doggo',
+     *       species: 'dog',
+     *       is_favorite: true,
+     *       // Use the id of the person we just inserted.
+     *       owner_id: db
+     *         .selectFrom('new_person')
+     *         .select('id')
+     *     })
+     *     .returning('id')
+     *   )
+     *   .selectFrom(['new_person', 'new_pet'])
+     *   .select([
+     *     'new_person.id as person_id',
+     *     'new_pet.id as pet_id'
+     *   ])
+     *   .execute()
+     * ```
+     *
      * The CTE name can optionally specify column names in addition to
      * a name. In that case Kysely requires the expression to retun
      * rows with the same columns.
@@ -245,7 +298,7 @@ export class QueryCreator {
      * This only affects the query created through the builder returned from
      * this method and doesn't modify the `db` instance.
      *
-     * See [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/schemas.md)
+     * See [this recipe](https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0007-schemas.md)
      * for a more detailed explanation.
      *
      * ### Examples

package/dist/esm/raw-builder/raw-builder.d.ts

@@ -20,6 +20,8 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      * this method also provides strict typing:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await db
      *   .selectFrom('person')
      *   .select(
@@ -33,7 +35,7 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      *
      * The generated SQL (PostgreSQL):
      *
-     * ```ts
+     * ```sql
      * select concat(first_name, ' ', last_name) as "full_name"
      * from "person"
      * ```
@@ -42,6 +44,8 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      * provide the alias as the only type argument:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const values = sql<{ a: number, b: string }>`(values (1, 'foo'))`
      *
      * // The alias is `t(a, b)` which specifies the column names
@@ -56,11 +60,12 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      *   .expression(
      *     db.selectFrom(aliasedValues).select(['t.a', 't.b'])
      *   )
+     *   .execute()
      * ```
      *
      * 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"
@@ -70,6 +75,8 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
     /**
      * Returns an aliased version of the expression.
      *
+     * ### Examples
+     *
      * In addition to slapping `as "the_alias"` at the end of the expression,
      * this method also provides strict typing:
      *
@@ -78,7 +85,7 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      *   .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()
      *
@@ -88,7 +95,7 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      *
      * The generated SQL (PostgreSQL):
      *
-     * ```ts
+     * ```sql
      * select
      *   concat("first_name", $1, "last_name") as "full_name"
      * from
@@ -99,6 +106,8 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      * provide the alias as the only type argument:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const values = sql<{ a: number, b: string }>`(values (1, 'foo'))`
      *
      * // The alias is `t(a, b)` which specifies the column names
@@ -113,11 +122,12 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      *   .expression(
      *     db.selectFrom(aliasedValues).select(['t.a', 't.b'])
      *   )
+     *   .execute()
      * ```
      *
      * 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"
@@ -151,8 +161,10 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      * ### Examples
      *
      * ```ts
-     * const { sql } = sql`select * from ${sql.table('person')}`.compile(db)
-     * console.log(sql)
+     * import { sql } from 'kysely'
+     *
+     * const compiledQuery = sql`select * from ${sql.table('person')}`.compile(db)
+     * console.log(compiledQuery.sql)
      * ```
      */
     compile(executorProvider: QueryExecutorProvider): CompiledQuery<O>;
@@ -162,6 +174,8 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      * ### Examples
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await sql`select * from ${sql.table('person')}`.execute(db)
      * ```
      */
@@ -169,11 +183,19 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
     /**
      * Creates the OperationNode that describes how to compile this expression into SQL.
      *
+     * ### Examples
+     *
      * If you are creating a custom expression, it's often easiest to use the {@link sql}
      * template tag to build the node:
      *
      * ```ts
+     * import { type Expression, type OperationNode, sql } from 'kysely'
+     *
      * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     *
      *   toOperationNode(): OperationNode {
      *     return sql`some sql here`.toOperationNode()
      *   }

package/dist/esm/raw-builder/sql.d.ts

@@ -5,6 +5,7 @@ export interface Sql {
      *
      * ```ts
      * import { sql } from 'kysely'
+     * import type { Person } from 'type-editor' // imaginary module
      *
      * const id = 123
      * const snippet = sql<Person[]>`select * from person where id = ${id}`
@@ -26,6 +27,12 @@ export interface Sql {
      * of methods:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const nicknames = ['johnny', 'john', 'jon']
+     * const date1 = new Date('2000-01-01')
+     * const date2 = new Date('2001-01-01')
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .select(
@@ -33,12 +40,12 @@ export interface Sql {
      *     // method to give it an alias.
      *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
      *   )
-     *   .where(sql`birthdate between ${date1} and ${date2}`)
+     *   .where(sql<boolean>`birthdate between ${date1} and ${date2}`)
      *   // Here we assume we have list of nicknames for the person
      *   // (a list of strings) and we use the PostgreSQL `@>` operator
      *   // to test if all of them are valid nicknames for the user.
-     *   .where('nicknames', '@>', sql`ARRAY[${sql.join(nicknames)}]`)
-     *   .orderBy(sql`concat(first_name, ' ', last_name)`)
+     *   .where('nicknames', '@>', sql<string[]>`ARRAY[${sql.join(nicknames)}]`)
+     *   .orderBy(sql<string>`concat(first_name, ' ', last_name)`)
      *   .execute()
      * ```
      *
@@ -56,19 +63,24 @@ export interface Sql {
      * instance as the only argument:
      *
      * ```ts
-     * const result = await sql<Person[]>`select * from person`.execute(db)
+     * import { sql } from 'kysely'
+     * import type { Person } from 'type-editor'
+     *
+     * const { rows: results } = await sql<Person[]>`select * from person`.execute(db)
      * ```
      *
      * You can merge other `sql` expressions and queries using substitutions:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const petName = db.selectFrom('pet').select('name').limit(1)
-     * const fullName = sql`concat(first_name, ' ', last_name)`
+     * const fullName = sql<string>`concat(first_name, ' ', last_name)`
      *
-     * sql`
+     * sql<{ full_name: string; pet_name: string }[]>`
      *   select ${fullName} as full_name, ${petName} as pet_name
      *   from person
-     * `
+     * `.execute(db)
      * ```
      *
      * Substitutions also handle {@link ExpressionBuilder.ref},
@@ -101,6 +113,11 @@ export interface Sql {
      * `sql.val(value)` is a shortcut for:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const value = 123
+     * type ValueType = typeof value
+     *
      * sql<ValueType>`${value}`
      * ```
      */
@@ -131,7 +148,7 @@ export interface Sql {
      * select "first_name" from person
      * ```
      *
-     * The refefences can also include a table name:
+     * The references can also include a table name:
      *
      * ```ts
      * const columnRef = 'person.first_name'
@@ -145,7 +162,7 @@ export interface Sql {
      * select "person"."first_name" from person
      * ```
      *
-     * The refefences can also include a schema on supported databases:
+     * The references can also include a schema on supported databases:
      *
      * ```ts
      * const columnRef = 'public.person.first_name'
@@ -204,7 +221,7 @@ export interface Sql {
      * but can also be used for any other identifiers like index names.
      *
      * You should use {@link Sql.ref | ref} and {@link Sql.table | table}
-     * instead of this whenever possible as they produce a more sematic
+     * instead of this whenever possible as they produce a more semantic
      * operation node tree.
      *
      * WARNING! Using this with unchecked inputs WILL lead to SQL injection
@@ -229,7 +246,7 @@ export interface Sql {
      * const columnName = 'first_name'
      * const table = 'person'
      *
-     * sql`select ${sql.id(schema, table, columnName)}} from ${sql.id(schema, table)}`
+     * sql`select ${sql.id(schema, table, columnName)} from ${sql.id(schema, table)}`
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -297,11 +314,13 @@ export interface Sql {
      * ### Examples
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
      * function findByNicknames(nicknames: string[]): Promise<Person[]> {
      *   return db
      *     .selectFrom('person')
      *     .selectAll()
-     *     .where('nicknames', '@>', sql`ARRAY[${sql.join(nicknames)}]`)
+     *     .where('nicknames', '@>', sql<string[]>`ARRAY[${sql.join(nicknames)}]`)
      *     .execute()
      * }
      * ```

package/dist/esm/schema/alter-column-builder.d.ts

@@ -19,14 +19,28 @@ export declare class AlterColumnBuilder {
 /**
  * Allows us to force consumers to do exactly one alteration to a column.
  *
- * Basically, deny the following:
+ * One cannot do no alterations:
  *
  * ```ts
- * db.schema.alterTable('person').alterColumn('age', (ac) => ac)
+ * await db.schema
+ *   .alterTable('person')
+ * //  .execute() // Property 'execute' does not exist on type 'AlteredColumnBuilder'.
  * ```
  *
  * ```ts
- * db.schema.alterTable('person').alterColumn('age', (ac) => ac.dropNotNull().setNotNull())
+ * await db.schema
+ *   .alterTable('person')
+ * //  .alterColumn('age', (ac) => ac) // Type 'AlterColumnBuilder' is not assignable to type 'AlteredColumnBuilder'.
+ * //  .execute()
+ * ```
+ *
+ * One cannot do multiple alterations:
+ *
+ * ```ts
+ * await db.schema
+ *   .alterTable('person')
+ * //  .alterColumn('age', (ac) => ac.dropNotNull().setNotNull()) // Property 'setNotNull' does not exist on type 'AlteredColumnBuilder'.
+ * //  .execute()
  * ```
  *
  * Which would now throw a compilation error, instead of a runtime error.

package/dist/esm/schema/alter-column-builder.js

@@ -2,6 +2,7 @@
 import { AlterColumnNode } from '../operation-node/alter-column-node.js';
 import { parseDataTypeExpression, } from '../parser/data-type-parser.js';
 import { parseDefaultValueExpression, } from '../parser/default-value-parser.js';
+import { preventAwait } from '../util/prevent-await.js';
 export class AlterColumnBuilder {
     #column;
     constructor(column) {
@@ -30,17 +31,32 @@ export class AlterColumnBuilder {
         return func(this);
     }
 }
+preventAwait(AlterColumnBuilder, "don't await AlterColumnBuilder instances");
 /**
  * Allows us to force consumers to do exactly one alteration to a column.
  *
- * Basically, deny the following:
+ * One cannot do no alterations:
  *
  * ```ts
- * db.schema.alterTable('person').alterColumn('age', (ac) => ac)
+ * await db.schema
+ *   .alterTable('person')
+ * //  .execute() // Property 'execute' does not exist on type 'AlteredColumnBuilder'.
  * ```
  *
  * ```ts
- * db.schema.alterTable('person').alterColumn('age', (ac) => ac.dropNotNull().setNotNull())
+ * await db.schema
+ *   .alterTable('person')
+ * //  .alterColumn('age', (ac) => ac) // Type 'AlterColumnBuilder' is not assignable to type 'AlteredColumnBuilder'.
+ * //  .execute()
+ * ```
+ *
+ * One cannot do multiple alterations:
+ *
+ * ```ts
+ * await db.schema
+ *   .alterTable('person')
+ * //  .alterColumn('age', (ac) => ac.dropNotNull().setNotNull()) // Property 'setNotNull' does not exist on type 'AlteredColumnBuilder'.
+ * //  .execute()
  * ```
  *
  * Which would now throw a compilation error, instead of a runtime error.
@@ -54,3 +70,4 @@ export class AlteredColumnBuilder {
         return this.#alterColumnNode;
     }
 }
+preventAwait(AlteredColumnBuilder, "don't await AlteredColumnBuilder instances");

package/dist/esm/schema/alter-table-add-index-builder.d.ts

@@ -12,6 +12,23 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
     constructor(props: AlterTableAddIndexBuilderProps);
     /**
      * Makes the index unique.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_index')
+     *   .unique()
+     *   .column('email')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * alter table `person` add unique index `person_first_name_index` (`email`)
+     * ```
      */
     unique(): AlterTableAddIndexBuilder;
     /**
@@ -24,11 +41,11 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
      *
      * ```ts
      * await db.schema
-     *         .alterTable('person')
-     *         .createIndex('person_first_name_and_age_index')
-     *         .column('first_name')
-     *         .column('age desc')
-     *         .execute()
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_and_age_index')
+     *   .column('first_name')
+     *   .column('age desc')
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -48,10 +65,10 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
      *
      * ```ts
      * await db.schema
-     *         .alterTable('person')
-     *         .addIndex('person_first_name_and_age_index')
-     *         .columns(['first_name', 'age desc'])
-     *         .execute()
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_and_age_index')
+     *   .columns(['first_name', 'age desc'])
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -72,7 +89,7 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
      * await db.schema
      *   .alterTable('person')
      *   .addIndex('person_first_name_index')
-     *   .expression(sql`(first_name < 'Sami')`)
+     *   .expression(sql<boolean>`(first_name < 'Sami')`)
      *   .execute()
      * ```
      *
@@ -85,6 +102,23 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
     expression(expression: Expression<any>): AlterTableAddIndexBuilder;
     /**
      * Specifies the index type.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_index')
+     *   .column('first_name')
+     *   .using('hash')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * alter table `person` add index `person_first_name_index` (`first_name`) using hash
+     * ```
      */
     using(indexType: IndexType): AlterTableAddIndexBuilder;
     using(indexType: string): AlterTableAddIndexBuilder;

package/dist/esm/schema/alter-table-add-index-builder.js

@@ -12,6 +12,23 @@ export class AlterTableAddIndexBuilder {
     }
     /**
      * Makes the index unique.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_index')
+     *   .unique()
+     *   .column('email')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * alter table `person` add unique index `person_first_name_index` (`email`)
+     * ```
      */
     unique() {
         return new AlterTableAddIndexBuilder({
@@ -33,11 +50,11 @@ export class AlterTableAddIndexBuilder {
      *
      * ```ts
      * await db.schema
-     *         .alterTable('person')
-     *         .createIndex('person_first_name_and_age_index')
-     *         .column('first_name')
-     *         .column('age desc')
-     *         .execute()
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_and_age_index')
+     *   .column('first_name')
+     *   .column('age desc')
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -66,10 +83,10 @@ export class AlterTableAddIndexBuilder {
      *
      * ```ts
      * await db.schema
-     *         .alterTable('person')
-     *         .addIndex('person_first_name_and_age_index')
-     *         .columns(['first_name', 'age desc'])
-     *         .execute()
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_and_age_index')
+     *   .columns(['first_name', 'age desc'])
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -97,7 +114,7 @@ export class AlterTableAddIndexBuilder {
      * await db.schema
      *   .alterTable('person')
      *   .addIndex('person_first_name_index')
-     *   .expression(sql`(first_name < 'Sami')`)
+     *   .expression(sql<boolean>`(first_name < 'Sami')`)
      *   .execute()
      * ```
      *

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

@@ -200,6 +200,7 @@ export class AlterTableBuilder {
         return func(this);
     }
 }
+preventAwait(AlterTableBuilder, "don't await AlterTableBuilder instances");
 export class AlterTableColumnAlteringBuilder {
     #props;
     constructor(props) {
@@ -248,6 +249,4 @@ export class AlterTableColumnAlteringBuilder {
         await this.#props.executor.executeQuery(this.compile(), this.#props.queryId);
     }
 }
-preventAwait(AlterTableBuilder, "don't await AlterTableBuilder instances");
-preventAwait(AlterColumnBuilder, "don't await AlterColumnBuilder instances");
 preventAwait(AlterTableColumnAlteringBuilder, "don't await AlterTableColumnAlteringBuilder instances directly. To execute the query you need to call `execute`");