@prairielearn/postgres 2.1.15 → 4.0.0

package/dist/pool.js

@@ -1,6 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Readable, Transform } from 'node:stream';
-import { callbackify } from 'node:util';
 import debugfn from 'debug';
 import _ from 'lodash';
 import multipipe from 'multipipe';
@@ -188,10 +187,6 @@ export class PostgresPool {
             }
         }
     }
-    /**
-     * Creates a new connection pool and attempts to connect to the database.
-     */
-    init = callbackify(this.initAsync);
     /**
      * Closes the connection pool.
      */
@@ -202,13 +197,7 @@ export class PostgresPool {
         this.pool = null;
     }
     /**
-     * Closes the connection pool.
-     */
-    close = callbackify(this.closeAsync);
-    /**
-     * Gets a new client from the connection pool. If `err` is not null
-     * then `client` and `done` are undefined. If `err` is null then
-     * `client` is valid and can be used. The caller MUST call `done()` to
+     * Gets a new client from the connection pool. The caller MUST call `release()` to
      * release the client, whether or not errors occurred while using
      * `client`. The client can call `done(truthy_value)` to force
      * destruction of the client, but this should not be used except in
@@ -253,14 +242,6 @@ export class PostgresPool {
         }
         return client;
     }
-    /**
-     * Gets a new client from the connection pool.
-     */
-    getClient(callback) {
-        this.getClientAsync()
-            .then((client) => callback(null, client, client.release))
-            .catch((err) => callback(err));
-    }
     /**
      * Performs a query with the given client.
      */
@@ -279,10 +260,6 @@ export class PostgresPool {
             throw enhanceError(err, sql, params);
         }
     }
-    /**
-     * Performs a query with the given client.
-     */
-    queryWithClient = callbackify(this.queryWithClientAsync);
     /**
      * Performs a query with the given client. Errors if the query returns more
      * than one row.
@@ -301,11 +278,6 @@ export class PostgresPool {
         debug('queryWithClientOneRow() success', 'rowCount:', result.rowCount);
         return result;
     }
-    /**
-     * Performs a query with the given client. Errors if the query returns more
-     * than one row.
-     */
-    queryWithClientOneRow = callbackify(this.queryWithClientOneRowAsync);
     /**
      * Performs a query with the given client. Errors if the query returns more
      * than one row.
@@ -324,11 +296,6 @@ export class PostgresPool {
         debug('queryWithClientZeroOrOneRow() success', 'rowCount:', result.rowCount);
         return result;
     }
-    /**
-     * Performs a query with the given client. Errors if the query returns more
-     * than one row.
-     */
-    queryWithClientZeroOrOneRow = callbackify(this.queryWithClientZeroOrOneRowAsync);
     /**
      * Rolls back the current transaction for the given client.
      */
@@ -351,16 +318,6 @@ export class PostgresPool {
             client.release(err);
         }
     }
-    /**
-     * Rolls back the current transaction for the given client.
-     */
-    rollbackWithClient(client, _done, callback) {
-        // Note that we can't use `util.callbackify` here because this function
-        // has an additional unused `done` parameter for backwards compatibility.
-        this.rollbackWithClientAsync(client)
-            .then(() => callback(null))
-            .catch((err) => callback(err));
-    }
     /**
      * Begins a new transaction.
      */
@@ -406,15 +363,6 @@ export class PostgresPool {
             }
         }
     }
