@prairielearn/postgres 3.0.0 → 4.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prairielearn/postgres",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -22,15 +22,15 @@
     "pg-cursor": "^2.15.3",
     "pg-pool": "^3.10.1",
     "pg-protocol": "^1.10.3",
-    "zod": "^3.25.69"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@prairielearn/tsconfig": "^0.0.0",
     "@types/multipipe": "^3.0.5",
-    "@types/node": "^22.15.34",
+    "@types/node": "^22.17.0",
     "@vitest/coverage-v8": "^3.2.4",
     "tsx": "^4.20.3",
-    "typescript": "^5.8.3",
+    "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   }
 }

package/src/default-pool.test.ts

@@ -14,7 +14,8 @@ const HIDDEN_PROPERTIES = new Set([
   'alsClient',
   'searchSchema',
   '_queryCount',
-  'queryValidatedCursorInternal',
+  'queryCursorWithClient',
+  'queryCursorInternal',
   'errorOnUnusedParameters',
   // Getters
   'totalCount',

package/src/default-pool.ts

@@ -11,55 +11,177 @@ export { defaultPool, type CursorIterator, type QueryParams };
 // that they'll be invoked with the correct `this` context, specifically when
 // this module is imported as `import * as db from '...'` and that import is
 // subsequently transformed by Babel to `interopRequireWildcard(...)`.
-export const init = defaultPool.init.bind(defaultPool);
+
+// VSCode currently doesn't allow for us to use `inheritDoc` to inherit the
+// documentation from the `PostgresPool` class. We mirror the documentation
+// here for *async methods* in VSCode intellisense.
+
+/**
+ * Creates a new connection pool and attempts to connect to the database.
+ */
 export const initAsync = defaultPool.initAsync.bind(defaultPool);
-export const close = defaultPool.close.bind(defaultPool);
+/**
+ * Closes the connection pool.
+ */
 export const closeAsync = defaultPool.closeAsync.bind(defaultPool);
+/**
+ * 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
+ * unusual circumstances.
+ */
 export const getClientAsync = defaultPool.getClientAsync.bind(defaultPool);
-export const getClient = defaultPool.getClient.bind(defaultPool);
-export const queryWithClient = defaultPool.queryWithClient.bind(defaultPool);
+
+/**
+ * Performs a query with the given client.
+ */
 export const queryWithClientAsync = defaultPool.queryWithClientAsync.bind(defaultPool);
-export const queryWithClientOneRow = defaultPool.queryWithClientOneRow.bind(defaultPool);
+
+/**
+ * Performs a query with the given client. Errors if the query returns more
+ * than one row.
+ */
 export const queryWithClientOneRowAsync = defaultPool.queryWithClientOneRowAsync.bind(defaultPool);
-export const queryWithClientZeroOrOneRow =
-  defaultPool.queryWithClientZeroOrOneRow.bind(defaultPool);
+
+/**
+ * Performs a query with the given client. Errors if the query returns more
+ * than one row.
+ */
 export const queryWithClientZeroOrOneRowAsync =
   defaultPool.queryWithClientZeroOrOneRowAsync.bind(defaultPool);
+/**
+ * Rolls back the current transaction for the given client.
+ */
 export const rollbackWithClientAsync = defaultPool.rollbackWithClientAsync.bind(defaultPool);
-export const rollbackWithClient = defaultPool.rollbackWithClient.bind(defaultPool);
 export const beginTransactionAsync = defaultPool.beginTransactionAsync.bind(defaultPool);
+/**
+ * Commits the transaction if err is null, otherwise rollbacks the transaction.
+ * Also releases the client.
+ */
 export const endTransactionAsync = defaultPool.endTransactionAsync.bind(defaultPool);
-export const endTransaction = defaultPool.endTransaction.bind(defaultPool);
+/**
+ * Runs the specified function inside of a transaction. The function will
+ * receive a database client as an argument, but it can also make queries
+ * as usual, and the correct client will be used automatically.
+ *
+ * The transaction will be rolled back if the function throws an error, and
+ * will be committed otherwise.
+ */
 export const runInTransactionAsync = defaultPool.runInTransactionAsync.bind(defaultPool);
-export const query = defaultPool.query.bind(defaultPool);
+/**
+ * Executes a query with the specified parameters.
+ *
+ * Using the return value of this function directly is not recommended. Instead, use
+ * {@link queryRows}, {@link queryRow}, or {@link queryOptionalRow}.
+ */
 export const queryAsync = defaultPool.queryAsync.bind(defaultPool);
-export const queryOneRow = defaultPool.queryOneRow.bind(defaultPool);
+/**
+ * Executes a query with the specified parameters. Errors if the query does
+ * not return exactly one row.
+ *
+ * @deprecated Use {@link queryRow} instead.
+ */
 export const queryOneRowAsync = defaultPool.queryOneRowAsync.bind(defaultPool);
-export const queryZeroOrOneRow = defaultPool.queryZeroOrOneRow.bind(defaultPool);
+/**
+ * Executes a query with the specified parameters. Errors if the query
+ * returns more than one row.
+ *
+ * @deprecated Use {@link queryOptionalRow} instead.
+ */
 export const queryZeroOrOneRowAsync = defaultPool.queryZeroOrOneRowAsync.bind(defaultPool);
-export const call = defaultPool.call.bind(defaultPool);
+/**
+ * Calls the given sproc with the specified parameters.
+ *
+ * @deprecated Use {@link callRows} instead.
+ */
 export const callAsync = defaultPool.callAsync.bind(defaultPool);
-export const callOneRow = defaultPool.callOneRow.bind(defaultPool);
+/**
+ * Calls the given sproc with the specified parameters. Errors if the
+ * sproc does not return exactly one row.
+ *
+ * @deprecated Use {@link callRow} instead.
+ */
 export const callOneRowAsync = defaultPool.callOneRowAsync.bind(defaultPool);
-export const callZeroOrOneRow = defaultPool.callZeroOrOneRow.bind(defaultPool);
+/**
+ * Calls the given sproc with the specified parameters. Errors if the
+ * sproc returns more than one row.
+ *
+ * @deprecated Use {@link callOptionalRow} instead.
+ */
 export const callZeroOrOneRowAsync = defaultPool.callZeroOrOneRowAsync.bind(defaultPool);
-export const callWithClient = defaultPool.callWithClient.bind(defaultPool);
+/**
+ * Calls a sproc with the specified parameters using a specific client.
+ */
 export const callWithClientAsync = defaultPool.callWithClientAsync.bind(defaultPool);
-export const callWithClientOneRow = defaultPool.callWithClientOneRow.bind(defaultPool);
+/**
+ * Calls a sproc with the specified parameters using a specific client.
+ * Errors if the sproc does not return exactly one row.
+ */
 export const callWithClientOneRowAsync = defaultPool.callWithClientOneRowAsync.bind(defaultPool);
-export const callWithClientZeroOrOneRow = defaultPool.callWithClientZeroOrOneRow.bind(defaultPool);
+/**
+ * Calls a sproc with the specified parameters using a specific client.
+ * Errors if the sproc returns more than one row.
+ */
 export const callWithClientZeroOrOneRowAsync =
   defaultPool.callWithClientZeroOrOneRowAsync.bind(defaultPool);
+/**
+ * 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.
+ */
 export const queryRows = defaultPool.queryRows.bind(defaultPool);
+/**
+ * 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.
+ */
 export const queryRow = defaultPool.queryRow.bind(defaultPool);
+/**
+ * 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.
+ */
 export const queryOptionalRow = defaultPool.queryOptionalRow.bind(defaultPool);
+/**
+ * Calls the given sproc with the specified parameters.
+ * Errors if the sproc does not return anything.
+ */
 export const callRows = defaultPool.callRows.bind(defaultPool);
+/**
+ * Calls the given sproc with the specified parameters.
+ * Returns exactly one row from the sproc that conforms to the given Zod schema.
+ */
 export const callRow = defaultPool.callRow.bind(defaultPool);
+/**
+ * Calls the given sproc with the specified parameters. Returns either null
+ * or a single row that conforms to the given Zod schema.
+ */
 export const callOptionalRow = defaultPool.callOptionalRow.bind(defaultPool);
-export const queryCursorWithClient = defaultPool.queryCursorWithClient.bind(defaultPool);
+/**
+ * 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.
+ */
 export const queryCursor = defaultPool.queryCursor.bind(defaultPool);
-export const queryValidatedCursor = defaultPool.queryValidatedCursor.bind(defaultPool);
+/**
+ * Set the schema to use for the search path.
+ *
+ * @param schema The schema name to use (can be "null" to unset the search path)
+ */
 export const setSearchSchema = defaultPool.setSearchSchema.bind(defaultPool);
+/**
+ * Get the schema that is currently used for the search path.
+ *
+ * @returns schema in use (may be `null` to indicate no schema)
+ */
 export const getSearchSchema = defaultPool.getSearchSchema.bind(defaultPool);
-export const setRandomSearchSchema = defaultPool.setRandomSearchSchema.bind(defaultPool);
+/**
+ * Generate, set, and return a random schema name.
+ *
+ * @param prefix The prefix of the new schema, only the first 28 characters will be used (after lowercasing).
+ * @returns The randomly-generated search schema.
+ */
 export const setRandomSearchSchemaAsync = defaultPool.setRandomSearchSchemaAsync.bind(defaultPool);

package/src/pool.test.ts

@@ -13,7 +13,6 @@ import {
   queryOptionalRow,
   queryRow,
   queryRows,
-  queryValidatedCursor,
 } from './default-pool.js';
 import { makePostgresTestUtils } from './test-utils.js';
 
@@ -256,7 +255,11 @@ describe('@prairielearn/postgres', function () {
 
   describe('queryCursor', () => {
     it('returns zero rows', async () => {
-      const cursor = await queryCursor('SELECT * FROM workspaces WHERE id = 10000;', {});
+      const cursor = await queryCursor(
+        'SELECT * FROM workspaces WHERE id = 10000;',
+        {},
+        z.unknown(),
+      );
       const rowBatches = [];
       for await (const rows of cursor.iterate(10)) {
         rowBatches.push(rows);
@@ -265,7 +268,7 @@ describe('@prairielearn/postgres', function () {
     });
 
     it('returns one row at a time', async () => {
-      const cursor = await queryCursor('SELECT * FROM workspaces WHERE id <= 2;', {});
+      const cursor = await queryCursor('SELECT * FROM workspaces WHERE id <= 2;', {}, z.unknown());
       const rowBatches = [];
       for await (const rows of cursor.iterate(1)) {
         rowBatches.push(rows);
@@ -276,7 +279,7 @@ describe('@prairielearn/postgres', function () {
     });
 
     it('returns all rows at once', async () => {
-      const cursor = queryCursor('SELECT * FROM workspaces WHERE id <= 10;', {});
+      const cursor = queryCursor('SELECT * FROM workspaces WHERE id <= 10;', {}, z.unknown());
       const rowBatches = [];
       for await (const rows of (await cursor).iterate(10)) {
         rowBatches.push(rows);
@@ -286,7 +289,7 @@ describe('@prairielearn/postgres', function () {
     });
 
     it('handles errors', async () => {
-      const cursor = await queryCursor('NOT VALID SQL', {});
+      const cursor = await queryCursor('NOT VALID SQL', {}, z.unknown());
 
       async function readAllRows() {
         const allRows = [];
@@ -307,7 +310,7 @@ describe('@prairielearn/postgres', function () {
     });
   });
 
-  describe('queryValidatedCursor', () => {
+  describe('queryCursor', () => {
     const WorkspaceSchema = z.object({
       id: z.string(),
     });
@@ -318,7 +321,7 @@ describe('@prairielearn/postgres', function () {
 
     describe('iterator', () => {
       it('validates with provided schema', async () => {
-        const cursor = await queryValidatedCursor(
+        const cursor = await queryCursor(
           'SELECT * FROM workspaces WHERE id <= 10 ORDER BY id ASC;',
           {},
           WorkspaceSchema,
@@ -334,7 +337,7 @@ describe('@prairielearn/postgres', function () {
       });
 
       it('throws error when validation fails', async () => {
-        const cursor = await queryValidatedCursor(
+        const cursor = await queryCursor(
           'SELECT * FROM workspaces WHERE id <= 10 ORDER BY id ASC;',
           {},
           BadWorkspaceSchema,
@@ -356,7 +359,7 @@ describe('@prairielearn/postgres', function () {
 
     describe('stream', () => {
       it('validates with provided schema', async () => {
-        const cursor = await queryValidatedCursor(
+        const cursor = await queryCursor(
           'SELECT * FROM workspaces WHERE id <= 10 ORDER BY id ASC;',
           {},
           WorkspaceSchema,
@@ -371,7 +374,7 @@ describe('@prairielearn/postgres', function () {
       });
 
       it('emits an error when validation fails', async () => {
-        const cursor = await queryValidatedCursor(
+        const cursor = await queryCursor(
           'SELECT * FROM workspaces ORDER BY id ASC;',
           {},
           BadWorkspaceSchema,
@@ -392,7 +395,7 @@ describe('@prairielearn/postgres', function () {
       });
 
       it('closes the cursor when the stream is closed', async () => {
-        const cursor = await queryValidatedCursor('SELECT * FROM workspaces;', {}, WorkspaceSchema);
+        const cursor = await queryCursor('SELECT * FROM workspaces;', {}, WorkspaceSchema);
         const stream = cursor.stream(1);
 
         const rows: any[] = [];