encore.dev 1.46.17 → 1.46.19

package/dist/internal/runtime/napi/napi.cjs

@@ -1,5 +1,5 @@
 // The version of the runtime this JS bundle was generated for.
-const version = "v1.46.17";
+const version = "v1.46.19";
 
 // Load the native module.
 const nativeModulePath = process.env.ENCORE_RUNTIME_LIB;
@@ -42,6 +42,7 @@ const {
   SqlConn,
   SqlDatabase,
   Stream,
+  Transaction,
   TypedObjectError,
   WebSocketClient,
 } = nativeModule;
@@ -78,6 +79,7 @@ module.exports = {
   SqlConn,
   SqlDatabase,
   Stream,
+  Transaction,
   TypedObjectError,
   WebSocketClient,
 };

package/dist/internal/runtime/napi/napi.d.cts

@@ -303,6 +303,8 @@ export class SqlDatabase {
   acquire(): Promise<SQLConn>
   /** Reports the connection string to connect to this database. */
   connString(): string
+  /** Begins a transaction */
+  begin(source?: Request | undefined | null): Promise<Transaction>
   query(query: string, args: QueryArgs, source?: Request | undefined | null): Promise<Cursor>
   queryRow(query: string, args: QueryArgs, source?: Request | undefined | null): Promise<Row | null>
 }
@@ -320,6 +322,12 @@ export interface TraceData {
   extCorrelationId?: string
 }
 
