@prairielearn/postgres 2.1.15 → 4.0.0

package/src/pool.ts

@@ -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';
@@ -220,11 +219,6 @@ export class PostgresPool {
     }
   }
 
-  /**
-   * Creates a new connection pool and attempts to connect to the database.
-   */
-  init = callbackify(this.initAsync);
-
   /**
    * Closes the connection pool.
    */
@@ -235,14 +229,7 @@ export class PostgresPool {
   }
 
   /**
-   * 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
@@ -290,15 +277,6 @@ export class PostgresPool {
     return client;
   }
 
-  /**
-   * Gets a new client from the connection pool.
-   */
-  getClient(callback: (error: Error | null, client?: pg.PoolClient, done?: () => void) => void) {
-    this.getClientAsync()
-      .then((client) => callback(null, client, client.release))
-      .catch((err) => callback(err));
-  }
-
   /**
    * Performs a query with the given client.
    */
@@ -321,11 +299,6 @@ export class PostgresPool {
     }
   }
 
-  /**
-   * 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.
@@ -349,12 +322,6 @@ export class PostgresPool {
     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.
@@ -378,12 +345,6 @@ export class PostgresPool {
     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.
    */
@@ -406,21 +367,6 @@ export class PostgresPool {
     }
   }
 
-  /**
-   * Rolls back the current transaction for the given client.
-   */
-  rollbackWithClient(
-    client: pg.PoolClient,
-    _done: (release?: any) => void,
-    callback: (err: Error | null) => void,
-  ) {
-    // 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.
    */
@@ -465,21 +411,6 @@ export class PostgresPool {
     }
   }
 