-    /**
-     * Commits the transaction if err is null, otherwise rollbacks the transaction.
-     * Also releases the client.
-     */
-    endTransaction(client, _done, err, callback) {
-        this.endTransactionAsync(client, err)
-            .then(() => callback(null))
-            .catch((error) => callback(error));
-    }
     /**
      * Runs the specified function inside of a transaction. The function will
      * receive a database client as an argument, but it can also make queries
@@ -469,10 +417,6 @@ export class PostgresPool {
             }
         }
     }
-    /**
-     * Executes a query with the specified parameters.
-     */
-    query = callbackify(this.queryAsync);
     /**
      * Executes a query with the specified parameters. Errors if the query does
      * not return exactly one row.
@@ -490,11 +434,6 @@ export class PostgresPool {
         debug('queryOneRow() success', 'rowCount:', result.rowCount);
         return result;
     }
-    /**
-     * Executes a query with the specified parameters. Errors if the query does
-     * not return exactly one row.
-     */
-    queryOneRow = callbackify(this.queryOneRowAsync);
     /**
      * Executes a query with the specified parameters. Errors if the query
      * returns more than one row.
@@ -513,12 +452,7 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Executes a query with the specified parameters. Errors if the query
-     * returns more than one row.
-     */
-    queryZeroOrOneRow = callbackify(this.queryZeroOrOneRowAsync);
-    /**
-     * Calls the given function with the specified parameters.
+     * Calls the given sproc with the specified parameters.
      */
     async callAsync(functionName, params) {
         debug('call()', 'function:', functionName);
@@ -530,12 +464,8 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls the given function with the specified parameters.
-     */
-    call = callbackify(this.callAsync);
-    /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function does not return exactly one row.
+     * Calls the given sproc with the specified parameters. Errors if the
+     * sproc does not return exactly one row.
      */
     async callOneRowAsync(functionName, params) {
         debug('callOneRow()', 'function:', functionName);
@@ -551,13 +481,8 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function does not return exactly one row.
-     */
-    callOneRow = callbackify(this.callOneRowAsync);
-    /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function returns more than one row.
+     * Calls the given sproc with the specified parameters. Errors if the
+     * sproc returns more than one row.
      */
     async callZeroOrOneRowAsync(functionName, params) {
         debug('callZeroOrOneRow()', 'function:', functionName);
@@ -573,12 +498,7 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls the given function with the specified parameters. Errors if the
-     * function returns more than one row.
-     */
-    callZeroOrOneRow = callbackify(this.callZeroOrOneRowAsync);
-    /**
-     * Calls a function with the specified parameters using a specific client.
+     * Calls a sproc with the specified parameters using a specific client.
      */
     async callWithClientAsync(client, functionName, params) {
         debug('callWithClient()', 'function:', functionName);
@@ -590,12 +510,8 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls a function with the specified parameters using a specific client.
-     */
-    callWithClient = callbackify(this.callWithClientAsync);
-    /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function does not return exactly one row.
+     * Calls a sproc with the specified parameters using a specific client.
+     * Errors if the sproc does not return exactly one row.
      */
     async callWithClientOneRowAsync(client, functionName, params) {
         debug('callWithClientOneRow()', 'function:', functionName);
@@ -612,12 +528,7 @@ export class PostgresPool {
     }
     /**
      * Calls a function with the specified parameters using a specific client.
-     * Errors if the function does not return exactly one row.
-     */
-    callWithClientOneRow = callbackify(this.callWithClientOneRowAsync);
-    /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function returns more than one row.
+     * Errors if the sproc returns more than one row.
      */
     async callWithClientZeroOrOneRowAsync(client, functionName, params) {
         debug('callWithClientZeroOrOneRow()', 'function:', functionName);
@@ -633,113 +544,11 @@ export class PostgresPool {
         return result;
     }
     /**
-     * Calls a function with the specified parameters using a specific client.
-     * Errors if the function returns more than one row.
-     */
-    callWithClientZeroOrOneRow = callbackify(this.callWithClientZeroOrOneRowAsync);
-    /**
-     * Wrapper around {@link queryAsync} that parses the resulting rows with the
-     * given Zod schema. Returns only the rows of the query.
-     */
-    async queryValidatedRows(query, params, model) {
-        const results = await this.queryAsync(query, params);
-        return z.array(model).parse(results.rows);
-    }
-    /**
-     * Wrapper around {@link queryOneRowAsync} that parses the resulting row with
-     * the given Zod schema. Returns only a single row of the query.
-     */
-    async queryValidatedOneRow(query, params, model) {
-        const results = await this.queryOneRowAsync(query, params);
-        return model.parse(results.rows[0]);
-    }
-    /**
-     * Wrapper around {@link queryZeroOrOneRowAsync} that parses the resulting row
-     * (if any) with the given Zod schema. Returns either a single row or `null`.
-     */
-    async queryValidatedZeroOrOneRow(query, params, model) {
-        const results = await this.queryZeroOrOneRowAsync(query, params);
-        if (results.rows.length === 0) {
-            return null;
-        }
-        else {
-            return model.parse(results.rows[0]);
-        }
-    }
-    /**
-     * Wrapper around {@link queryAsync} that validates that only one column is
-     * returned and parses the data in it with the given Zod schema. Returns only
-     * the single column of the query as an array.
-     */
-    async queryValidatedSingleColumnRows(query, params, model) {
-        const results = await this.queryAsync(query, params);
-        if (results.fields.length !== 1) {
-            throw new Error(`Expected one column, got ${results.fields.length}`);
-        }
-        const columnName = results.fields[0].name;
-        const rawData = results.rows.map((row) => row[columnName]);
-        return z.array(model).parse(rawData);
-    }
-    /**
-     * Wrapper around {@link queryOneRowAsync} that validates that only one column
-     * is returned and parses the data in it with the given Zod schema. Returns
-     * only the single entry.
-     */
-    async queryValidatedSingleColumnOneRow(query, params, model) {
-        const results = await this.queryOneRowAsync(query, params);
-        if (results.fields.length !== 1) {
-            throw new Error(`Expected one column, got ${results.fields.length}`);
-        }
-        const columnName = results.fields[0].name;
-        return model.parse(results.rows[0][columnName]);
-    }
-    /**
-     * Wrapper around {@link queryZeroOrOneRowAsync} that validates that only one
-     * column is returned and parses the data in it (if any) with the given Zod
-     * schema. Returns either the single row of the query or `null`.
-     */
-    async queryValidatedSingleColumnZeroOrOneRow(query, params, model) {
-        const results = await this.queryZeroOrOneRowAsync(query, params);
-        if (results.fields.length !== 1) {
-            throw new Error(`Expected one column, got ${results.fields.length}`);
-        }
-        if (results.rows.length === 0) {
-            return null;
-        }
-        else {
-            const columnName = results.fields[0].name;
-            return model.parse(results.rows[0][columnName]);
-        }
-    }
-    /**
-     * Wrapper around {@link callAsync} that parses the resulting rows with the
-     * given Zod schema. Returns only the rows.
-     */
-    async callValidatedRows(sprocName, params, model) {
-        const results = await this.callAsync(sprocName, params);
-        return z.array(model).parse(results.rows);
-    }
-    /**
-     * Wrapper around {@link callOneRowAsync} that parses the resulting rows with
-     * the given Zod schema. Returns only a single row.
-     */
-    async callValidatedOneRow(sprocName, params, model) {
-        const results = await this.callOneRowAsync(sprocName, params);
-        return model.parse(results.rows[0]);
-    }
-    /**
-     * Wrapper around {@link callZeroOrOneRowAsync} that parses the resulting row
-     * (if any) with the given Zod schema. Returns at most a single row.
+     * Executes a query with the specified parameters. Returns an array of rows
+     * that conform to the given Zod schema.
+     *
+     * If the query returns a single column, the return value will be a list of column values.
      */
-    async callValidatedZeroOrOneRow(sprocName, params, model) {
-        const results = await this.callZeroOrOneRowAsync(sprocName, params);
-        if (results.rows.length === 0) {
-            return null;
-        }
-        else {
-            return model.parse(results.rows[0]);
-        }
-    }
     async queryRows(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? {} : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -753,6 +562,11 @@ export class PostgresPool {
             return z.array(model).parse(results.rows);
         }
     }
+    /**
+     * Executes a query with the specified parameters. Returns exactly one row that conforms to the given Zod schema.
+     *
+     * If the query returns a single column, the return value will be the column value itself.
+     */
     async queryRow(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? {} : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -765,6 +579,12 @@ export class PostgresPool {
             return model.parse(results.rows[0]);
         }
     }
+    /**
+     * Executes a query with the specified parameters. Returns either null or a
+     * single row that conforms to the given Zod schema, and errors otherwise.
+     *
+     * If the query returns a single column, the return value will be the column value itself.
+     */
     async queryOptionalRow(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? {} : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -780,6 +600,10 @@ export class PostgresPool {
             return model.parse(results.rows[0]);
         }
     }
+    /**
+     * Calls the given sproc with the specified parameters.
+     * Errors if the sproc does not return anything.
+     */
     async callRows(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? [] : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -793,6 +617,10 @@ export class PostgresPool {
             return z.array(model).parse(results.rows);
         }
     }
+    /**
+     * Calls the given sproc with the specified parameters.
+     * Returns exactly one row from the sproc that conforms to the given Zod schema.
+     */
     async callRow(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? [] : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -805,6 +633,10 @@ export class PostgresPool {
             return model.parse(results.rows[0]);
         }
     }
+    /**
+     * Calls the given sproc with the specified parameters. Returns either null
+     * or a single row that conforms to the given Zod schema.
+     */
     async callOptionalRow(sql, paramsOrSchema, maybeModel) {
         const params = maybeModel === undefined ? [] : paramsOrSchema;
         const model = maybeModel === undefined ? paramsOrSchema : maybeModel;
@@ -832,22 +664,15 @@ export class PostgresPool {
         lastQueryMap.set(client, processedSql);
         return client.query(new Cursor(processedSql, paramsArray));
     }
-    /**
-     * Returns an {@link CursorIterator} that can be used to iterate over the
-     * results of the query in batches, which is useful for large result sets.
-     */
-    async queryCursor(sql, params) {
-        return this.queryValidatedCursorInternal(sql, params);
-    }
     /**
      * Returns an {@link CursorIterator} that can be used to iterate over the
      * results of the query in batches, which is useful for large result sets.
      * Each row will be parsed by the given Zod schema.
      */
-    async queryValidatedCursor(sql, params, model) {
-        return this.queryValidatedCursorInternal(sql, params, model);
+    async queryCursor(sql, params, model) {
+        return this.queryCursorInternal(sql, params, model);
     }
-    async queryValidatedCursorInternal(sql, params, model) {
+    async queryCursorInternal(sql, params, model) {
         const client = await this.getClientAsync();
         const cursor = await this.queryCursorWithClient(client, sql, params);
         let iterateCalled = false;
@@ -958,10 +783,6 @@ export class PostgresPool {
         await this.setSearchSchema(schema);
         return schema;
     }
-    /**
-     * Generate, set, and return a random schema name.
-     */
-    setRandomSearchSchema = callbackify(this.setRandomSearchSchemaAsync);
     /** The number of established connections. */
     get totalCount() {
         return this.pool?.totalCount ?? 0;