kysely 0.3.4 → 0.3.9

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

@@ -1,8 +1,8 @@
 import { aliasNode } from '../operation-node/alias-node.js';
 import { parseJoinArgs, } from '../parser/join-parser.js';
 import { parseSelectExpressionOrList, parseSelectAllArgs, } from '../parser/select-parser.js';
-import { parseFilterArgs, parseExistsFilterArgs, parseReferenceFilterArgs, } from '../parser/filter-parser.js';
-import { parseInsertValuesArgs } from '../parser/insert-values-parser.js';
+import { parseFilter, parseExistExpression, parseReferenceFilter, } from '../parser/filter-parser.js';
+import { parseInsertObjectOrList, } from '../parser/insert-values-parser.js';
 import { parseColumnName, parseReferenceExpression, parseReferenceExpressionOrList, } from '../parser/reference-parser.js';
 import { orderByItemNode, } from '../operation-node/order-by-item-node.js';
 import { selectQueryNode, } from '../operation-node/select-query-node.js';
@@ -42,7 +42,7 @@ export class QueryBuilder {
         ensureCanHaveWhereClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'and', parseFilterArgs('Where', args)),
+            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'and', parseFilter('Where', args)),
         });
     }
     /**
@@ -72,7 +72,8 @@ export class QueryBuilder {
      * Usage in a subquery:
      *
      * ```ts
-     * db.selectFrom('person)
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll('person')
      *   .select((qb) => qb
      *     .subQuery('pet')
@@ -81,6 +82,7 @@ export class QueryBuilder {
      *     .limit(1)
      *     .as('pet_name')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -90,21 +92,22 @@ export class QueryBuilder {
      *   select "name"
      *   from "pet"
      *   where "pet"."owner_id" = "person"."id"
-     * ) as pet_name
-     * from "person"`
+     *   limit $1
+     * ) as "pet_name"
+     * from "person"
      */
     whereRef(lhs, op, rhs) {
         ensureCanHaveWhereClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'and', parseReferenceFilterArgs(lhs, op, rhs)),
+            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'and', parseReferenceFilter(lhs, op, rhs)),
         });
     }
     orWhere(...args) {
         ensureCanHaveWhereClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'or', parseFilterArgs('Where', args)),
