kysely 0.16.8 → 0.17.0

package/dist/cjs/query-builder/update-query-builder.js

@@ -19,81 +19,81 @@ class UpdateQueryBuilder {
     where(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(this.#props.parseContext, args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(args)),
         });
     }
     whereRef(lhs, op, rhs) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     orWhere(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(this.#props.parseContext, args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseWhereFilter)(args)),
         });
     }
     orWhereRef(lhs, op, rhs) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(this.#props.parseContext, lhs, op, rhs)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseReferenceFilter)(lhs, op, rhs)),
         });
     }
     whereExists(arg) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     whereNotExists(arg) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     orWhereExists(arg) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseExistFilter)(arg)),
         });
     }
     orWhereNotExists(arg) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(this.#props.parseContext, arg)),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrWhere(this.#props.queryNode, (0, filter_parser_js_1.parseNotExistFilter)(arg)),
         });
     }
     innerJoin(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'InnerJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('InnerJoin', args)),
         });
     }
     leftJoin(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'LeftJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('LeftJoin', args)),
         });
     }
     rightJoin(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'RightJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('RightJoin', args)),
         });
     }
     fullJoin(...args) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(this.#props.parseContext, 'FullJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('FullJoin', args)),
         });
     }
     /**
      * 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`
-     * instances or select queries.
+     * values to update. In addition to the column's type, the values can be
+     * raw {@link sql} snippets or select queries.
      *
      * The return value of an update query is an instance of {@link UpdateResult}.
      * You can use the {@link returning} method on supported databases to get out
@@ -146,16 +146,18 @@ class UpdateQueryBuilder {
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
      * ```
      *
-     * In addition to primitives, the values can also be `raw` expressions or
+     * In addition to primitives, the values can also be raw sql expressions or
      * select queries:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await db
      *   .updateTable('person')
      *   .set({
      *     first_name: 'Jennifer',
-     *     last_name: db.raw('? || ?', ['Ani', 'ston']),
-     *     age: db.selectFrom('person').select(raw('avg(age)')),
+     *     last_name: sql`${'Ani'} || ${'ston'}`,
+     *     age: db.selectFrom('person').select(sql`avg(age)`),
      *   })
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
@@ -176,13 +178,13 @@ class UpdateQueryBuilder {
     set(row) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: update_query_node_js_1.UpdateQueryNode.cloneWithUpdates(this.#props.queryNode, (0, update_set_parser_js_1.parseUpdateObject)(this.#props.parseContext, row)),
+            queryNode: update_query_node_js_1.UpdateQueryNode.cloneWithUpdates(this.#props.queryNode, (0, update_set_parser_js_1.parseUpdateObject)(row)),
         });
     }
     returning(selection) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithReturning(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(this.#props.parseContext, selection)),
+            queryNode: query_node_js_1.QueryNode.cloneWithReturning(this.#props.queryNode, (0, select_parser_js_1.parseSelectExpressionOrList)(selection)),
         });
     }
     returningAll() {
@@ -293,7 +295,7 @@ class UpdateQueryBuilder {
         const compildQuery = this.compile();
         const query = compildQuery.query;
         const result = await this.#props.executor.executeQuery(compildQuery, this.#props.queryId);
-        if (this.#props.parseContext.adapter.supportsReturning && query.returning) {
+        if (this.#props.executor.adapter.supportsReturning && query.returning) {
             return result.rows;
         }
         else {

package/dist/cjs/query-builder/where-interface.d.ts

@@ -26,7 +26,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use `db.raw('your operator')`.
+     * you can always use `sql\`your operator\``.
      *
      * ```ts
      * const persons = await db
@@ -96,7 +96,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      *
      * A `where in` query can be built by using the `in` operator and an array
      * of values. The values in the array can also be subqueries or raw
-     * instances.
+     * {@link sql} expressions.
      *
      * ```ts
      * const persons = await db
@@ -112,15 +112,17 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * If everything else fails, you can always pass {@link Kysely.raw | raw}
+     * If everything else fails, you can always use the {@link sql} tag
      * as any of the arguments, including the operator:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     db.raw('coalesce(first_name, last_name)'),
+     *     sql`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -155,24 +157,25 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * ```
      *
      * In all examples above the columns were known at compile time
-     * (except for the `raw` expressions). By default kysely only allows
-     * you to refer to columns that exist in the database **and** can be
-     * referred to in the current query and context.
+     * (except for the raw {@link sql} expressions). By default kysely only
+     * allows you to refer to columns that exist in the database **and**
+     * can be referred to in the current query and context.
      *
      * Sometimes you may want to refer to columns that come from the user
      * input and thus are not available at compile time.
      *
-     * You have two options, `db.raw` or `db.dynamic`. The example below
+     * You have two options, the {@link sql} tag or `db.dynamic`. The example below
      * uses both:
      *
      * ```ts
+     * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
-     *   .orWhere(db.raw('??', [columnFromUserInput]), '=', 2)
+     *   .orWhere(sql.id(columnFromUserInput), '=', 2)
      *   .execute()
      * ```
      */
