kysely 0.16.9 → 0.17.1

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

@@ -2,75 +2,85 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AliasedRawBuilder = exports.RawBuilder = void 0;
 const alias_node_js_1 = require("../operation-node/alias-node.js");
-const operation_node_source_js_1 = require("../operation-node/operation-node-source.js");
-const raw_node_js_1 = require("../operation-node/raw-node.js");
-const value_node_js_1 = require("../operation-node/value-node.js");
-const reference_parser_js_1 = require("../parser/reference-parser.js");
 const prevent_await_js_1 = require("../util/prevent-await.js");
-const query_id_js_1 = require("../util/query-id.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 const noop_query_executor_js_1 = require("../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.
+ */
 class RawBuilder {
     #props;
     constructor(props) {
-        this.#props = (0, object_utils_js_1.freeze)({
-            queryId: props.queryId ?? (0, query_id_js_1.createQueryId)(),
-            executor: props.executor ?? new noop_query_executor_js_1.NoopQueryExecutor(),
-            sql: props.sql,
-            parameters: props.parameters,
-        });
+        this.#props = (0, object_utils_js_1.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
+                ? (0, object_utils_js_1.freeze)([...this.#props.plugins, plugin])
+                : (0, object_utils_js_1.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 = raw_node_js_1.RawNode.create(sqlFragments, argNodes);
-        return this.#props.executor.transformQuery(rawNode, this.#props.queryId);
+        const executor = this.#props.plugins !== undefined
+            ? noop_query_executor_js_1.NOOP_QUERY_EXECUTOR.withPlugins(this.#props.plugins)
+            : noop_query_executor_js_1.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);
     }
 }
 exports.RawBuilder = RawBuilder;
@@ -101,14 +111,3 @@ class AliasedRawBuilder {
     }
 }
 exports.AliasedRawBuilder = AliasedRawBuilder;
-function parseRawArg(match, arg) {
-    if ((0, operation_node_source_js_1.isOperationNodeSource)(arg)) {
-        return arg.toOperationNode();
-    }
-    else if (match === '??') {
-        return (0, reference_parser_js_1.parseStringReference)(arg);
-    }
-    else {
-        return value_node_js_1.ValueNode.create(arg);
-    }
-}

package/dist/cjs/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/cjs/raw-builder/sql.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sql = void 0;
+const identifier_node_js_1 = require("../operation-node/identifier-node.js");
+const raw_node_js_1 = require("../operation-node/raw-node.js");
+const value_node_js_1 = require("../operation-node/value-node.js");
+const reference_parser_js_1 = require("../parser/reference-parser.js");
+const table_parser_js_1 = require("../parser/table-parser.js");
+const value_parser_js_1 = require("../parser/value-parser.js");
+const query_id_js_1 = require("../util/query-id.js");
+const raw_builder_js_1 = require("./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.
+ */
+exports.sql = Object.assign((sqlFragments, ...parameters) => {
+    return new raw_builder_js_1.RawBuilder({
+        queryId: (0, query_id_js_1.createQueryId)(),
+        rawNode: raw_node_js_1.RawNode.create(sqlFragments, parameters?.map(value_parser_js_1.parseValueExpression) ?? []),
+    });
+}, {
+    ref(columnReference) {
+        return new raw_builder_js_1.RawBuilder({
+            queryId: (0, query_id_js_1.createQueryId)(),
+            rawNode: raw_node_js_1.RawNode.createWithChild((0, reference_parser_js_1.parseStringReference)(columnReference)),
+        });
+    },
+    table(tableReference) {
+        return new raw_builder_js_1.RawBuilder({
+            queryId: (0, query_id_js_1.createQueryId)(),
+            rawNode: raw_node_js_1.RawNode.createWithChild((0, table_parser_js_1.parseTable)(tableReference)),
+        });
+    },
+    id(...ids) {
+        const fragments = new Array(ids.length + 1).fill('.');
+        fragments[0] = '';
+        fragments[fragments.length - 1] = '';
+        return new raw_builder_js_1.RawBuilder({
+            queryId: (0, query_id_js_1.createQueryId)(),
+            rawNode: raw_node_js_1.RawNode.create(fragments, ids.map(identifier_node_js_1.IdentifierNode.create)),
+        });
+    },
+    literal(value) {
+        return new raw_builder_js_1.RawBuilder({
+            queryId: (0, query_id_js_1.createQueryId)(),
+            rawNode: raw_node_js_1.RawNode.createWithChild(value_node_js_1.ValueNode.createImmediate(value)),
+        });
+    },
+    raw(sql) {
+        return new raw_builder_js_1.RawBuilder({
+            queryId: (0, query_id_js_1.createQueryId)(),
+            rawNode: raw_node_js_1.RawNode.createWithSql(sql),
+        });
+    },
+    join(array, separator = (0, exports.sql) `, `) {
+        const nodes = new Array(2 * array.length - 1);
+        const sep = separator.toOperationNode();
+        for (let i = 0; i < array.length; ++i) {
+            nodes[2 * i] = (0, value_parser_js_1.parseValueExpression)(array[i]);
+            if (i !== array.length - 1) {
+                nodes[2 * i + 1] = sep;
+            }
+        }
+        return new raw_builder_js_1.RawBuilder({
+            queryId: (0, query_id_js_1.createQueryId)(),
+            rawNode: raw_node_js_1.RawNode.createWithChildren(nodes),
+        });
+    },
+});