+            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'or', parseFilter('Where', args)),
         });
     }
     /**
@@ -117,7 +120,7 @@ export class QueryBuilder {
         ensureCanHaveWhereClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'or', parseReferenceFilterArgs(lhs, op, rhs)),
+            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'or', parseReferenceFilter(lhs, op, rhs)),
         });
     }
     /**
@@ -129,7 +132,8 @@ export class QueryBuilder {
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .whereExists((qb) => qb
      *     .subQuery('pet')
@@ -137,6 +141,7 @@ export class QueryBuilder {
      *     .whereRef('person.id', '=', 'pet.owner_id')
      *     .where('pet.name', '=', 'Catto')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -181,7 +186,7 @@ export class QueryBuilder {
         ensureCanHaveWhereClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'and', parseExistsFilterArgs('exists', arg)),
+            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'and', parseExistExpression('exists', arg)),
         });
     }
     /**
@@ -191,7 +196,7 @@ export class QueryBuilder {
         ensureCanHaveWhereClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'and', parseExistsFilterArgs('not exists', arg)),
+            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'and', parseExistExpression('not exists', arg)),
         });
     }
     /**
@@ -201,7 +206,7 @@ export class QueryBuilder {
         ensureCanHaveWhereClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'or', parseExistsFilterArgs('exists', arg)),
+            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'or', parseExistExpression('exists', arg)),
         });
     }
     /**
@@ -211,14 +216,14 @@ export class QueryBuilder {
         ensureCanHaveWhereClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'or', parseExistsFilterArgs('not exists', arg)),
+            queryNode: queryNode.cloneWithWhere(this.#queryNode, 'or', parseExistExpression('not exists', arg)),
         });
     }
     having(...args) {
         ensureCanHaveHavingClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'and', parseFilterArgs('Having', args)),
+            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'and', parseFilter('Having', args)),
         });
     }
     /**
@@ -229,14 +234,14 @@ export class QueryBuilder {
         ensureCanHaveHavingClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'and', parseReferenceFilterArgs(lhs, op, rhs)),
+            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'and', parseReferenceFilter(lhs, op, rhs)),
         });
     }
     orHaving(...args) {
         ensureCanHaveHavingClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'or', parseFilterArgs('Having', args)),
+            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'or', parseFilter('Having', args)),
         });
     }
     /**
@@ -247,7 +252,7 @@ export class QueryBuilder {
         ensureCanHaveHavingClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'or', parseReferenceFilterArgs(lhs, op, rhs)),
+            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'or', parseReferenceFilter(lhs, op, rhs)),
         });
     }
     /**
@@ -258,7 +263,7 @@ export class QueryBuilder {
         ensureCanHaveHavingClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'and', parseExistsFilterArgs('exists', arg)),
+            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'and', parseExistExpression('exists', arg)),
         });
     }
     /**
@@ -269,7 +274,7 @@ export class QueryBuilder {
         ensureCanHaveHavingClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'and', parseExistsFilterArgs('not exists', arg)),
+            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'and', parseExistExpression('not exists', arg)),
         });
     }
     /**
@@ -280,7 +285,7 @@ export class QueryBuilder {
         ensureCanHaveHavingClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'or', parseExistsFilterArgs('exists', arg)),
+            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'or', parseExistExpression('exists', arg)),
         });
     }
     /**
@@ -291,7 +296,7 @@ export class QueryBuilder {
         ensureCanHaveHavingClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'or', parseExistsFilterArgs('not exists', arg)),
+            queryNode: selectQueryNode.cloneWithHaving(this.#queryNode, 'or', parseExistExpression('not exists', arg)),
         });
     }
     select(selection) {
@@ -309,13 +314,27 @@ export class QueryBuilder {
         });
     }
     /**
+     * Makes the selection distinct.
      *
+     * @example
+     * ```ts
+     * await db.selectFrom('person')
+     *   .select('first_name')
+     *   .distinct()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (postgresql):
+     *
+     * ```sql
+     * select distinct "first_name" from "person"
+     * ```
      */
     distinct() {
         ensureCanHaveSelectClause(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: selectQueryNode.cloneWithModifier(this.#queryNode, 'Distinct'),
+            queryNode: selectQueryNode.cloneWithDistinct(this.#queryNode),
         });
     }
     /**
@@ -417,7 +436,7 @@ export class QueryBuilder {
         ensureCanHaveInsertValues(this.#queryNode);
         return new QueryBuilder({
             executor: this.#executor,
-            queryNode: insertQueryNode.cloneWithColumnsAndValues(this.#queryNode, ...parseInsertValuesArgs(args)),
+            queryNode: insertQueryNode.cloneWithColumnsAndValues(this.#queryNode, ...parseInsertObjectOrList(args)),
         });
     }
     onConflictDoNothing(columns) {
@@ -435,7 +454,7 @@ export class QueryBuilder {
         });
     }
     /**
-     * Sets the values to update for an `updateTable` query.
+     * Sets the values to update for an {@link Kysely.updateTable | update} query.
      *
      * This method takes an object whose keys are column names and values are
      * values to update. In addition to the column's type, the values can be `raw`
@@ -466,7 +485,7 @@ export class QueryBuilder {
      * ```
      *
      * @example
-     * On postgresql you need to chain `returning` to the query to get
+     * On postgresql you ca chain `returning` to the query to get
      * the updated rows' columns (or any other expression) as the
      * return value:
      *
@@ -479,7 +498,7 @@ export class QueryBuilder {
      *   })
      *   .where('id', '=', 1)
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      *
      * row.id
      * ```

package/dist/esm/query-builder/type-utils.d.ts

@@ -40,7 +40,7 @@ export declare type RowType<DB, TB extends keyof DB> = UnionToIntersection<DB[TB
  */
 export declare type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 /**
- * Given a database type and a union of table name in that db returns
+ * Given a database type and a union of table names in that db, returns
  * a union type with all possible column names.
  *
  * Example:
@@ -74,7 +74,7 @@ export declare type AnyColumn<DB, TB extends keyof DB> = {
     [T in TB]: keyof DB[T];
 }[TB];
 /**
- * Given a database type and a union of table names in that db returns
+ * Given a database type and a union of table names in that db, returns
  * a union type with all possible `table`.`column` combinations.
  *
  * Example:
@@ -107,29 +107,46 @@ export declare type AnyColumn<DB, TB extends keyof DB> = {
 export declare type AnyColumnWithTable<DB, TB extends keyof DB> = {
     [T in TB]: T extends string ? keyof DB[T] extends string ? `${T}.${keyof DB[T]}` : never : never;
 }[TB];
+/**
+ * Just like {@link AnyColumn} but with a ` as <string>` suffix.
+ */
 export declare type AnyAliasedColumn<DB, TB extends keyof DB> = {
     [T in TB]: T extends string ? keyof DB[T] extends string ? `${keyof DB[T]} as ${string}` : never : never;
 }[TB];
-export declare type AnyAliasedColumnWithTable<DB, TB extends keyof DB> = `${AnyColumnWithTable<DB, TB>} as ${string}`;
 /**
- * Extracts an array item type.
+ * Just like {@link AnyColumnWithTable} but with a ` as <string>` suffix.
+ */
+export declare type AnyAliasedColumnWithTable<DB, TB extends keyof DB> = {
+    [T in TB]: T extends string ? keyof DB[T] extends string ? `${T}.${keyof DB[T]} as ${string}` : never : never;
+}[TB];
+/**
+ * Extracts the item type of an array.
  */
 export declare type ArrayItemType<T> = T extends ReadonlyArray<infer I> ? I : never;
 export declare type AnyQueryBuilder = QueryBuilder<any, any, any>;
 export declare type AnyAliasedQueryBuilder = AliasedQueryBuilder<any, any, any, any>;
+export declare type AnyRawBuilder = RawBuilder<any>;
+export declare type AnyAliasedRawBuilder = AliasedRawBuilder<any, any>;
 export declare type QueryBuilderFactory<DB, TB extends keyof DB> = (qb: SubQueryBuilder<DB, TB>) => QueryBuilder<any, any, any>;
 export declare type AliasedQueryBuilderFactory<DB, TB extends keyof DB> = (qb: SubQueryBuilder<DB, TB>) => AnyAliasedQueryBuilder;
-export declare type RawBuilderFactory<DB, TB extends keyof DB> = (qb: SubQueryBuilder<DB, TB>) => RawBuilder<any>;
-export declare type AliasedRawBuilderFactory<DB, TB extends keyof DB> = (qb: SubQueryBuilder<DB, TB>) => AliasedRawBuilder<any, any>;
+export declare type RawBuilderFactory<DB, TB extends keyof DB> = (qb: SubQueryBuilder<DB, TB>) => AnyRawBuilder;
+export declare type AliasedRawBuilderFactory<DB, TB extends keyof DB> = (qb: SubQueryBuilder<DB, TB>) => AnyAliasedRawBuilder;
 export interface InsertResultTypeTag {
+    /** @internal */
     __isInsertResultTypeTag__: true;
 }
 export interface DeleteResultTypeTag {
+    /** @internal */
     __isDeleteResultTypeTag__: true;
 }
 export interface UpdateResultTypeTag {
+    /** @internal */
     __isUpdateResultTypeTag__: true;
 }
+export interface GeneratedPlaceholder {
+    /** @internal */
+    __isGeneratedPlaceholder__: true;
+}
 export declare type ManyResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O;
 export declare type SingleResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O | undefined;
 export declare type NonEmptySingleResultRowType<O> = O extends InsertResultTypeTag ? number : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O;

package/dist/esm/query-compiler/default-query-compiler.js

@@ -35,8 +35,8 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.compileDistinctOn(node.distinctOnSelections);
             this.append(' ');
         }
