kysely 0.19.11 → 0.20.1

package/dist/esm/raw-builder/sql.js

@@ -7,102 +7,6 @@ import { parseTable } from '../parser/table-parser.js';
 import { parseValueExpression } from '../parser/value-parser.js';
 import { createQueryId } from '../util/query-id.js';
 import { RawBuilder } from './raw-builder.js';
-/**
- * Template tag for creating raw SQL snippets and queries.
- *
- * ```ts
- * import { sql } from 'kysely'
- *
- * const id = 123
- *
- * const snippet = sql<Person[]>`select * from person where id = ${id}`
- * ```
- *
- * Substitutions (the things inside `${}`) are automatically passed to the database
- * as parameters and are NOT interpolated to the SQL string. There's no need to worry
- * about SQL injection vulnerabilities.
- *
- * If you need your substitutions to be interpreted as identifiers, value literals or
- * lists of things, see the {@link Sql.ref}, {@link Sql.table}, {@link Sql.id},
- * {@link Sql.literal}, {@link Sql.raw} and {@link Sql.join} functions.
- *
- * You can pass sql snippets returned by the `sql` tag pretty much anywhere. Whenever
- * something can't be done using the Kysely API, you should be able to drop down to
- * raw SQL using the `sql` tag. Here's an example query that uses raw sql in a bunch
- * of methods:
- *
- * ```ts
- * const persons = await db
- *   .selectFrom('person')
- *   .select(
- *     // If you use `sql` in a select statement, remember to call the `as`
- *     // method to give it an alias. Otherwise Kysely is not able to add
- *     // the column to the result type.
- *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
- *   )
- *   .where(sql`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)`)
- *   .execute()
- * ```
- *
- * The generated SQL (PostgreSQL):
- *
- * ```sql
- * select concat(first_name, ' ', last_name) as "full_name"
- * from "person"
- * where birthdate between $1 and $2
- * and "nicknames" @> ARRAY[$3, $4, $5, $6, $7, $8, $9, $10]
- * order by concat(first_name, ' ', last_name)
- * ```
- *
- * SQL snippets can be executed by calling the `execute` method and passing a `Kysely`
- * instance as the only argument:
- *
- * ```ts
- * const result = await sql<Person[]>`select * from person`.execute(db)
- * ```
- *
- * You can merge other `sql` expressions and queries using substitutions:
- *
- * ```ts
- * const petName = db.selectFrom('pet').select('name').limit(1)
- * const fullName = sql`concat(first_name, ' ', last_name)`
- *
- * sql`
- *   select ${fullName} as full_name, ${petName} as pet_name
- *   from person
- * `
- * ```
- *
- * Substitutions also handle {@link ExpressionBuilder.ref},
- * {@link DynamicModule.ref} and pretty much anything else you
- * throw at it. Here's an example of calling a function in a
- * type-safe way:
- *
- * ```ts
- * db.selectFrom('person')
- *   .select([
- *     'first_name',
- *     'last_name',
- *     (eb) => {
- *       // The `eb.ref` method is type-safe and only accepts
- *       // column references that are possible.
- *       const firstName = eb.ref('first_name')
- *       const lastName = eb.ref('last_name')
- *
- *       const fullName = sql<string>`concat(${firstName}, ' ', ${lastName})`
- *       return fullName.as('full_name')
- *     }
- *   ])
- * ```
- *
- * don't know if that amount of ceremony is worth the small increase in
- * type-safety though... But it's possible.
- */
 export const sql = Object.assign((sqlFragments, ...parameters) => {
     return new RawBuilder({
         queryId: createQueryId(),

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

@@ -9,6 +9,7 @@ import { ColumnDefinitionNode } from '../operation-node/column-definition-node.j
 import { parseDefaultValueExpression, } from '../parser/default-value-parser.js';
 import { GeneratedNode } from '../operation-node/generated-node.js';
 import { DefaultValueNode } from '../operation-node/default-value-node.js';
+import { parseOnModifyForeignAction } from '../parser/on-modify-action-parser.js';
 export class ColumnDefinitionBuilder {
     #node;
     constructor(node) {
@@ -36,7 +37,7 @@ export class ColumnDefinitionBuilder {
             throw new Error('on delete constraint can only be added for foreign keys');
         }
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
-            references: ReferencesNode.cloneWithOnDelete(this.#node.references, onDelete),
+            references: ReferencesNode.cloneWithOnDelete(this.#node.references, parseOnModifyForeignAction(onDelete)),
         }));
     }
     onUpdate(onUpdate) {
@@ -44,7 +45,7 @@ export class ColumnDefinitionBuilder {
             throw new Error('on update constraint can only be added for foreign keys');
         }
         return new ColumnDefinitionBuilder(ColumnDefinitionNode.cloneWith(this.#node, {
-            references: ReferencesNode.cloneWithOnUpdate(this.#node.references, onUpdate),
+            references: ReferencesNode.cloneWithOnUpdate(this.#node.references, parseOnModifyForeignAction(onUpdate)),
         }));
     }
     unique() {

package/dist/esm/schema/create-table-builder.d.ts

@@ -149,6 +149,60 @@ export declare class CreateTableBuilder<TB extends string, C extends string = ne
      * ```
      */
     addForeignKeyConstraint(constraintName: string, columns: C[], targetTable: string, targetColumns: string[], build?: ForeignKeyConstraintBuilderCallback): CreateTableBuilder<TB, C>;
+    /**
+     * This can be used to add any additional SQL to the front of the query __after__ the `create` keyword.
+     *
+     * Also see {@link temporary}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * 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())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (Postgres):
+     *
+     * ```sql
+     * create global temporary table "person" (
+     *   "id" integer primary key,
+     *   "first_name" varchar(64) not null,
+     *   "last_name" varchar(64) not null
+     * )
+     * ```
+     */
+    modifyFront(modifier: AnyRawBuilder): CreateTableBuilder<TB, C>;
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * Also see {@link onCommit}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * 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())
+     *   .modifyEnd(sql`collate utf8_unicode_ci`)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `id` integer primary key,
+     *   `first_name` varchar(64) not null,
+     *   `last_name` varchar(64) not null
+     * ) collate utf8_unicode_ci
+     * ```
+     */
+    modifyEnd(modifier: AnyRawBuilder): CreateTableBuilder<TB, C>;
     toOperationNode(): CreateTableNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

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

@@ -12,6 +12,7 @@ import { PrimaryConstraintNode } from '../operation-node/primary-constraint-node
 import { UniqueConstraintNode } from '../operation-node/unique-constraint-node.js';
 import { CheckConstraintNode } from '../operation-node/check-constraint-node.js';
 import { parseTable } from '../parser/table-parser.js';
+import { parseOnCommitAction } from '../parser/on-commit-action-parse.js';
 /**
  * This builder can be used to create a `create table` query.
  */
@@ -43,7 +44,7 @@ export class CreateTableBuilder {
         return new CreateTableBuilder({
             ...this.#props,
             createTableNode: CreateTableNode.cloneWith(this.#props.createTableNode, {
-                onCommit,
+                onCommit: parseOnCommitAction(onCommit),
             }),
         });
     }
@@ -203,6 +204,70 @@ export class CreateTableBuilder {
             createTableNode: CreateTableNode.cloneWithConstraint(this.#props.createTableNode, builder.toOperationNode()),
         });
     }
+    /**
+     * This can be used to add any additional SQL to the front of the query __after__ the `create` keyword.
+     *
+     * Also see {@link temporary}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * 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())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (Postgres):
+     *
+     * ```sql
+     * create global temporary table "person" (
+     *   "id" integer primary key,
+     *   "first_name" varchar(64) not null,
+     *   "last_name" varchar(64) not null
+     * )
+     * ```
+     */
+    modifyFront(modifier) {
+        return new CreateTableBuilder({
+            ...this.#props,
+            createTableNode: CreateTableNode.cloneWithFrontModifier(this.#props.createTableNode, modifier.toOperationNode()),
+        });
+    }
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * Also see {@link onCommit}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * 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())
+     *   .modifyEnd(sql`collate utf8_unicode_ci`)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * create table `person` (
+     *   `id` integer primary key,
+     *   `first_name` varchar(64) not null,
+     *   `last_name` varchar(64) not null
+     * ) collate utf8_unicode_ci
+     * ```
+     */
+    modifyEnd(modifier) {
+        return new CreateTableBuilder({
+            ...this.#props,
+            createTableNode: CreateTableNode.cloneWithEndModifier(this.#props.createTableNode, modifier.toOperationNode()),
+        });
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.createTableNode, this.#props.queryId);
     }

package/dist/esm/schema/foreign-key-constraint-builder.js

@@ -1,5 +1,6 @@
 /// <reference types="./foreign-key-constraint-builder.d.ts" />
 import { ForeignKeyConstraintNode } from '../operation-node/foreign-key-constraint-node.js';
+import { parseOnModifyForeignAction } from '../parser/on-modify-action-parser.js';
 import { preventAwait } from '../util/prevent-await.js';
 export class ForeignKeyConstraintBuilder {
     #node;
@@ -8,12 +9,12 @@ export class ForeignKeyConstraintBuilder {
     }
     onDelete(onDelete) {
         return new ForeignKeyConstraintBuilder(ForeignKeyConstraintNode.cloneWith(this.#node, {
-            onDelete,
+            onDelete: parseOnModifyForeignAction(onDelete),
         }));
     }
     onUpdate(onUpdate) {
         return new ForeignKeyConstraintBuilder(ForeignKeyConstraintNode.cloneWith(this.#node, {
-            onUpdate,
+            onUpdate: parseOnModifyForeignAction(onUpdate),
         }));
     }
     toOperationNode() {

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

@@ -0,0 +1,5 @@
+import { AnyRawBuilder } from './type-utils.js';
+export declare type ExplainFormat = 'text' | 'xml' | 'json' | 'yaml' | 'traditional' | 'tree';
+export interface Explainable {
+    explain<O extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: AnyRawBuilder): Promise<O[]>;
+}

package/dist/esm/util/explainable.js

@@ -0,0 +1,2 @@
+/// <reference types="./explainable.d.ts" />
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.19.11",
+  "version": "0.20.1",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -48,6 +48,7 @@
     "@types/chai-subset": "^1.3.3",
     "@types/mocha": "^9.1.1",
     "@types/pg": "^8.6.5",
+    "@types/sinon": "^10.0.13",
     "better-sqlite3": "^7.5.3",
     "chai": "^4.3.6",
     "chai-as-promised": "^7.1.1",
@@ -59,6 +60,7 @@
     "pg-cursor": "^2.7.3",
     "playwright": "^1.22.2",
     "prettier": "^2.7.1",
+    "sinon": "^14.0.0",
     "tsd": "^0.21.0",
     "typedoc": "^0.23.6",
     "typescript": "4.7.4"