+export class Transaction {
+  commit(source?: Request | undefined | null): Promise<void>
+  rollback(source?: Request | undefined | null): Promise<void>
+  query(query: string, args: QueryArgs, source?: Request | undefined | null): Promise<Cursor>
+}
+
 export class TypedObjectError {
   kind: ObjectErrorKind
   message: string

package/dist/storage/sqldb/database.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import * as runtime from "../../internal/runtime/mod.js";
 import { StringLiteral } from "../../internal/utils/constraints.js";
 export interface SQLMigrationsConfig {
@@ -14,28 +15,11 @@ export interface SQLDatabaseConfig {
 export type Row = Record<string, any>;
 /** Represents a type that can be used in query template literals */
 export type Primitive = string | string[] | number | number[] | boolean | boolean[] | Buffer | Date | Date[] | Record<string, any> | Record<string, any>[] | null | undefined;
-/**
- * Constructing a new database object will result in Encore provisioning a database with
- * that name and returning this object to represent it.
- *
- * If you want to reference an existing database, use `Database.Named(name)` as it is a
- * compile error to create duplicate databases.
- */
-export declare class SQLDatabase {
-    private readonly impl;
-    /**
-     * Creates a new database with the given name and configuration
-     */
-    constructor(name: string, cfg?: SQLDatabaseConfig);
-    /**
-     * Reference an existing database by name, if the database doesn't
-     * exist yet, use `new Database(name)` instead.
-     */
-    static named<name extends string>(name: StringLiteral<name>): SQLDatabase;
-    /**
-     * Returns the connection string for the database
-     */
-    get connectionString(): string;
+type SQLQueryExecutor = runtime.SQLConn | runtime.SQLDatabase | runtime.Transaction;
+/** Base class containing shared query functionality */
+declare class BaseQueryExecutor {
+    protected readonly impl: SQLQueryExecutor;
+    constructor(impl: SQLQueryExecutor);
     /**
      * query queries the database using a template string, replacing your placeholders in the template
      * with parametrised values without risking SQL injections.
@@ -142,128 +126,64 @@ export declare class SQLDatabase {
      * @returns A promise that resolves when the query has been executed.
      */
     rawExec(query: string, ...params: Primitive[]): Promise<void>;
-    /**
-     * Acquires a database connection from the database pool.
-     *
-     * When the connection is closed or is garbage-collected, it is returned to the pool.
-     * @returns a new connection to the database
-     */
-    acquire(): Promise<Connection>;
 }
 /**
- * Represents a dedicated connection to a database.
+ * Constructing a new database object will result in Encore provisioning a database with
+ * that name and returning this object to represent it.
+ *
+ * If you want to reference an existing database, use `Database.Named(name)` as it is a
+ * compile error to create duplicate databases.
  */
-export declare class Connection {
-    private readonly impl;
-    constructor(impl: runtime.SQLConn);
-    /**
-     * Returns the connection to the database pool.
-     */
-    close(): Promise<void>;
-    /**
-     * query queries the database using a template string, replacing your placeholders in the template
-     * with parametrised values without risking SQL injections.
-     *
-     * It returns an async generator, that allows iterating over the results
-     * in a streaming fashion using `for await`.
-     *
-     * @example
-     *
-     * const email = "foo@example.com";
-     * const result = database.query`SELECT id FROM users WHERE email=${email}`
-     *
-     * This produces the query: "SELECT id FROM users WHERE email=$1".
-     */
-    query<T extends Row = Record<string, any>>(strings: TemplateStringsArray, ...params: Primitive[]): AsyncGenerator<T>;
+export declare class SQLDatabase extends BaseQueryExecutor {
+    protected readonly impl: runtime.SQLDatabase;
+    constructor(name: string, cfg?: SQLDatabaseConfig);
     /**
-     * rawQuery queries the database using a raw parametrised SQL query and parameters.
-     *
-     * It returns an async generator, that allows iterating over the results
-     * in a streaming fashion using `for await`.
-     *
-     * @example
-     * const query = "SELECT id FROM users WHERE email=$1";
-     * const email = "foo@example.com";
-     * for await (const row of database.rawQuery(query, email)) {
-     *   console.log(row);
-     * }
-     *
-     * @param query - The raw SQL query string.
-     * @param params - The parameters to be used in the query.
-     * @returns An async generator that yields rows from the query result.
+     * Reference an existing database by name, if the database doesn't
+     * exist yet, use `new Database(name)` instead.
      */
-    rawQuery<T extends Row = Record<string, any>>(query: string, ...params: Primitive[]): AsyncGenerator<T>;
+    static named<name extends string>(name: StringLiteral<name>): SQLDatabase;
     /**
-     * queryAll queries the database using a template string, replacing your placeholders in the template
-     * with parametrised values without risking SQL injections.
-     *
-     * It returns an array of all results.
-     *
-     * @example
-     *
-     * const email = "foo@example.com";
-     * const result = database.queryAll`SELECT id FROM users WHERE email=${email}`
-     *
-     * This produces the query: "SELECT id FROM users WHERE email=$1".
+     * Returns the connection string for the database
      */
-    queryAll<T extends Row = Record<string, any>>(strings: TemplateStringsArray, ...params: Primitive[]): Promise<T[]>;
+    get connectionString(): string;
     /**
-     * rawQueryAll queries the database using a raw parametrised SQL query and parameters.
-     *
-     * It returns an array of all results.
-     *
-     * @example
+     * Acquires a database connection from the database pool.
      *
-     * const query = "SELECT id FROM users WHERE email=$1";
-     * const email = "foo@example.com";
-     * const rows = await database.rawQueryAll(query, email);
+     * When the connection is closed or is garbage-collected, it is returned to the pool.
+     * @returns a new connection to the database
      */
-    rawQueryAll<T extends Row = Record<string, any>>(query: string, ...params: Primitive[]): Promise<T[]>;
+    acquire(): Promise<Connection>;
     /**
-     * queryRow is like query but returns only a single row.
-     * If the query selects no rows it returns null.
-     * Otherwise it returns the first row and discards the rest.
+     * Begins a database transaction.
      *
-     * @example
-     * const email = "foo@example.com";
-     * const result = database.queryRow`SELECT id FROM users WHERE email=${email}`
+     * Make sure to always call `rollback` or `commit` to prevent hanging transactions.
+     * @returns a transaction object that implements AsycDisposable
      */
-    queryRow<T extends Row = Record<string, any>>(strings: TemplateStringsArray, ...params: Primitive[]): Promise<T | null>;
+    begin(): Promise<Transaction>;
+}
+export declare class Transaction extends BaseQueryExecutor implements AsyncDisposable {
+    protected readonly impl: runtime.Transaction;
+    private done;
+    constructor(impl: runtime.Transaction);
     /**
-     * rawQueryRow is like rawQuery but returns only a single row.
-     * If the query selects no rows, it returns null.
-     * Otherwise, it returns the first row and discards the rest.
-     *
-     * @example
-     * const query = "SELECT id FROM users WHERE email=$1";
-     * const email = "foo@example.com";
-     * const result = await database.rawQueryRow(query, email);
-     * console.log(result);
-     *
-     * @param query - The raw SQL query string.
-     * @param params - The parameters to be used in the query.
-     * @returns A promise that resolves to a single row or null.
+     * Commit the transaction.
      */
-    rawQueryRow<T extends Row = Record<string, any>>(query: string, ...params: Primitive[]): Promise<T | null>;
+    commit(): Promise<void>;
     /**
-     * exec executes a query without returning any rows.
-     *
-     * @example
-     * const email = "foo@example.com";
-     * const result = database.exec`DELETE FROM users WHERE email=${email}`
+     * Rollback the transaction.
      */
-    exec(strings: TemplateStringsArray, ...params: Primitive[]): Promise<void>;
+    rollback(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Represents a dedicated connection to a database.
+ */
+export declare class Connection extends BaseQueryExecutor {
+    protected readonly impl: runtime.SQLConn;
+    constructor(impl: runtime.SQLConn);
     /**
-     * rawExec executes a query without returning any rows.
-     *
-     * @example
-     * const query = "DELETE FROM users WHERE email=$1";
-     * const email = "foo@example.com";
-     * await database.rawExec(query, email);
-     *
-     * @param query - The raw SQL query string.
-     * @param params - The parameters to be used in the query.
-     * @returns A promise that resolves when the query has been executed.
+     * Returns the connection to the database pool.
      */
-    rawExec(query: string, ...params: Primitive[]): Promise<void>;
+    close(): Promise<void>;
 }
+export {};

package/dist/storage/sqldb/database.js

@@ -1,34 +1,11 @@
 import { getCurrentRequest } from "../../internal/reqtrack/mod.js";
 import * as runtime from "../../internal/runtime/mod.js";
 const driverName = "node-pg";
-/**
- * Constructing a new database object will result in Encore provisioning a database with
- * that name and returning this object to represent it.
- *
- * If you want to reference an existing database, use `Database.Named(name)` as it is a
- * compile error to create duplicate databases.
- */
-export class SQLDatabase {
+/** Base class containing shared query functionality */
+class BaseQueryExecutor {
     impl;
-    /**
-     * Creates a new database with the given name and configuration
-     */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    constructor(name, cfg) {
-        this.impl = runtime.RT.sqlDatabase(name);
-    }
-    /**
-     * Reference an existing database by name, if the database doesn't
-     * exist yet, use `new Database(name)` instead.
-     */
-    static named(name) {
-        return new SQLDatabase(name);
-    }
-    /**
-     * Returns the connection string for the database
-     */
-    get connectionString() {
-        return this.impl.connString();
+    constructor(impl) {
+        this.impl = impl;
     }
     /**
      * query queries the database using a template string, replacing your placeholders in the template
@@ -52,9 +29,8 @@ export class SQLDatabase {
         const cursor = await this.impl.query(query, args, source);
         while (true) {
             const row = await cursor.next();
-            if (row === null) {
+            if (row === null)
                 break;
-            }
             yield row.values();
         }
     }
@@ -81,9 +57,8 @@ export class SQLDatabase {
         const result = await this.impl.query(query, args, source);
         while (true) {
             const row = await result.next();
-            if (row === null) {
+            if (row === null)
                 break;
-            }
             yield row.values();
         }
     }
@@ -109,9 +84,8 @@ export class SQLDatabase {
         const result = [];
         while (true) {
             const row = await cursor.next();
-            if (row === null) {
+            if (row === null)
                 break;
-            }
             result.push(row.values());
         }
         return result;
@@ -135,9 +109,8 @@ export class SQLDatabase {
         const result = [];
         while (true) {
             const row = await cursor.next();
-            if (row === null) {
+            if (row === null)
                 break;
-            }
             result.push(row.values());
         }
         return result;
@@ -157,10 +130,8 @@ export class SQLDatabase {
         const args = buildQueryArgs(params);
         const source = getCurrentRequest();
         const result = await this.impl.query(query, args, source);
-        while (true) {
-            const row = await result.next();
-            return row ? row.values() : null;
-        }
+        const row = await result.next();
+        return row ? row.values() : null;
     }
     /**
      * rawQueryRow is like rawQuery but returns only a single row.
@@ -181,10 +152,8 @@ export class SQLDatabase {
         const args = buildQueryArgs(params);
         const source = getCurrentRequest();
         const result = await this.impl.query(query, args, source);
-        while (true) {
-            const row = await result.next();
-            return row ? row.values() : null;
-        }
+        const row = await result.next();
+        return row ? row.values() : null;
     }
     /**
      * exec executes a query without returning any rows.
@@ -199,7 +168,7 @@ export class SQLDatabase {
         const source = getCurrentRequest();
         // Need to await the cursor to process any errors from things like
         // unique constraint violations.
-        let cur = await this.impl.query(query, args, source);
+        const cur = await this.impl.query(query, args, source);
         await cur.next();
     }
     /**
@@ -219,225 +188,95 @@ export class SQLDatabase {
         const source = getCurrentRequest();
         // Need to await the cursor to process any errors from things like
         // unique constraint violations.
-        let cur = await this.impl.query(query, args, source);
+        const cur = await this.impl.query(query, args, source);
         await cur.next();
     }
-    /**
-     * Acquires a database connection from the database pool.
-     *
-     * When the connection is closed or is garbage-collected, it is returned to the pool.
-     * @returns a new connection to the database
-     */
-    async acquire() {
-        const impl = await this.impl.acquire();
-        return new Connection(impl);
-    }
 }
 /**
- * Represents a dedicated connection to a database.
+ * Constructing a new database object will result in Encore provisioning a database with
+ * that name and returning this object to represent it.
+ *
+ * If you want to reference an existing database, use `Database.Named(name)` as it is a
+ * compile error to create duplicate databases.
  */
-export class Connection {
-    impl;
-    constructor(impl) {
-        this.impl = impl;
+export class SQLDatabase extends BaseQueryExecutor {
+    constructor(name, cfg) {
+        super(runtime.RT.sqlDatabase(name));
     }
     /**
-     * Returns the connection to the database pool.
+     * Reference an existing database by name, if the database doesn't
+     * exist yet, use `new Database(name)` instead.
      */
-    async close() {
-        await this.impl.close();
+    static named(name) {
+        return new SQLDatabase(name);
     }
     /**
-     * query queries the database using a template string, replacing your placeholders in the template
-     * with parametrised values without risking SQL injections.
-     *
-     * It returns an async generator, that allows iterating over the results
-     * in a streaming fashion using `for await`.
-     *
-     * @example
-     *
-     * const email = "foo@example.com";
-     * const result = database.query`SELECT id FROM users WHERE email=${email}`
-     *
-     * This produces the query: "SELECT id FROM users WHERE email=$1".
+     * Returns the connection string for the database
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async *query(strings, ...params) {
-        const query = buildQuery(strings, params);
-        const args = buildQueryArgs(params);
-        const source = getCurrentRequest();
-        const cursor = await this.impl.query(query, args, source);
-        while (true) {
-            const row = await cursor.next();
-            if (row === null) {
-                break;
-            }
-            yield row.values();
-        }
+    get connectionString() {
+        return this.impl.connString();
     }
     /**
-     * rawQuery queries the database using a raw parametrised SQL query and parameters.
-     *
-     * It returns an async generator, that allows iterating over the results
-     * in a streaming fashion using `for await`.
-     *
-     * @example
-     * const query = "SELECT id FROM users WHERE email=$1";
-     * const email = "foo@example.com";
-     * for await (const row of database.rawQuery(query, email)) {
-     *   console.log(row);
-     * }
+     * Acquires a database connection from the database pool.
      *
-     * @param query - The raw SQL query string.
-     * @param params - The parameters to be used in the query.
-     * @returns An async generator that yields rows from the query result.
+     * When the connection is closed or is garbage-collected, it is returned to the pool.
+     * @returns a new connection to the database
      */
-    async *rawQuery(query, ...params) {
-        const args = buildQueryArgs(params);
-        const source = getCurrentRequest();
-        const result = await this.impl.query(query, args, source);
-        while (true) {
-            const row = await result.next();
-            if (row === null) {
-                break;
-            }
-            yield row.values();
-        }
+    async acquire() {
+        const impl = await this.impl.acquire();
+        return new Connection(impl);
     }
     /**
-     * queryAll queries the database using a template string, replacing your placeholders in the template
-     * with parametrised values without risking SQL injections.
-     *
-     * It returns an array of all results.
-     *
-     * @example
-     *
-     * const email = "foo@example.com";
-     * const result = database.queryAll`SELECT id FROM users WHERE email=${email}`
+     * Begins a database transaction.
      *
-     * This produces the query: "SELECT id FROM users WHERE email=$1".
+     * Make sure to always call `rollback` or `commit` to prevent hanging transactions.
+     * @returns a transaction object that implements AsycDisposable
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async queryAll(strings, ...params) {
-        const query = buildQuery(strings, params);
-        const args = buildQueryArgs(params);
+    async begin() {
         const source = getCurrentRequest();
-        const cursor = await this.impl.query(query, args, source);
-        const result = [];
-        while (true) {
-            const row = await cursor.next();
-            if (row === null) {
-                break;
-            }
-            result.push(row.values());
-        }
-        return result;
+        const impl = await this.impl.begin(source);
+        return new Transaction(impl);
     }
-    /**
-     * rawQueryAll queries the database using a raw parametrised SQL query and parameters.
-     *
-     * It returns an array of all results.
-     *
-     * @example
-     *
-     * const query = "SELECT id FROM users WHERE email=$1";
-     * const email = "foo@example.com";
-     * const rows = await database.rawQueryAll(query, email);
-     */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async rawQueryAll(query, ...params) {
-        const args = buildQueryArgs(params);
-        const source = getCurrentRequest();
-        const cursor = await this.impl.query(query, args, source);
-        const result = [];
-        while (true) {
-            const row = await cursor.next();
-            if (row === null) {
-                break;
-            }
-            result.push(row.values());
-        }
-        return result;
+}
+export class Transaction extends BaseQueryExecutor {
+    done = false;
+    constructor(impl) {
+        super(impl);
     }
     /**
-     * queryRow is like query but returns only a single row.
-     * If the query selects no rows it returns null.
-     * Otherwise it returns the first row and discards the rest.
-     *
-     * @example
-     * const email = "foo@example.com";
-     * const result = database.queryRow`SELECT id FROM users WHERE email=${email}`
+     * Commit the transaction.
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async queryRow(strings, ...params) {
-        const query = buildQuery(strings, params);
-        const args = buildQueryArgs(params);
+    async commit() {
+        this.done = true;
         const source = getCurrentRequest();
-        const result = await this.impl.query(query, args, source);
-        while (true) {
-            const row = await result.next();
-            return row ? row.values() : null;
-        }
+        await this.impl.commit(source);
     }
     /**
-     * rawQueryRow is like rawQuery but returns only a single row.
-     * If the query selects no rows, it returns null.
-     * Otherwise, it returns the first row and discards the rest.
-     *
-     * @example
-     * const query = "SELECT id FROM users WHERE email=$1";
-     * const email = "foo@example.com";
-     * const result = await database.rawQueryRow(query, email);
-     * console.log(result);
-     *
-     * @param query - The raw SQL query string.
-     * @param params - The parameters to be used in the query.
-     * @returns A promise that resolves to a single row or null.
+     * Rollback the transaction.
      */
-    async rawQueryRow(query, ...params) {
-        const args = buildQueryArgs(params);
+    async rollback() {
+        this.done = true;
         const source = getCurrentRequest();
-        const result = await this.impl.query(query, args, source);
-        while (true) {
-            const row = await result.next();
-            return row ? row.values() : null;
+        await this.impl.rollback(source);
+    }
+    async [Symbol.asyncDispose]() {
+        if (!this.done) {
+            await this.rollback();
         }
     }
-    /**
-     * exec executes a query without returning any rows.
-     *
-     * @example
-     * const email = "foo@example.com";
-     * const result = database.exec`DELETE FROM users WHERE email=${email}`
-     */
-    async exec(strings, ...params) {
-        const query = buildQuery(strings, params);
-        const args = buildQueryArgs(params);
-        const source = getCurrentRequest();
-        // Need to await the cursor to process any errors from things like
-        // unique constraint violations.
-        let cur = await this.impl.query(query, args, source);
-        await cur.next();
+}
+/**
+ * Represents a dedicated connection to a database.
+ */
+export class Connection extends BaseQueryExecutor {
+    constructor(impl) {
+        super(impl);
     }
     /**
-     * rawExec executes a query without returning any rows.
-     *
-     * @example
-     * const query = "DELETE FROM users WHERE email=$1";
-     * const email = "foo@example.com";
-     * await database.rawExec(query, email);
-     *
-     * @param query - The raw SQL query string.
-     * @param params - The parameters to be used in the query.
-     * @returns A promise that resolves when the query has been executed.
+     * Returns the connection to the database pool.
      */
-    async rawExec(query, ...params) {
-        const args = buildQueryArgs(params);
-        const source = getCurrentRequest();
-        // Need to await the cursor to process any errors from things like
-        // unique constraint violations.
-        let cur = await this.impl.query(query, args, source);
-        await cur.next();
+    async close() {
+        await this.impl.close();
     }
 }
 function buildQuery(strings, expr) {