kysely 0.16.3 → 0.16.7

package/README.md

@@ -3,14 +3,15 @@
 
 # [Kysely](https://koskimas.github.io/kysely/index.html)
 
-A type-safe and autocompletion-friendly typescript SQL query builder for node.js. Inspired by
-[knex](http://knexjs.org/).
+A type-safe and autocompletion-friendly typescript SQL query builder. Inspired by [knex](http://knexjs.org/).
+Mainly developed for [node.js](https://nodejs.org/en/) but also runs on [deno](https://deno.land/) and
+in the browser.
 
 ![](https://github.com/koskimas/kysely/blob/master/assets/demo.gif)
 
-Kysely's typings make sure you only refer to tables and columns that are visible to the part of the query
-you are writing. The result type only has the selected columns with correct types and aliases. This 
-allows tools like vscode autocompletion to make your life so much easier.
+Kysely makes sure you only refer to tables and columns that are visible to the part of the query
+you are writing. The result type only has the selected columns with correct types and aliases. As an
+added bonus you get autocompletion for all that stuff.
 
 As you can see in the gif above, through the pure magic of modern typescript, Kysely is even able to parse
 the alias given to `pet.name` and add the `pet_name` column to the result row type. Kysely is able to infer
@@ -32,7 +33,10 @@ You can find a more thorough introduction [here](https://www.jakso.me/blog/kysel
 - [Installation](#installation)
 - [Minimal example](#minimal-example)
 - [Query examples](#query-examples)
+- [Recipes](https://github.com/koskimas/kysely/tree/master/recipes)
 - [Migrations](#migrations)
+- [Deno](#deno)
+- [Browser](#browser)
 - [API reference](https://koskimas.github.io/kysely/index.html)
 - [Changelog](https://github.com/koskimas/kysely/releases)
 
@@ -162,19 +166,19 @@ type UpdateablePerson = Updateable<PersonTable>
 ## Select queries
 
 You can find examples of select queries in the documentation of the 
-[select method](https://koskimas.github.io/kysely/classes/QueryBuilder.html#select) and
-the [where method](https://koskimas.github.io/kysely/classes/QueryBuilder.html#where) 
+[select method](https://koskimas.github.io/kysely/classes/SelectQueryBuilder.html#select) and
+the [where method](https://koskimas.github.io/kysely/classes/SelectQueryBuilder.html#where)
 among other places.
 
 ## Update queries
 
-See the [set method](https://koskimas.github.io/kysely/classes/QueryBuilder.html#set) and the
+See the [set method](https://koskimas.github.io/kysely/classes/UpdateQueryBuilder.html#set) and the
 [updateTable method](https://koskimas.github.io/kysely/classes/Kysely.html#updateTable)
 documentation.
 
 ## Insert queries
 
-See the [values method](https://koskimas.github.io/kysely/classes/QueryBuilder.html#values) and the
+See the [values method](https://koskimas.github.io/kysely/classes/InsertQueryBuilder.html#values) and the
 [insertInto method](https://koskimas.github.io/kysely/classes/Kysely.html#insertInto)
 documentation.
 
@@ -341,6 +345,8 @@ async function migrateToLatest() {
     console.error(error)
     process.exit(1)
   }
+
+  await db.destroy()
 }
 
 migrateToLatest()
@@ -350,6 +356,113 @@ The migration methods use a lock on the database level, and parallel calls are e
 This means that you can safely call `migrateToLatest` and other migration methods from multiple
 server instances simultaneously and the migrations are guaranteed to only be executed once.
 
+# Deno
+
+Kysely doesn't include drivers for deno, but you can still use Kysely as a query builder
+or implement your own driver:
+
+```ts
+// We use jsdeliver to get Kysely from npm. We also need to
+// import the `dist/esm/index-nodeless.js` file instead of the
+// root which has node dependencies.
+import {
+  DummyDriver,
+  Generated,
+  Kysely,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+} from 'https://cdn.jsdelivr.net/npm/kysely/dist/esm/index-nodeless.js'
+
+interface Person {
+  id: Generated<number>
+  first_name: string
+  last_name: string | null
+}
+
+interface Database {
+  person: Person
+}
+
+const db = new Kysely<Database>({
+  dialect: {
+    createAdapter() {
+      return new PostgresAdapter()
+    },
+    createDriver() {
+      // You need a driver to be able to execute queries. In this example
+      // we use the dummy driver that never does anything.
+      return new DummyDriver()
+    },
+    createIntrospector(db: Kysely<unknown>) {
+      return new PostgresIntrospector(db)
+    },
+    createQueryCompiler() {
+      return new PostgresQueryCompiler()
+    },
+  },
+})
+
+const query = db.selectFrom('person').select('id')
+const sql = query.compile()
+
+console.log(sql.sql)
+```
+
+# Browser
+
+Kysely also runs in the browser as long as you import the `dist/esm/index-nodeless.js`
+module instead of the root that has node dependencies. You can also import the
+`dist/cjs/index-nodeless.js` file if you are using commonjs modules instead of ESM.
+
+```ts
+import {
+  Kysely,
+  Generated,
+  DummyDriver,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+} from 'kysely/dist/esm/index-nodeless.js'
+
+interface Person {
+  id: Generated<number>
+  first_name: string
+  last_name: string | null
+}
+
+interface Database {
+  person: Person
+}
+
+const db = new Kysely<Database>({
+  dialect: {
+    createAdapter() {
+      return new SqliteAdapter()
+    },
+    createDriver() {
+      return new DummyDriver()
+    },
+    createIntrospector(db: Kysely<unknown>) {
+      return new SqliteIntrospector(db)
+    },
+    createQueryCompiler() {
+      return new SqliteQueryCompiler()
+    },
+  },
+})
+
+window.addEventListener('load', () => {
+  const sql = db.selectFrom('person').select('id').compile()
+
+  const result = document.createElement('span')
+  result.id = 'result'
+  result.innerHTML = sql.sql
+
+  document.body.appendChild(result)
+})
+```
+
 # Why not just contribute to knex
 
 Kysely is very similar to knex, but it also attempts to fix things that I personally find not-so-good

package/dist/cjs/dialect/mysql/mysql-dialect-config.d.ts

@@ -0,0 +1,205 @@
+import { DatabaseConnection } from '../../driver/database-connection.js';
+/**
+ * Config for the MySQL dialect.
+ *
+ * This interface is equal to `mysql2` library's pool config.
+ *
+ * https://github.com/sidorares/node-mysql2#using-connection-pools
+ */
+export interface MysqlDialectConfig {
+    /**
+     * The MySQL user to authenticate as
+     */
+    user?: string;
+    /**
+     * The password of that MySQL user
+     */
+    password?: string;
+    /**
+     * Name of the database to use for this connection
+     */
+    database?: string;
+    /**
+     * The charset for the connection. This is called 'collation' in the SQL-level of MySQL (like utf8_general_ci).
+     * If a SQL-level charset is specified (like utf8mb4) then the default collation for that charset is used.
+     * (Default: 'UTF8_GENERAL_CI')
+     */
+    charset?: string;
+    /**
+     * The hostname of the database you are connecting to. (Default: localhost)
+     */
+    host?: string;
+    /**
+     * The port number to connect to. (Default: 3306)
+     */
+    port?: number;
+    /**
+     * The source IP address to use for TCP connection
+     */
+    localAddress?: string;
+    /**
+     * The path to a unix domain socket to connect to. When used host and port are ignored
+     */
+    socketPath?: string;
+    /**
+     * The timezone used to store local dates. (Default: 'local')
+     */
+    timezone?: string | 'local';
+    /**
+     * The milliseconds before a timeout occurs during the initial connection to the MySQL server. (Default: 10 seconds)
+     */
+    connectTimeout?: number;
+    /**
+     * Stringify objects instead of converting to values. (Default: 'false')
+     */
+    stringifyObjects?: boolean;
+    /**
+     * Allow connecting to MySQL instances that ask for the old (insecure) authentication method. (Default: false)
+     */
+    insecureAuth?: boolean;
+    /**
+     * Determines if column values should be converted to native JavaScript types. It is not recommended (and may go away / change in the future)
+     * to disable type casting, but you can currently do so on either the connection or query level. (Default: true)
+     *
+     * You can also specify a function (field: any, next: () => void) => {} to do the type casting yourself.
+     *
+     * WARNING: YOU MUST INVOKE the parser using one of these three field functions in your custom typeCast callback. They can only be called once.
+     *
+     * field.string()
+     * field.buffer()
+     * field.geometry()
+     *
+     * are aliases for
+     *
+     * parser.parseLengthCodedString()
+     * parser.parseLengthCodedBuffer()
+     * parser.parseGeometryValue()
+     *
+     * You can find which field function you need to use by looking at: RowDataPacket.prototype._typeCast
+     */
+    typeCast?: boolean | ((field: any, next: () => void) => any);
+    /**
+     * A custom query format function
+     */
+    queryFormat?: (query: string, values: any) => void;
+    /**
+     * When dealing with big numbers (BIGINT and DECIMAL columns) in the database, you should enable this option
+     * (Default: false)
+     */
+    supportBigNumbers?: boolean;
+    /**
+     * Enabling both supportBigNumbers and bigNumberStrings forces big numbers (BIGINT and DECIMAL columns) to be
+     * always returned as JavaScript String objects (Default: false). Enabling supportBigNumbers but leaving
+     * bigNumberStrings disabled will return big numbers as String objects only when they cannot be accurately
+     * represented with [JavaScript Number objects] (http://ecma262-5.com/ELS5_HTML.htm#Section_8.5)
+     * (which happens when they exceed the [-2^53, +2^53] range), otherwise they will be returned as Number objects.
+     * This option is ignored if supportBigNumbers is disabled.
+     */
+    bigNumberStrings?: boolean;
+    /**
+     * Force date types (TIMESTAMP, DATETIME, DATE) to be returned as strings rather then inflated into JavaScript Date
+     * objects. Can be true/false or an array of type names to keep as strings.
+     *
+     * (Default: false)
+     */
+    dateStrings?: boolean | Array<'TIMESTAMP' | 'DATETIME' | 'DATE'>;
+    /**
+     * This will print all incoming and outgoing packets on stdout.
+     * You can also restrict debugging to packet types by passing an array of types (strings) to debug;
+     *
+     * (Default: false)
+     */
+    debug?: any;
+    /**
+     * Generates stack traces on Error to include call site of library entrance ('long stack traces'). Slight
+     * performance penalty for most calls. (Default: true)
+     */
+    trace?: boolean;
+    /**
+     * Allow multiple MySQL statements per query. Be careful with this, it exposes you to SQL injection attacks. (Default: false)
+     */
+    multipleStatements?: boolean;
+    /**
+     * List of connection flags to use other than the default ones. It is also possible to blacklist default ones
+     */
+    flags?: Array<string>;
+    /**
+     * object with ssl parameters or a string containing name of ssl profile
+     */
+    ssl?: string | MysqlSslOptions;
+    /**
+     * Return each row as an array, not as an object.
+     * This is useful when you have duplicate column names.
+     * This can also be set in the `QueryOption` object to be applied per-query.
+     */
+    rowsAsArray?: boolean;
+    /**
+     * The milliseconds before a timeout occurs during the connection acquisition. This is slightly different from connectTimeout,
+     * because acquiring a pool connection does not always involve making a connection. (Default: 10 seconds)
+     */
+    acquireTimeout?: number;
+    /**
+     * Determines the pool's action when no connections are available and the limit has been reached. If true, the pool will queue
+     * the connection request and call it when one becomes available. If false, the pool will immediately call back with an error.
+     * (Default: true)
+     */
+    waitForConnections?: boolean;
+    /**
+     * The maximum number of connections to create at once. (Default: 10)
+     */
+    connectionLimit?: number;
+    /**
+     * The maximum number of connection requests the pool will queue before returning an error from getConnection. If set to 0, there
+     * is no limit to the number of queued connection requests. (Default: 0)
+     */
+    queueLimit?: number;
+    /**
+     * Enable keep-alive on the socket.  It's disabled by default, but the
+     * user can enable it and supply an initial delay.
+     */
+    enableKeepAlive?: true;
+    /**
+     * If keep-alive is enabled users can supply an initial delay.
+     */
+    keepAliveInitialDelay?: number;
+    /**
+     * Called once for each created connection.
+     *
+     * This is a Kysely specific feature and does not come from the `mysql2` module.
+     */
+    onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
+}
+export interface MysqlSslOptions {
+    /**
+     * A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
+     */
+    pfx?: string;
+    /**
+     * A string holding the PEM encoded private key
+     */
+    key?: string;
+    /**
+     * A string of passphrase for the private key or pfx
+     */
+    passphrase?: string;
+    /**
+     * A string holding the PEM encoded certificate
+     */
+    cert?: string;
+    /**
+     * Either a string or list of strings of PEM encoded CA certificates to trust.
+     */
+    ca?: string | string[];
+    /**
+     * Either a string or list of strings of PEM encoded CRLs (Certificate Revocation List)
+     */
+    crl?: string | string[];
+    /**
+     * A string describing the ciphers to use or exclude
+     */
+    ciphers?: string;
+    /**
+     * You can also connect to a MySQL server without properly providing the appropriate CA to trust. You should not do this.
+     */
+    rejectUnauthorized?: boolean;
+}

package/dist/cjs/dialect/mysql/mysql-dialect-config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/dialect/mysql/mysql-dialect.d.ts

@@ -4,7 +4,7 @@ import { QueryCompiler } from '../../query-compiler/query-compiler.js';
 import { Dialect } from '../dialect.js';
 import { DatabaseIntrospector } from '../database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
-import { DatabaseConnection } from '../../driver/database-connection.js';
+import { MysqlDialectConfig } from './mysql-dialect-config.js';
 /**
  * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
  *
@@ -36,207 +36,3 @@ export declare class MysqlDialect implements Dialect {
      */
     createIntrospector(db: Kysely<any>): DatabaseIntrospector;
 }
-/**
- * Config for the MySQL dialect.
- *
- * This interface is equal to `mysql2` library's pool config.
- *
- * https://github.com/sidorares/node-mysql2#using-connection-pools
- */
-export interface MysqlDialectConfig {
-    /**
-     * The MySQL user to authenticate as
-     */
-    user?: string;
-    /**
-     * The password of that MySQL user
-     */
-    password?: string;
-    /**
-     * Name of the database to use for this connection
-     */
-    database?: string;
-    /**
-     * The charset for the connection. This is called 'collation' in the SQL-level of MySQL (like utf8_general_ci).
-     * If a SQL-level charset is specified (like utf8mb4) then the default collation for that charset is used.
-     * (Default: 'UTF8_GENERAL_CI')
-     */
-    charset?: string;
-    /**
-     * The hostname of the database you are connecting to. (Default: localhost)
-     */
-    host?: string;
-    /**
-     * The port number to connect to. (Default: 3306)
-     */
-    port?: number;
-    /**
-     * The source IP address to use for TCP connection
-     */
-    localAddress?: string;
-    /**
-     * The path to a unix domain socket to connect to. When used host and port are ignored
-     */
-    socketPath?: string;
-    /**
-     * The timezone used to store local dates. (Default: 'local')
-     */
-    timezone?: string | 'local';
-    /**
-     * The milliseconds before a timeout occurs during the initial connection to the MySQL server. (Default: 10 seconds)
-     */
-    connectTimeout?: number;
-    /**
-     * Stringify objects instead of converting to values. (Default: 'false')
-     */
-    stringifyObjects?: boolean;
-    /**
-     * Allow connecting to MySQL instances that ask for the old (insecure) authentication method. (Default: false)
-     */
-    insecureAuth?: boolean;
-    /**
-     * Determines if column values should be converted to native JavaScript types. It is not recommended (and may go away / change in the future)
-     * to disable type casting, but you can currently do so on either the connection or query level. (Default: true)
-     *
-     * You can also specify a function (field: any, next: () => void) => {} to do the type casting yourself.
-     *
-     * WARNING: YOU MUST INVOKE the parser using one of these three field functions in your custom typeCast callback. They can only be called once.
-     *
-     * field.string()
-     * field.buffer()
-     * field.geometry()
-     *
-     * are aliases for
-     *
-     * parser.parseLengthCodedString()
-     * parser.parseLengthCodedBuffer()
-     * parser.parseGeometryValue()
-     *
-     * You can find which field function you need to use by looking at: RowDataPacket.prototype._typeCast
-     */
-    typeCast?: boolean | ((field: any, next: () => void) => any);
-    /**
-     * A custom query format function
-     */
-    queryFormat?: (query: string, values: any) => void;
-    /**
-     * When dealing with big numbers (BIGINT and DECIMAL columns) in the database, you should enable this option
-     * (Default: false)
-     */
-    supportBigNumbers?: boolean;
-    /**
-     * Enabling both supportBigNumbers and bigNumberStrings forces big numbers (BIGINT and DECIMAL columns) to be
-     * always returned as JavaScript String objects (Default: false). Enabling supportBigNumbers but leaving
-     * bigNumberStrings disabled will return big numbers as String objects only when they cannot be accurately
-     * represented with [JavaScript Number objects] (http://ecma262-5.com/ELS5_HTML.htm#Section_8.5)
-     * (which happens when they exceed the [-2^53, +2^53] range), otherwise they will be returned as Number objects.
-     * This option is ignored if supportBigNumbers is disabled.
-     */
-    bigNumberStrings?: boolean;
-    /**
-     * Force date types (TIMESTAMP, DATETIME, DATE) to be returned as strings rather then inflated into JavaScript Date
-     * objects. Can be true/false or an array of type names to keep as strings.
-     *
-     * (Default: false)
-     */
-    dateStrings?: boolean | Array<'TIMESTAMP' | 'DATETIME' | 'DATE'>;
-    /**
-     * This will print all incoming and outgoing packets on stdout.
-     * You can also restrict debugging to packet types by passing an array of types (strings) to debug;
-     *
-     * (Default: false)
-     */
-    debug?: any;
-    /**
-     * Generates stack traces on Error to include call site of library entrance ('long stack traces'). Slight
-     * performance penalty for most calls. (Default: true)
-     */
-    trace?: boolean;
-    /**
-     * Allow multiple MySQL statements per query. Be careful with this, it exposes you to SQL injection attacks. (Default: false)
-     */
-    multipleStatements?: boolean;
-    /**
-     * List of connection flags to use other than the default ones. It is also possible to blacklist default ones
-     */
-    flags?: Array<string>;
-    /**
-     * object with ssl parameters or a string containing name of ssl profile
-     */
-    ssl?: string | MysqlSslOptions;
-    /**
-     * Return each row as an array, not as an object.
-     * This is useful when you have duplicate column names.
-     * This can also be set in the `QueryOption` object to be applied per-query.
-     */
-    rowsAsArray?: boolean;
-    /**
-     * The milliseconds before a timeout occurs during the connection acquisition. This is slightly different from connectTimeout,
-     * because acquiring a pool connection does not always involve making a connection. (Default: 10 seconds)
-     */
-    acquireTimeout?: number;
-    /**
-     * Determines the pool's action when no connections are available and the limit has been reached. If true, the pool will queue
-     * the connection request and call it when one becomes available. If false, the pool will immediately call back with an error.
-     * (Default: true)
-     */
-    waitForConnections?: boolean;
-    /**
-     * The maximum number of connections to create at once. (Default: 10)
-     */
-    connectionLimit?: number;
-    /**
-     * The maximum number of connection requests the pool will queue before returning an error from getConnection. If set to 0, there
-     * is no limit to the number of queued connection requests. (Default: 0)
-     */
-    queueLimit?: number;
-    /**
-     * Enable keep-alive on the socket.  It's disabled by default, but the
-     * user can enable it and supply an initial delay.
-     */
-    enableKeepAlive?: true;
-    /**
-     * If keep-alive is enabled users can supply an initial delay.
-     */
-    keepAliveInitialDelay?: number;
-    /**
-     * Called once for each created connection.
-     *
-     * This is a Kysely specific feature and does not come from the `mysql2` module.
-     */
-    onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
-}
-export interface MysqlSslOptions {
-    /**
-     * A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
-     */
-    pfx?: string;
-    /**
-     * A string holding the PEM encoded private key
-     */
-    key?: string;
-    /**
-     * A string of passphrase for the private key or pfx
-     */
-    passphrase?: string;
-    /**
-     * A string holding the PEM encoded certificate
-     */
-    cert?: string;
-    /**
-     * Either a string or list of strings of PEM encoded CA certificates to trust.
-     */
-    ca?: string | string[];
-    /**
-     * Either a string or list of strings of PEM encoded CRLs (Certificate Revocation List)
-     */
-    crl?: string | string[];
-    /**
-     * A string describing the ciphers to use or exclude
-     */
-    ciphers?: string;
-    /**
-     * You can also connect to a MySQL server without properly providing the appropriate CA to trust. You should not do this.
-     */
-    rejectUnauthorized?: boolean;
-}

package/dist/cjs/dialect/mysql/mysql-dialect.js

@@ -5,6 +5,7 @@ const mysql_driver_js_1 = require("./mysql-driver.js");
 const mysql_query_compiler_js_1 = require("./mysql-query-compiler.js");
 const mysql_introspector_js_1 = require("./mysql-introspector.js");
 const mysql_adapter_js_1 = require("./mysql-adapter.js");
+const object_utils_js_1 = require("../../util/object-utils.js");
 /**
  * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
  *
@@ -15,7 +16,7 @@ const mysql_adapter_js_1 = require("./mysql-adapter.js");
 class MysqlDialect {
     #config;
     constructor(config) {
-        this.#config = config;
+        this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     createDriver() {
         return new mysql_driver_js_1.MysqlDriver(this.#config);

package/dist/cjs/dialect/mysql/mysql-driver.d.ts

@@ -1,6 +1,6 @@
 import { DatabaseConnection } from '../../driver/database-connection.js';
 import { Driver, TransactionSettings } from '../../driver/driver.js';
-import { MysqlDialectConfig } from './mysql-dialect.js';
+import { MysqlDialectConfig } from './mysql-dialect-config.js';
 export declare class MysqlDriver implements Driver {
     #private;
     constructor(config: MysqlDialectConfig);

package/dist/cjs/dialect/mysql/mysql-driver.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MysqlDriver = void 0;
 const compiled_query_js_1 = require("../../query-compiler/compiled-query.js");
-const dynamic_import_js_1 = require("../../util/dynamic-import.js");
 const object_utils_js_1 = require("../../util/object-utils.js");
 const PRIVATE_RELEASE_METHOD = Symbol();
 class MysqlDriver {
@@ -10,7 +9,7 @@ class MysqlDriver {
     #connections = new WeakMap();
     #pool;
     constructor(config) {
-        this.#config = config;
+        this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     async init() {
         // Import the `mysql2` module here instead at the top of the file
@@ -83,7 +82,16 @@ class MysqlDriver {
 exports.MysqlDriver = MysqlDriver;
 async function importMysqlPoolFactory() {
     try {
-        return await (0, dynamic_import_js_1.importNamedFunction)('mysql2', 'createPool');
+        // The imported module name must be a string literal to make
+        // some bundlers work. So don't move this code behind a helper
+        // for example.
+        const mysqlModule = await Promise.resolve().then(() => require('mysql2'));
+        if ((0, object_utils_js_1.isFunction)(mysqlModule.createPool)) {
+            return mysqlModule.createPool;
+        }
+        else {
+            return mysqlModule.default.createPool;
+        }
     }
     catch (error) {
         throw new Error('MySQL client not installed. Please run `npm install mysql2`');