-  /**
-   * Commits the transaction if err is null, otherwise rollbacks the transaction.
-   * Also releases the client.
-   */
-  endTransaction(
-    client: pg.PoolClient,
-    _done: (rollback?: any) => void,
-    err: Error | null | undefined,
-    callback: (error: Error | null) => void,
-  ): void {
-    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
@@ -537,11 +468,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.
@@ -560,12 +486,6 @@ export class PostgresPool {
     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.
@@ -585,13 +505,7 @@ export class PostgresPool {
   }
 
   /**
-   * 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: string, params: any[]): Promise<pg.QueryResult> {
     debug('call()', 'function:', functionName);
@@ -604,13 +518,8 @@ export class PostgresPool {
   }
 
   /**
-   * 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: string, params: any[]): Promise<pg.QueryResult> {
     debug('callOneRow()', 'function:', functionName);
@@ -627,14 +536,8 @@ export class PostgresPool {
   }
 
   /**
-   * 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: string, params: any[]): Promise<pg.QueryResult> {
     debug('callZeroOrOneRow()', 'function:', functionName);
@@ -651,13 +554,7 @@ export class PostgresPool {
   }
 
   /**
-   * 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: pg.PoolClient,
@@ -674,13 +571,8 @@ export class PostgresPool {
   }
 
   /**
-   * 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: pg.PoolClient,
@@ -702,13 +594,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: pg.PoolClient,
@@ -728,163 +614,18 @@ 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<Model extends z.ZodTypeAny>(
-    query: string,
-    params: QueryParams,
-    model: Model,
-  ): Promise<z.infer<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<Model extends z.ZodTypeAny>(
-    query: string,
-    params: QueryParams,
-    model: Model,
-  ): Promise<z.infer<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<Model extends z.ZodTypeAny>(
-    query: string,
-    params: QueryParams,
-    model: Model,
-  ): Promise<z.infer<Model> | null> {
-    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<Model extends z.ZodTypeAny>(
-    query: string,
-    params: QueryParams,
-    model: Model,
-  ): Promise<z.infer<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<Model extends z.ZodTypeAny>(
-    query: string,
-    params: QueryParams,
-    model: Model,
-  ): Promise<z.infer<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<Model extends z.ZodTypeAny>(
-    query: string,
-    params: QueryParams,
-    model: Model,
-  ): Promise<z.infer<Model> | null> {
-    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<Model extends z.ZodTypeAny>(
-    sprocName: string,
-    params: any[],
-    model: Model,
-  ): Promise<z.infer<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<Model extends z.ZodTypeAny>(
-    sprocName: string,
-    params: any[],
-    model: Model,
-  ): Promise<z.infer<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.
-   */
-  async callValidatedZeroOrOneRow<Model extends z.ZodTypeAny>(
-    sprocName: string,
-    params: any[],
-    model: Model,
-  ): Promise<z.infer<Model> | null> {
-    const results = await this.callZeroOrOneRowAsync(sprocName, params);
-    if (results.rows.length === 0) {
-      return null;
-    } else {
-      return model.parse(results.rows[0]);
-    }
-  }
-
   async queryRows<Model extends z.ZodTypeAny>(sql: string, model: Model): Promise<z.infer<Model>[]>;
   async queryRows<Model extends z.ZodTypeAny>(
     sql: string,
     params: QueryParams,
     model: Model,
   ): Promise<z.infer<Model>[]>;
+  /**
+   * 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 queryRows<Model extends z.ZodTypeAny>(
     sql: string,
     paramsOrSchema: QueryParams | Model,
@@ -908,6 +649,11 @@ export class PostgresPool {
     params: QueryParams,
     model: Model,
   ): Promise<z.infer<Model>>;
+  /**
+   * 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<Model extends z.ZodTypeAny>(
     sql: string,
     paramsOrSchema: QueryParams | Model,
@@ -933,6 +679,12 @@ export class PostgresPool {
     params: QueryParams,
     model: Model,
   ): Promise<z.infer<Model> | null>;
+  /**
+   * 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<Model extends z.ZodTypeAny>(
     sql: string,
     paramsOrSchema: QueryParams | Model,
@@ -957,6 +709,10 @@ export class PostgresPool {
     params: any[],
     model: Model,
   ): Promise<z.infer<Model>[]>;
+  /**
+   * Calls the given sproc with the specified parameters.
+   * Errors if the sproc does not return anything.
+   */
   async callRows<Model extends z.ZodTypeAny>(
     sql: string,
     paramsOrSchema: any[] | Model,
@@ -980,6 +736,10 @@ export class PostgresPool {
     params: any[],
     model: Model,
   ): Promise<z.infer<Model>>;
+  /**
+   * Calls the given sproc with the specified parameters.
+   * Returns exactly one row from the sproc that conforms to the given Zod schema.
+   */
   async callRow<Model extends z.ZodTypeAny>(
     sql: string,
     paramsOrSchema: any[] | Model,
@@ -1005,6 +765,10 @@ export class PostgresPool {
     params: any[],
     model: Model,
   ): Promise<z.infer<Model> | null>;
+  /**
+   * Calls the given sproc with the specified parameters. Returns either null
+   * or a single row that conforms to the given Zod schema.
+   */
   async callOptionalRow<Model extends z.ZodTypeAny>(
     sql: string,
     paramsOrSchema: any[] | Model,
@@ -1027,7 +791,7 @@ export class PostgresPool {
    * Returns a {@link Cursor} for the given query. The cursor can be used to
    * read results in batches, which is useful for large result sets.
    */
-  async queryCursorWithClient(
+  private async queryCursorWithClient(
     client: pg.PoolClient,
     sql: string,
     params: QueryParams,
@@ -1040,31 +804,20 @@ export class PostgresPool {
     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<Model extends z.ZodTypeAny>(
-    sql: string,
-    params: QueryParams,
-  ): Promise<CursorIterator<z.infer<Model>>> {
-    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<Model extends z.ZodTypeAny>(
+  async queryCursor<Model extends z.ZodTypeAny>(
     sql: string,
     params: QueryParams,
     model: Model,
   ): Promise<CursorIterator<z.infer<Model>>> {
-    return this.queryValidatedCursorInternal(sql, params, model);
+    return this.queryCursorInternal(sql, params, model);
   }
 
-  private async queryValidatedCursorInternal<Model extends z.ZodTypeAny>(
+  private async queryCursorInternal<Model extends z.ZodTypeAny>(
     sql: string,
     params: QueryParams,
     model?: Model,
@@ -1187,11 +940,6 @@ export class PostgresPool {
     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;