-        if (node.modifier === 'Distinct') {
-            this.append(SELECT_MODIFIER_SQL[node.modifier]);
+        if (node.isDistinct) {
+            this.append('distinct');
             this.append(' ');
         }
         if (node.selections) {
@@ -72,9 +72,11 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.offset);
         }
-        if (node.modifier) {
-            this.append(' ');
-            this.append(SELECT_MODIFIER_SQL[node.modifier]);
+        if (node.modifiers) {
+            node.modifiers.forEach((modifier) => {
+                this.append(' ');
+                this.append(SELECT_MODIFIER_SQL[modifier]);
+            });
         }
         if (isSubQuery) {
             this.append(')');
@@ -622,7 +624,6 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     }
 }
 const SELECT_MODIFIER_SQL = {
-    Distinct: 'distinct',
     ForKeyShare: 'for key share',
     ForNoKeyUpdate: 'for no key update',
     ForUpdate: 'for update',

package/dist/esm/query-creator.d.ts

@@ -138,6 +138,7 @@ export declare class QueryCreator<DB> {
      * const maybePrimaryKey: number | undefined = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
@@ -151,6 +152,7 @@ export declare class QueryCreator<DB> {
      * const { id } = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })

package/dist/esm/query-creator.js

@@ -40,6 +40,7 @@ export class QueryCreator {
      * const maybePrimaryKey: number | undefined = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
@@ -53,6 +54,7 @@ export class QueryCreator {
      * const { id } = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })

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

@@ -9,6 +9,7 @@ import { Compilable } from '../util/compilable.js';
 import { PrimitiveValue } from '../util/object-utils.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { ColumnDefinitionBuilder, ColumnDefinitionBuilderInterface } from './column-definition-builder.js';
+import { AnyRawBuilder } from '../query-builder/type-utils.js';
 export declare class AlterTableBuilder {
     #private;
     constructor(args: AlterTableBuilderConstructorArgs);
@@ -23,7 +24,7 @@ export declare class AlterColumnBuilder {
     #private;
     constructor(args: AlterColumnBuilderConstructorArgs);
     setDataType(dataType: ColumnDataType): AlterTableExecutor;
-    setDefault(value: PrimitiveValue | RawBuilder<any>): AlterTableExecutor;
+    setDefault(value: PrimitiveValue | AnyRawBuilder): AlterTableExecutor;
     dropDefault(): AlterTableExecutor;
     setNotNull(): AlterTableExecutor;
     dropNotNull(): AlterTableExecutor;
@@ -44,7 +45,7 @@ export declare class AlterTableAddColumnBuilder implements ColumnDefinitionBuild
     onDelete(onDelete: OnDelete): AlterTableAddColumnBuilder;
     unique(): AlterTableAddColumnBuilder;
     notNull(): AlterTableAddColumnBuilder;
-    defaultTo(value: PrimitiveValue | RawBuilder<any>): AlterTableAddColumnBuilder;
+    defaultTo(value: PrimitiveValue | AnyRawBuilder): AlterTableAddColumnBuilder;
     check(sql: string): AlterTableAddColumnBuilder;
     toOperationNode(): AlterTableNode;
     compile(): CompiledQuery;

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

@@ -1,8 +1,8 @@
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { OnDelete } from '../operation-node/references-node.js';
-import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { PrimitiveValue } from '../util/object-utils.js';
 import { ColumnDefinitionNode } from '../operation-node/column-definition-node.js';
+import { AnyRawBuilder } from '../query-builder/type-utils.js';
 export interface ColumnDefinitionBuilderInterface<R> {
     /**
      * Makes the column automatically incrementing.
@@ -51,7 +51,7 @@ export interface ColumnDefinitionBuilderInterface<R> {
      *   .execute()
      * ```
      */
-    defaultTo(value: PrimitiveValue | RawBuilder<any>): R;
+    defaultTo(value: PrimitiveValue | AnyRawBuilder): R;
     /**
      * Adds a check constraint for the column.
      *
@@ -74,7 +74,7 @@ export declare class ColumnDefinitionBuilder implements ColumnDefinitionBuilderI
     onDelete(onDelete: OnDelete): ColumnDefinitionBuilder;
     unique(): ColumnDefinitionBuilder;
     notNull(): ColumnDefinitionBuilder;
-    defaultTo(value: PrimitiveValue | RawBuilder<any>): ColumnDefinitionBuilder;
+    defaultTo(value: PrimitiveValue | AnyRawBuilder): ColumnDefinitionBuilder;
     check(sql: string): ColumnDefinitionBuilder;
     toOperationNode(): ColumnDefinitionNode;
 }

package/dist/esm/util/generated-placeholder.d.ts

@@ -0,0 +1,3 @@
+import { GeneratedPlaceholder } from '../query-builder/type-utils';
+export declare const generatedPlaceholder: GeneratedPlaceholder;
+export declare function isGeneratedPlaceholder(obj: unknown): obj is GeneratedPlaceholder;

package/dist/esm/util/generated-placeholder.js

@@ -0,0 +1,7 @@
+import { freeze, isObject } from './object-utils';
+export const generatedPlaceholder = freeze({
+    __isGeneratedPlaceholder__: true,
+});
+export function isGeneratedPlaceholder(obj) {
+    return isObject(obj) && obj.__isGeneratedPlaceholder__ === true;
+}

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

@@ -15,3 +15,4 @@ export declare function getLast<T>(arr: ArrayLike<T>): T | undefined;
 export declare function freeze<T>(obj: T): Readonly<T>;
 export declare function asArray<T>(arg: T | T[]): T[];
 export declare function asReadonlyArray<T>(arg: T | ReadonlyArray<T>): ReadonlyArray<T>;
+export declare function isReadonlyArray(arg: unknown): arg is ReadonlyArray<unknown>;

package/dist/esm/util/object-utils.js

@@ -65,6 +65,6 @@ export function asReadonlyArray(arg) {
         return freeze([arg]);
     }
 }
-function isReadonlyArray(arg) {
+export function isReadonlyArray(arg) {
     return Array.isArray(arg);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.3.4",
+  "version": "0.3.9",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -24,7 +24,7 @@
     "build": "npm run clean && npm run build:esm && npm run build:cjs && ./module-fixup.sh",
     "build:esm": "tsc -p tsconfig.json",
     "build:cjs": "tsc -p tsconfig-cjs.json",
-    "docs:build": "typedoc --excludePrivate --excludeInternal src/index.ts && npm run docs:postprocess",
+    "docs:build": "typedoc --excludePrivate --excludeInternal --customCss ./docs-theme.css src/index.ts && npm run docs:postprocess",
     "docs:postprocess": "node post-process-docs.js",
     "prepublish": "npm run build"
   },