@@ -306,13 +309,14 @@ export interface WhereInterface<DB, TB extends keyof DB> {
     /**
      * Adds a `where exists` clause to the query.
      *
-     * You can either use a subquery or a raw instance.
+     * You can either use a subquery or a raw {@link sql} snippet.
      *
      * ### Examples
      *
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
+     * const petName = 'Catto'
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -320,7 +324,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      *     .selectFrom('pet')
      *     .select('pet.id')
      *     .whereRef('person.id', '=', 'pet.owner_id')
-     *     .where('pet.name', '=', 'Catto')
+     *     .where('pet.name', '=', petName)
      *   )
      *   .execute()
      * ```
@@ -337,16 +341,16 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * )
      * ```
      *
-     * The same query as in the previous example but with using raw:
+     * The same query as in the previous example but with using raw {@link sql}:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const petName = 'Catto'
      * db.selectFrom('person')
      *   .selectAll()
      *   .whereExists(
-     *     db.raw(
-     *       '(select pet.id from pet where person.id = pet.owner_id and pet.name = ?)',
-     *       ['Catto']
-     *     )
+     *     sql`(select pet.id from pet where person.id = pet.owner_id and pet.name = ${petName})`
      *   )
      * ```
      *

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

@@ -29,9 +29,9 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
     }
     visitSelectQuery(node) {
         const wrapInParens = this.parentNode !== undefined &&
+            !insert_query_node_js_1.InsertQueryNode.is(this.parentNode) &&
             !create_view_node_js_1.CreateViewNode.is(this.parentNode) &&
-            !union_node_js_1.UnionNode.is(this.parentNode) &&
-            !insert_query_node_js_1.InsertQueryNode.is(this.parentNode);
+            !union_node_js_1.UnionNode.is(this.parentNode);
         if (wrapInParens) {
             this.append('(');
         }
@@ -190,6 +190,14 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
             this.append(' ');
             this.visitNode(node.where);
         }
+        if (node.orderBy) {
+            this.append(' ');
+            this.visitNode(node.orderBy);
+        }
+        if (node.limit) {
+            this.append(' ');
+            this.visitNode(node.limit);
+        }
         if (node.returning) {
             this.append(' ');
             this.visitNode(node.returning);
@@ -285,12 +293,13 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         this.visitNode(node.on);
     }
     visitRaw(node) {
-        node.sqlFragments.forEach((sql, i) => {
-            this.append(sql);
-            if (node.params.length > i) {
-                this.visitNode(node.params[i]);
+        const { sqlFragments, parameters: params } = node;
+        for (let i = 0; i < sqlFragments.length; ++i) {
+            this.append(sqlFragments[i]);
+            if (params.length > i) {
+                this.visitNode(params[i]);
             }
-        });
+        }
     }
     visitOperator(node) {
         this.append(node.operator);

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

@@ -4,10 +4,8 @@ import { DeleteQueryBuilder } from './query-builder/delete-query-builder.js';
 import { UpdateQueryBuilder } from './query-builder/update-query-builder.js';
 import { TableExpression, TableExpressionDatabase, TableExpressionTables, TableReference } from './parser/table-parser.js';
 import { QueryExecutor } from './query-executor/query-executor.js';
-import { RawBuilder } from './raw-builder/raw-builder.js';
 import { CommonTableExpression, QueryCreatorWithCommonTableExpression, RecursiveCommonTableExpression } from './parser/with-parser.js';
 import { WithNode } from './operation-node/with-node.js';
-import { ParseContext } from './parser/parse-context.js';
 import { InsertResult } from './query-builder/insert-result.js';
 import { DeleteResult } from './query-builder/delete-result.js';
 import { UpdateResult } from './query-builder/update-result.js';
@@ -73,9 +71,10 @@ export declare class QueryCreator<DB> {
      * Create a select query from raw sql:
      *
      * ```ts
-     * const items = await db.selectFrom(
-     *     db.raw<{ one: number }>('(select 1 as one)').as('q')
-     *   )
+     * import { sql } from 'kysely'
+     *
+     * const items = await db
+     *   .selectFrom(sql<{ one: number }>`(select 1 as one)`.as('q'))
      *   .select('q.one')
      *   .execute()
      *
@@ -91,18 +90,20 @@ export declare class QueryCreator<DB> {
      * ) as q
      * ```
      *
-     * When you use `raw` you need to also provide the result type of the
-     * raw segment / query so that Kysely can figure out what columns are
-     * available for the query.
+     * When you use the `sql` tag you need to also provide the result type of the
+     * raw snippet / query so that Kysely can figure out what columns are
+     * available for the rest of the query.
      *
      * The `selectFrom` method also accepts an array for multiple tables. All
      * the above examples can also be used in an array.
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const items = await db.selectFrom([
      *     'person as p',
      *     db.selectFrom('pet').select('pet.species').as('a'),
-     *     db.raw<{ one: number }>('(select 1 as one)').as('q')
+     *     sql<{ one: number }>`(select 1 as one)`.as('q')
      *   ])
      *   .select(['p.id', 'a.species', 'q.one'])
      *   .execute()
@@ -258,14 +259,18 @@ export declare class QueryCreator<DB> {
      * 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/recipes/schemas.md)
+     * for a more detailed explanation.
+     *
      * ### Examples
      *
      * ```
-     * await db.withSchema('mammals')
-     *  .selectFrom('pet')
-     *  .selectAll()
-     *  .innerJoin('public.person', 'public.person.id', 'pet.owner_id')
-     *  .execute()
+     * await db
+     *   .withSchema('mammals')
+     *   .selectFrom('pet')
+     *   .selectAll()
+     *   .innerJoin('public.person', 'public.person.id', 'pet.owner_id')
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -281,10 +286,11 @@ export declare class QueryCreator<DB> {
      * doesn't belong to:
      *
      * ```
-     * await db.withSchema('mammals')
-     *  .selectFrom('pet as p')
-     *  .select('p.name')
-     *  .execute()
+     * await db
+     *   .withSchema('mammals')
+     *   .selectFrom('pet as p')
+     *   .select('p.name')
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -294,128 +300,8 @@ export declare class QueryCreator<DB> {
      * ```
      */
     withSchema(schema: string): QueryCreator<DB>;
-    /**
-     * Provides a way to pass arbitrary SQL into your query and executing completely
-     * raw queries.
-     *
-     * You can use the strings `?` and `??` in the `sql` to bind parameters such as
-     * user input to the SQL. You should never EVER concatenate untrusted user
-     * input to the SQL string to avoid injection vulnerabilities. Instead use `?`
-     * in place of a value and pass the actual value in the `parameters` list. See
-     * the examples below.
-     *
-     * You should only use `raw` when there is no other way to get the job done. This is
-     * because Kysely is not able to use type inference when you use raw SQL. For example
-     * Kysely won't be able to automatically provide you with the correct query result
-     * type. However, there are ways to manually provide types when you use `raw` in most
-     * cases. See the examples below.
-     *
-     * Raw builder instances can be passed to pretty much anywhere: `select`, `where`,
-     * `*Join`, `groupBy`, `orderBy` etc. Just try it. If the method accepts it, it works.
-     *
-     * ### Examples
-     *
-     * Example of using `raw` in a select statement:
-     *
-     * ```ts
-     * const [person] = await db.selectFrom('person')
-     *   .select(db.raw<string>('concat(first_name, ' ', last_name)').as('name'))
-     *   .where('id', '=', 1)
-     *   .execute()
-     *
-     * console.log(person.name)
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select concat(first_name, ' ', last_name) as "name"
-     * from "person" where "id" = 1
-     * ```
-     *
-     * The above example selects computed column `name` by concatenating the first name
-     * and last name together.
-     *
-     * There are couple of things worth noticing:
-     *
-     *   1. You need to provide the output type of your SQL segment for the `raw` method
-     *     so that Kysely knows what type to give for the `name` column. In this case it's
-     *     a `string` since that's the output type of the `concat` function in SQL.
-     *
-     *   2. You need to give an alias for the selection using the `as` method so that
-     *     Kysely is able to add a column to the output type. The alias needs to be
-     *     known at compile time! If you pass a string variable whose value is not known
-     *     at compile time, there is no way for Kysely or typescript to add a column to
-     *     the output type. In this case you need to use the `castTo` method on the query
-     *     to specify a return type for the query.
-     *
-     * We could've also used a `??` placeholder to provide `first_name` and `last_name` like
-     * this:
-     *
-     * ```ts
-     * db.raw<string>('concat(??, ' ', ??)', ['first_name', 'last_name'])
-     * ```
-     *
-     * or this:
-     *
-     * ```ts
-     * db.raw<string>('concat(??, ' ', ??)', ['person.first_name', 'person.last_name'])
-     * ```
-     *
-     * But it's often cleaner to just write the column names in the SQL. Again remember to
-     * never concatenate column names or any other untrusted user input to the SQL string or you
-     * are going to create an injection vulnerability. All user input should go to the parameters
-     * array, never to the SQL string directly. But if the column names or values are trusted
-     * and known at compile time, there is no reason to use parameters.
-     *
-     * Example of using `raw` in `where`:
-     *
-     * ```ts
-     * function getPersonsOlderThan(ageLimit: number) {
-     *   return await db.selectFrom('person')
-     *     .selectAll()
-     *     .where(
-     *       db.raw('now() - birth_date'),
-     *       '>',
-     *       db.raw('interval ? year', [ageLimit.toString()])
-     *     )
-     *     .execute()
-     * }
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" where now() - birth_date > interval $1 year
-     * ```
-     *
-     * The function in the above example returns people that are older than the given number of
-     * years. The number of years in this example is an untrusted user input, and therefore we use
-     * a `?` placeholder for it.
-     *
-     * Example of creating a completely raw query from scratch:
-     *
-     * ```ts
-     * const result = await db.raw<Person>('select p.* from person p').execute()
-     * const persons = result.rows
-     * ```
-     *
-     * For a raw query, you need to specify the type of the returned __row__. In
-     * this case we know the resulting items will be of type `Person` se specify that.
-     * The result of `execute()` method is always an array. In this case the type of
-     * the `persons` variable is `Person[]`.
-     *
-     * @param sql - The raw SQL. Special strings `?` and `??` can be used as parameter
-     *    placeholders. `?` for values and `??` for identifiers such as column names
-     *    or `column.table` references.
-     *
-     * @param params - The parameters that will be bound to the `?` and `??` placeholders in
-     *    the sql string.
-     */
-    raw<T = unknown>(sql: string, parameters?: unknown[]): RawBuilder<T>;
 }
 export interface QueryCreatorProps {
     readonly executor: QueryExecutor;
-    readonly parseContext: ParseContext;
     readonly withNode?: WithNode;
 }