kysely 0.22.0 → 0.23.0

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

@@ -1,20 +1,37 @@
 import { QueryResult } from '../driver/database-connection.js';
 import { AliasNode } from '../operation-node/alias-node.js';
-import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { RawNode } from '../operation-node/raw-node.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { QueryExecutorProvider } from '../query-executor/query-executor-provider.js';
 import { QueryId } from '../util/query-id.js';
-import { AnyRawBuilder } from '../util/type-utils.js';
+import { AliasedExpression, Expression } from '../expression/expression.js';
 /**
  * An instance of this class can be used to create raw SQL snippets or queries.
  *
  * You shouldn't need to create `RawBuilder` instances directly. Instead you should
  * use the {@link sql} template tag.
  */
-export declare class RawBuilder<O = unknown> implements OperationNodeSource {
+export declare class RawBuilder<O> implements Expression<O> {
     #private;
     constructor(props: RawBuilderProps);
+    /** @private */
+    /**
+     * All expressions need to have this getter for complicated type-related reasons.
+     * Simply add this getter for your expression and always return `undefined` from it:
+     *
+     * ```ts
+     * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     * }
+     * ```
+     *
+     * The getter is needed to make the expression assignable to another expression only
+     * if the types `T` are assignable. Without this property (or some other property
+     * that references `T`), you could assing `Expression<string>` to `Expression<number>`.
+     */
+    get expressionType(): O | undefined;
     /**
      * Returns an aliased version of the SQL expression.
      *
@@ -69,7 +86,7 @@ export declare class RawBuilder<O = unknown> implements OperationNodeSource {
      * ```
      */
     as<A extends string>(alias: A): AliasedRawBuilder<O, A>;
-    as<A extends string = never>(alias: AnyRawBuilder): AliasedRawBuilder<O, A>;
+    as<A extends string = never>(alias: Expression<any>): AliasedRawBuilder<O, A>;
     /**
      * Change the output type of the raw expression.
      *
@@ -81,25 +98,44 @@ export declare class RawBuilder<O = unknown> implements OperationNodeSource {
      * Adds a plugin for this SQL snippet.
      */
     withPlugin(plugin: KyselyPlugin): RawBuilder<O>;
+    /**
+     * Creates the OperationNode that describes how to compile this expression into SQL.
+     *
+     * If you are creating a custom expression, it's often easiest to use the {@link sql}
+     * template tag to build the node:
+     *
+     * ```ts
+     * class SomeExpression<T> implements Expression<T> {
+     *   toOperationNode(): OperationNode {
+     *     return sql`some sql here`.toOperationNode()
+     *   }
+     * }
+     * ```
+     */
     toOperationNode(): RawNode;
     execute(executorProvider: QueryExecutorProvider): Promise<QueryResult<O>>;
 }
+export declare function isRawBuilder(obj: unknown): obj is RawBuilder<unknown>;
 /**
  * {@link RawBuilder} with an alias. The result of calling {@link RawBuilder.as}.
  */
-export declare class AliasedRawBuilder<O = unknown, A extends string = never> implements OperationNodeSource {
+export declare class AliasedRawBuilder<O = unknown, A extends string = never> implements AliasedExpression<O, A> {
     #private;
+    constructor(rawBuilder: RawBuilder<O>, alias: A | Expression<any>);
+    /** @private */
     /**
-     * @private
-     *
-     * This needs to be here just so that the typings work. Without this
-     * the generated .d.ts file contains no reference to the type param A
-     * which causes this type to be equal to AliasedRawBuilder with any A
-     * as long as O is the same.
+     * Returns the aliased expression.
+     */
+    get expression(): Expression<O>;
+    /** @private */
+    /**
+     * Returns the alias.
+     */
+    get alias(): A;
+    /**
+     * Creates the OperationNode that describes how to compile this expression into SQL.
      */
-    protected get alias(): A | AnyRawBuilder;
     toOperationNode(): AliasNode;
-    constructor(rawBuilder: RawBuilder<O>, alias: A | AnyRawBuilder);
 }
 export interface RawBuilderProps {
     readonly queryId: QueryId;

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

@@ -1,10 +1,10 @@
 /// <reference types="./raw-builder.d.ts" />
 import { AliasNode } from '../operation-node/alias-node.js';
-import { isOperationNodeSource, } from '../operation-node/operation-node-source.js';
 import { preventAwait } from '../util/prevent-await.js';
-import { freeze } from '../util/object-utils.js';
+import { freeze, isFunction, isObject } from '../util/object-utils.js';
 import { NOOP_QUERY_EXECUTOR } from '../query-executor/noop-query-executor.js';
 import { IdentifierNode } from '../operation-node/identifier-node.js';
+import { isOperationNodeSource } from '../operation-node/operation-node-source.js';
 /**
  * An instance of this class can be used to create raw SQL snippets or queries.
  *
@@ -16,6 +16,10 @@ export class RawBuilder {
     constructor(props) {
         this.#props = freeze(props);
     }
+    /** @private */
+    get expressionType() {
+        return undefined;
+    }
     as(alias) {
         return new AliasedRawBuilder(this, alias);
     }
@@ -58,6 +62,14 @@ export class RawBuilder {
         return executor.compileQuery(this.#toOperationNode(executor), this.#props.queryId);
     }
 }
+export function isRawBuilder(obj) {
+    return (isObject(obj) &&
+        isFunction(obj.as) &&
+        isFunction(obj.castTo) &&
+        isFunction(obj.withPlugin) &&
+        isFunction(obj.toOperationNode) &&
+        isFunction(obj.execute));
+}
 preventAwait(RawBuilder, "don't await RawBuilder instances directly. To execute the query you need to call `execute`");
 /**
  * {@link RawBuilder} with an alias. The result of calling {@link RawBuilder.as}.
@@ -65,14 +77,15 @@ preventAwait(RawBuilder, "don't await RawBuilder instances directly. To execute
 export class AliasedRawBuilder {
     #rawBuilder;
     #alias;
-    /**
-     * @private
-     *
-     * This needs to be here just so that the typings work. Without this
-     * the generated .d.ts file contains no reference to the type param A
-     * which causes this type to be equal to AliasedRawBuilder with any A
-     * as long as O is the same.
-     */
+    constructor(rawBuilder, alias) {
+        this.#rawBuilder = rawBuilder;
+        this.#alias = alias;
+    }
+    /** @private */
+    get expression() {
+        return this.#rawBuilder;
+    }
+    /** @private */
     get alias() {
         return this.#alias;
     }
@@ -81,8 +94,4 @@ export class AliasedRawBuilder {
             ? this.#alias.toOperationNode()
             : IdentifierNode.create(this.#alias));
     }
-    constructor(rawBuilder, alias) {
-        this.#rawBuilder = rawBuilder;
-        this.#alias = alias;
-    }
 }

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

@@ -101,10 +101,10 @@ export interface Sql {
      * `sql.value(value)` is a shortcut for:
      *
      * ```ts
-     * sql`${value}`
+     * sql<ValueType>`${value}`
      * ```
      */
-    value(value: unknown): RawBuilder<unknown>;
+    value<T>(value: T): RawBuilder<T>;
     /**
      * This can be used to add runtime column references to SQL snippets.
      *
@@ -234,7 +234,7 @@ export interface Sql {
      * select "public"."person"."first_name" from "public"."person"
      * ```
      */
-    id(...ids: string[]): RawBuilder<unknown>;
+    id(...ids: readonly string[]): RawBuilder<unknown>;
     /**
      * This can be used to add literal values to SQL snippets.
      *
@@ -334,6 +334,6 @@ export interface Sql {
      * BEFORE $1::varchar, (1 == 1)::varchar, (select * from "person")::varchar, false::varchar, "first_name" AFTER
      * ```
      */
-    join(array: unknown[], separator?: RawBuilder<any>): RawBuilder<unknown>;
+    join(array: readonly unknown[], separator?: RawBuilder<any>): RawBuilder<unknown>;
 }
 export declare const sql: Sql;

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

@@ -0,0 +1,28 @@
+import { AlterColumnNode } from '../operation-node/alter-column-node.js';
+import { ColumnDataType } from '../operation-node/data-type-node.js';
+import { OperationNodeSource } from '../operation-node/operation-node-source.js';
+import { DefaultValueExpression } from '../parser/default-value-parser.js';
+export declare class AlterColumnBuilder {
+    protected readonly alterColumnNode: AlterColumnNode;
+    constructor(alterColumnNode: AlterColumnNode);
+    setDataType(dataType: ColumnDataType): AlteredColumnBuilder;
+    setDefault(value: DefaultValueExpression): AlteredColumnBuilder;
+    dropDefault(): AlteredColumnBuilder;
+    setNotNull(): AlteredColumnBuilder;
+    dropNotNull(): AlteredColumnBuilder;
+}
+/**
+ * Allows us to force consumers to do something, anything, when altering a column.
+ *
+ * Basically, deny the following:
+ *
+ * ```ts
+ * db.schema.alterTable('person').alterColumn('age', (ac) => ac)
+ * ```
+ *
+ * Which would now throw a compilation error, instead of a runtime error.
+ */
+export declare class AlteredColumnBuilder extends AlterColumnBuilder implements OperationNodeSource {
+    toOperationNode(): AlterColumnNode;
+}
+export declare type AlterColumnBuilderCallback = (builder: AlterColumnBuilder) => AlteredColumnBuilder;

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

@@ -0,0 +1,51 @@
+/// <reference types="./alter-column-builder.d.ts" />
+import { AlterColumnNode } from '../operation-node/alter-column-node.js';
+import { DataTypeNode, } from '../operation-node/data-type-node.js';
+import { parseDefaultValueExpression, } from '../parser/default-value-parser.js';
+export class AlterColumnBuilder {
+    alterColumnNode;
+    constructor(alterColumnNode) {
+        this.alterColumnNode = alterColumnNode;
+    }
+    setDataType(dataType) {
+        return new AlteredColumnBuilder(AlterColumnNode.cloneWith(this.alterColumnNode, {
+            dataType: DataTypeNode.create(dataType),
+        }));
+    }
+    setDefault(value) {
+        return new AlteredColumnBuilder(AlterColumnNode.cloneWith(this.alterColumnNode, {
+            setDefault: parseDefaultValueExpression(value),
+        }));
+    }
+    dropDefault() {
+        return new AlteredColumnBuilder(AlterColumnNode.cloneWith(this.alterColumnNode, {
+            dropDefault: true,
+        }));
+    }
+    setNotNull() {
+        return new AlteredColumnBuilder(AlterColumnNode.cloneWith(this.alterColumnNode, {
+            setNotNull: true,
+        }));
+    }
+    dropNotNull() {
+        return new AlteredColumnBuilder(AlterColumnNode.cloneWith(this.alterColumnNode, {
+            dropNotNull: true,
+        }));
+    }
+}
+/**
+ * Allows us to force consumers to do something, anything, when altering a column.
+ *
+ * Basically, deny the following:
+ *
+ * ```ts
+ * db.schema.alterTable('person').alterColumn('age', (ac) => ac)
+ * ```
+ *
+ * Which would now throw a compilation error, instead of a runtime error.
+ */
+export class AlteredColumnBuilder extends AlterColumnBuilder {
+    toOperationNode() {
+        return this.alterColumnNode;
+    }
+}