kysely 0.16.11 → 0.17.0

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

@@ -1,74 +1,84 @@
 /// <reference types="./raw-builder.d.ts" />
 import { AliasNode } from '../operation-node/alias-node.js';
-import { isOperationNodeSource, } from '../operation-node/operation-node-source.js';
-import { RawNode } from '../operation-node/raw-node.js';
-import { ValueNode } from '../operation-node/value-node.js';
-import { parseStringReference } from '../parser/reference-parser.js';
 import { preventAwait } from '../util/prevent-await.js';
-import { createQueryId } from '../util/query-id.js';
 import { freeze } from '../util/object-utils.js';
-import { NoopQueryExecutor } from '../query-executor/noop-query-executor.js';
+import { NOOP_QUERY_EXECUTOR } from '../query-executor/noop-query-executor.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 class RawBuilder {
     #props;
     constructor(props) {
-        this.#props = freeze({
-            queryId: props.queryId ?? createQueryId(),
-            executor: props.executor ?? new NoopQueryExecutor(),
-            sql: props.sql,
-            parameters: props.parameters,
-        });
+        this.#props = freeze(props);
     }
+    /**
+     * Returns an aliased version of the SQL expression.
+     *
+     * In addition to slapping `as "the_alias"` to the end of the SQL,
+     * this method also provides strict typing:
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select(
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
+     *   )
+     *   .executeTakeFirstOrThrow()
+     *
+     * // `full_name: string` field exists in the result type.
+     * console.log(result.full_name)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```ts
+     * select concat(first_name, ' ', last_name) as "full_name"
+     * from "person"
+     * ```
+     */
     as(alias) {
         return new AliasedRawBuilder(this, alias);
     }
     /**
      * Change the output type of the raw expression.
      *
-     * This doesn't produce any SQL. This methods simply returns a copy
-     * of this `RawBuilder` with a new output type.
+     * This method call doesn't change the SQL in any way. This methods simply
+     * returns a copy of this `RawBuilder` with a new output type.
      */
     castTo() {
-        return new RawBuilder({
-            ...this.#props,
-        });
+        return new RawBuilder({ ...this.#props });
     }
+    /**
+     * Adds a plugin for this SQL snippet.
+     */
     withPlugin(plugin) {
         return new RawBuilder({
             ...this.#props,
-            executor: this.#props.executor.withPlugin(plugin),
+            plugins: this.#props.plugins !== undefined
+                ? freeze([...this.#props.plugins, plugin])
+                : freeze([plugin]),
         });
     }
     toOperationNode() {
-        const parameterPlaceholderRegex = /(\?\??)/g;
-        const sql = this.#props.sql;
-        const parameters = this.#props.parameters ?? [];
-        const sqlFragments = [];
-        const argNodes = [];
-        let paramIdx = 0;
-        let sqlIdx = 0;
-        let match = null;
-        while ((match = parameterPlaceholderRegex.exec(sql))) {
-            const str = match[1];
-            if (paramIdx >= parameters.length) {
-                throw new Error(`value not provided for all placeholders in string ${sql}`);
-            }
-            if (match.index > 0 && sql[match.index - 1] === '\\') {
-                continue;
-            }
-            sqlFragments.push(sql.slice(sqlIdx, match.index).replace(/\\\?/g, '?'));
-            argNodes.push(parseRawArg(str, parameters[paramIdx]));
-            sqlIdx = match.index + str.length;
-            ++paramIdx;
-        }
-        sqlFragments.push(sql.slice(sqlIdx));
-        const rawNode = RawNode.create(sqlFragments, argNodes);
-        return this.#props.executor.transformQuery(rawNode, this.#props.queryId);
+        const executor = this.#props.plugins !== undefined
+            ? NOOP_QUERY_EXECUTOR.withPlugins(this.#props.plugins)
+            : NOOP_QUERY_EXECUTOR;
+        return this.#toOperationNode(executor);
     }
-    compile() {
-        return this.#props.executor.compileQuery(this.toOperationNode(), this.#props.queryId);
+    async execute(executorProvider) {
+        const executor = this.#props.plugins !== undefined
+            ? executorProvider.getExecutor().withPlugins(this.#props.plugins)
+            : executorProvider.getExecutor();
+        return executor.executeQuery(this.#compile(executor), this.#props.queryId);
     }
-    async execute() {
-        return this.#props.executor.executeQuery(this.compile(), this.#props.queryId);
+    #toOperationNode(executor) {
+        return executor.transformQuery(this.#props.rawNode, this.#props.queryId);
+    }
+    #compile(executor) {
+        return executor.compileQuery(this.#toOperationNode(executor), this.#props.queryId);
     }
 }
 preventAwait(RawBuilder, "don't await RawBuilder instances directly. To execute the query you need to call `execute`");
@@ -97,14 +107,3 @@ export class AliasedRawBuilder {
         this.#alias = alias;
     }
 }
-function parseRawArg(match, arg) {
-    if (isOperationNodeSource(arg)) {
-        return arg.toOperationNode();
-    }
-    else if (match === '??') {
-        return parseStringReference(arg);
-    }
-    else {
-        return ValueNode.create(arg);
-    }
-}

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

@@ -0,0 +1,323 @@
+import { RawBuilder } from './raw-builder.js';
+export interface Sql {
+    <T = unknown>(sqlFragments: TemplateStringsArray, ...parameters: unknown[]): RawBuilder<T>;
+    /**
+     * This can be used to add runtime column references to SQL snippets.
+     *
+     * By default `${}` substitutions in {@link sql} template strings get
+     * transformed into parameters. You can use this function to tell
+     * Kysely to interpret them as column references instead.
+     *
+     * WARNING! Using this with unchecked inputs WILL lead to SQL injection
+     * vulnerabilities. The input is not checked or escaped by Kysely in any way.
+     *
+     * ```ts
+     * const columnRef = 'first_name'
+     *
+     * sql`select ${sql.ref(columnRef)} from person`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name" from person
+     * ```
+     *
+     * The refefences can also include a table name:
+     *
+     * ```ts
+     * const columnRef = 'person.first_name'
+     *
+     * sql`select ${sql.ref(columnRef)}} from person`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" from person
+     * ```
+     *
+     * The refefences can also include a schema on supported databases:
+     *
+     * ```ts
+     * const columnRef = 'public.person.first_name'
+     *
+     * sql`select ${sql.ref(columnRef)}} from person`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "public"."person"."first_name" from person
+     * ```
+     */
+    ref(columnReference: string): RawBuilder<unknown>;
+    /**
+     * This can be used to add runtime table references to SQL snippets.
+     *
+     * By default `${}` substitutions in {@link sql} template strings get
+     * transformed into parameters. You can use this function to tell
+     * Kysely to interpret them as table references instead.
+     *
+     * WARNING! Using this with unchecked inputs WILL lead to SQL injection
+     * vulnerabilities. The input is not checked or escaped by Kysely in any way.
+     *
+     * ```ts
+     * const table = 'person'
+     *
+     * sql`select first_name from ${sql.table(table)}`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select first_name from "person"
+     * ```
+     *
+     * The refefences can also include a schema on supported databases:
+     *
+     * ```ts
+     * const table = 'public.person'
+     *
+     * sql`select first_name from ${sql.table(table)}`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select first_name from "public"."person"
+     * ```
+     */
+    table(tableReference: string): RawBuilder<unknown>;
+    /**
+     * This can be used to add arbitrary identifiers to SQL snippets.
+     *
+     * Does the same thing as {@link Sql.ref | ref} and {@link Sql.table | table}
+     * 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
+     * operation node tree.
+     *
+     * WARNING! Using this with unchecked inputs WILL lead to SQL injection
+     * vulnerabilities. The input is not checked or escaped by Kysely in any way.
+     *
+     * ```ts
+     * const indexName = 'person_first_name_index'
+     *
+     * sql`create index ${indexName} on person`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create index "person_first_name_index" on person
+     * ```
+     *
+     * Multiple identifiers get separated by dots:
+     *
+     * ```ts
+     * const schema = 'public'
+     * const columnName = 'first_name'
+     * const table = 'person'
+     *
+     * sql`select ${sql.id(schema, table, columnName)}} from ${sql.id(schema, table)}`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "public"."person"."first_name" from "public"."person"
+     * ```
+     */
+    id(...ids: string[]): RawBuilder<unknown>;
+    /**
+     * This can be used to add literal values to SQL snippets.
+     *
+     * WARNING! Using this with unchecked inputs WILL lead to SQL injection
+     * vulnerabilities. The input is not checked or escaped by Kysely in any way.
+     * You almost always want to use normal substitutions that get sent to the
+     * db as parameters.
+     *
+     * ```ts
+     * const firstName = 'first_name'
+     *
+     * sql`select * from person where first_name = ${sql.literal(firstName)}`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from person where first_name = 'first_name'
+     * ```
+     *
+     * As you can see from the example above, the value was added directly to
+     * the SQL string instead of as a parameter. Only use this function when
+     * something can't be sent as a parameter.
+     */
+    literal(value: unknown): RawBuilder<unknown>;
+    /**
+     * This can be used to add arbitrary runtime SQL to SQL snippets.
+     *
+     * WARNING! Using this with unchecked inputs WILL lead to SQL injection
+     * vulnerabilities. The input is not checked or escaped by Kysely in any way.
+     *
+     * ```ts
+     * const firstName = "'first_name'"
+     *
+     * sql`select * from person where first_name = ${sql.raw(firstName)}`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from person where first_name = 'first_name'
+     * ```
+     *
+     * Note that the difference to `sql.literal` is that this function
+     * doesn't assume the inputs are values. The input to this function
+     * can be any sql and it's simply glued to the parent string as-is.
+     */
+    raw(anySql: string): RawBuilder<unknown>;
+    /**
+     * This can be used to add lists of things to SQL snippets.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * function findByNicknames(nicknames: string[]): Promise<Person[]> {
+     *   return db
+     *     .selectFrom('person')
+     *     .selectAll()
+     *     .where('nicknames', '@>', sql`ARRAY[${sql.join(nicknames)}]`)
+     *     .execute()
+     * }
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from "person"
+     * where "nicknames" @> ARRAY[$1, $2, $3, $4, $5, $6, $7, $8]
+     * ```
+     *
+     * The second argument is the joining SQL expression that defaults
+     * to
+     *
+     * ```ts
+     * sql`, `
+     * ```
+     *
+     * In addition to values, items in the list can be also {@link sql}
+     * expressions, queries or anything else the normal substitutions
+     * support:
+     *
+     * ```ts
+     * const things = [
+     *   123,
+     *   sql`(1 == 1)`,
+     *   db.selectFrom('person').selectAll(),
+     *   sql.literal(false),
+     *   sql.id('first_name')
+     * ]
+     *
+     * sql`BEFORE ${sql.array(things, sql`::varchar, `)} AFTER`
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * BEFORE $1::varchar, (1 == 1)::varchar, (select * from "person")::varchar, false::varchar, "first_name" AFTER
+     * ```
+     */
+    join(array: unknown[], separator?: RawBuilder<any>): RawBuilder<unknown>;
+}
+/**
+ * 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 concate(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) => sql<string>`concat(${eb.ref('first_name')}, ' ', ${eb.ref('last_name')})`.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 declare const sql: Sql;

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

@@ -0,0 +1,151 @@
+/// <reference types="./sql.d.ts" />
+import { IdentifierNode } from '../operation-node/identifier-node.js';
+import { RawNode } from '../operation-node/raw-node.js';
+import { ValueNode } from '../operation-node/value-node.js';
+import { parseStringReference } from '../parser/reference-parser.js';
+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 concate(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) => sql<string>`concat(${eb.ref('first_name')}, ' ', ${eb.ref('last_name')})`.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(),
+        rawNode: RawNode.create(sqlFragments, parameters?.map(parseValueExpression) ?? []),
+    });
+}, {
+    ref(columnReference) {
+        return new RawBuilder({
+            queryId: createQueryId(),
+            rawNode: RawNode.createWithChild(parseStringReference(columnReference)),
+        });
+    },
+    table(tableReference) {
+        return new RawBuilder({
+            queryId: createQueryId(),
+            rawNode: RawNode.createWithChild(parseTable(tableReference)),
+        });
+    },
+    id(...ids) {
+        const fragments = new Array(ids.length + 1).fill('.');
+        fragments[0] = '';
+        fragments[fragments.length - 1] = '';
+        return new RawBuilder({
+            queryId: createQueryId(),
+            rawNode: RawNode.create(fragments, ids.map(IdentifierNode.create)),
+        });
+    },
+    literal(value) {
+        return new RawBuilder({
+            queryId: createQueryId(),
+            rawNode: RawNode.createWithChild(ValueNode.createImmediate(value)),
+        });
+    },
+    raw(sql) {
+        return new RawBuilder({
+            queryId: createQueryId(),
+            rawNode: RawNode.createWithSql(sql),
+        });
+    },
+    join(array, separator = sql `, `) {
+        const nodes = new Array(2 * array.length - 1);
+        const sep = separator.toOperationNode();
+        for (let i = 0; i < array.length; ++i) {
+            nodes[2 * i] = parseValueExpression(array[i]);
+            if (i !== array.length - 1) {
+                nodes[2 * i + 1] = sep;
+            }
+        }
+        return new RawBuilder({
+            queryId: createQueryId(),
+            rawNode: RawNode.createWithChildren(nodes),
+        });
+    },
+});