@prairielearn/postgres 5.0.3 → 6.0.1

package/src/default-pool.ts

@@ -69,49 +69,6 @@ export const endTransactionAsync = defaultPool.endTransactionAsync.bind(defaultP
  * will be committed otherwise.
  */
 export const runInTransactionAsync = defaultPool.runInTransactionAsync.bind(defaultPool);
-/**
- * Executes a query with the specified parameters.
- *
- * @deprecated Use {@link execute} instead.
- *
- * 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);
-/**
- * Executes a query with the specified parameters. Errors if the query does
- * not return exactly one row.
- *
- * @deprecated Use {@link executeRow} or {@link queryRow} instead.
- */
-export const queryOneRowAsync = defaultPool.queryOneRowAsync.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);
-/**
- * Calls the given sproc with the specified parameters.
- *
- * @deprecated Use {@link callRows} instead.
- */
-export const callAsync = defaultPool.callAsync.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);
-/**
- * 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);
 /**
  * Calls a sproc with the specified parameters using a specific client.
  */
@@ -130,21 +87,15 @@ export const callWithClientZeroOrOneRowAsync =
 /**
  * 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);
 /**
@@ -162,6 +113,40 @@ export const callRow = defaultPool.callRow.bind(defaultPool);
  * or a single row that conforms to the given Zod schema.
  */
 export const callOptionalRow = defaultPool.callOptionalRow.bind(defaultPool);
+/**
+ * Executes a query and returns all values from a single column, validated
+ * against the given Zod schema. Errors if the query returns more than one column.
+ */
+export const queryScalars = defaultPool.queryScalars.bind(defaultPool);
+/**
+ * Executes a query and returns a single value from a single column, validated
+ * against the given Zod schema. Errors if the query does not return exactly
+ * one row or returns more than one column.
+ */
+export const queryScalar = defaultPool.queryScalar.bind(defaultPool);
+/**
+ * Executes a query and returns a single value from a single column, or null
+ * if no rows are returned. Validated against the given Zod schema. Errors if
+ * the query returns more than one row or more than one column.
+ */
+export const queryOptionalScalar = defaultPool.queryOptionalScalar.bind(defaultPool);
+/**
+ * Calls the given sproc and returns all values from a single column, validated
+ * against the given Zod schema. Errors if the sproc returns more than one column.
+ */
+export const callScalars = defaultPool.callScalars.bind(defaultPool);
+/**
+ * Calls the given sproc and returns a single value from a single column, validated
+ * against the given Zod schema. Errors if the sproc does not return exactly
+ * one row or returns more than one column.
+ */
+export const callScalar = defaultPool.callScalar.bind(defaultPool);
+/**
+ * Calls the given sproc and returns a single value from a single column, or
+ * null if no rows are returned. Validated against the given Zod schema.
+ * Errors if the sproc returns more than one row or more than one column.
+ */
+export const callOptionalScalar = defaultPool.callOptionalScalar.bind(defaultPool);
 
 /**
  * Executes a query with the specified parameters. Returns the number of rows affected.

package/src/index.ts

@@ -1,7 +1,7 @@
 export { type PoolClient } from 'pg';
 
 export { loadSql, loadSqlEquiv } from './loader.js';
-export { PostgresPool, type PostgresPoolConfig } from './pool.js';
+export { type AnyRowSchema, PostgresPool, type PostgresPoolConfig } from './pool.js';
 
 export * from './default-pool.js';
 

package/src/pool.test.ts

@@ -6,14 +6,19 @@ import { ZodError, z } from 'zod';
 
 import {
   callOptionalRow,
+  callOptionalScalar,
   callRow,
   callRows,
+  callScalar,
+  callScalars,
   execute,
-  queryAsync,
   queryCursor,
   queryOptionalRow,
+  queryOptionalScalar,
   queryRow,
   queryRows,
+  queryScalar,
+  queryScalars,
 } from './default-pool.js';
 import { makePostgresTestUtils } from './test-utils.js';
 
@@ -59,32 +64,35 @@ describe('@prairielearn/postgres', function () {
   describe('paramsToArray', () => {
     it('enforces SQL must be a string', async () => {
       // @ts-expect-error SQL must be a string
-      const rows = queryAsync({ invalid: true }, {});
+      const rows = execute({ invalid: true }, {});
       await expect(rows).rejects.toThrow('SQL must be a string');
     });
 
     it('enforces params must be array or object', async () => {
       // @ts-expect-error params must be an array or object
-      const rows = queryAsync('SELECT 33;', 33);
+      const rows = execute('SELECT 33;', 33);
       await expect(rows).rejects.toThrow('params must be array or object');
     });
 
     it('rejects missing parameters', async () => {
-      const rows = queryAsync('SELECT $missing;', {});
+      const rows = execute('SELECT $missing;', {});
       await expect(rows).rejects.toThrow('Missing parameter');
     });
 
     it('rejects unused parameters in testing', async () => {
-      const rows = queryAsync('SELECT 33;', { unsed_parameter: true });
+      const rows = execute('SELECT 33;', { unsed_parameter: true });
       await expect(rows).rejects.toThrow('Unused parameter');
     });
   });
 
   describe('queryRows', () => {
     it('handles single column', async () => {
-      const rows = await queryRows('SELECT id FROM workspaces WHERE id <= 10;', z.string());
+      const rows = await queryRows(
+        'SELECT id FROM workspaces WHERE id <= 10;',
+        z.object({ id: z.string() }),
+      );
       assert.lengthOf(rows, 10);
-      assert.equal(rows[0], '1');
+      assert.equal(rows[0].id, '1');
     });
 
     it('handles multiple columns', async () => {
@@ -106,8 +114,11 @@ describe('@prairielearn/postgres', function () {
 
   describe('queryRow', () => {
     it('handles single column', async () => {
-      const row = await queryRow('SELECT id FROM workspaces WHERE id = 1;', z.string());
-      assert.equal(row, '1');
+      const row = await queryRow(
+        'SELECT id FROM workspaces WHERE id = 1;',
+        z.object({ id: z.string() }),
+      );
+      assert.equal(row.id, '1');
     });
 
     it('handles multiple columns', async () => {
@@ -134,8 +145,11 @@ describe('@prairielearn/postgres', function () {
 
   describe('queryOptionalRow', () => {
     it('handles single column', async () => {
-      const row = await queryRow('SELECT id FROM workspaces WHERE id = 1;', z.string());
-      assert.equal(row, '1');
+      const row = await queryRow(
+        'SELECT id FROM workspaces WHERE id = 1;',
+        z.object({ id: z.string() }),
+      );
+      assert.equal(row.id, '1');
     });
 
     it('handles multiple columns', async () => {
@@ -171,15 +185,15 @@ describe('@prairielearn/postgres', function () {
 
   describe('callRows', () => {
     it('handles single column', async () => {
-      const rows = await callRows('test_sproc_one_column_ten_rows', z.string());
+      const rows = await callRows('test_sproc_one_column_ten_rows', z.object({ id: z.string() }));
       assert.lengthOf(rows, 10);
-      assert.equal(rows[0], '1');
+      assert.equal(rows[0].id, '1');
     });
 
     it('handles parameters', async () => {
-      const rows = await callRows('test_sproc_one_column', [10], z.string());
+      const rows = await callRows('test_sproc_one_column', [10], z.object({ id: z.string() }));
       assert.lengthOf(rows, 10);
-      assert.equal(rows[0], '1');
+      assert.equal(rows[0].id, '1');
     });
 
     it('handles multiple columns', async () => {
@@ -194,13 +208,13 @@ describe('@prairielearn/postgres', function () {
 
   describe('callRow', () => {
     it('handles single column', async () => {
-      const row = await callRow('test_sproc_one_column_one_row', z.string());
-      assert.equal(row, '1');
+      const row = await callRow('test_sproc_one_column_one_row', z.object({ id: z.string() }));
+      assert.equal(row.id, '1');
     });
 
     it('handles parameters', async () => {
-      const row = await callRow('test_sproc_one_column', [1], z.string());
-      assert.equal(row, '1');
+      const row = await callRow('test_sproc_one_column', [1], z.object({ id: z.string() }));
+      assert.equal(row.id, '1');
     });
 
     it('handles multiple columns', async () => {
@@ -222,13 +236,16 @@ describe('@prairielearn/postgres', function () {
 
   describe('callOptionalRow', () => {
     it('handles single column', async () => {
-      const row = await callOptionalRow('test_sproc_one_column_one_row', z.string());
-      assert.equal(row, '1');
+      const row = await callOptionalRow(
+        'test_sproc_one_column_one_row',
+        z.object({ id: z.string() }),
+      );
+      assert.equal(row?.id, '1');
     });
 
     it('handles parameters', async () => {
-      const row = await callOptionalRow('test_sproc_one_column', [1], z.string());
-      assert.equal(row, '1');
+      const row = await callOptionalRow('test_sproc_one_column', [1], z.object({ id: z.string() }));
+      assert.equal(row?.id, '1');
     });
 
     it('handles multiple columns', async () => {
@@ -249,14 +266,173 @@ describe('@prairielearn/postgres', function () {
     });
   });
 
+  describe('queryScalars', () => {
+    it('returns all scalar values', async () => {
+      const ids = await queryScalars(
+        'SELECT id FROM workspaces WHERE id <= 10 ORDER BY id ASC;',
+        z.string(),
+      );
+      assert.lengthOf(ids, 10);
+      assert.equal(ids[0], '1');
+      assert.equal(ids[9], '10');
+    });
+
+    it('handles parameters', async () => {
+      const ids = await queryScalars(
+        'SELECT id FROM workspaces WHERE id <= $1 ORDER BY id ASC;',
+        [5],
+        z.string(),
+      );
+      assert.lengthOf(ids, 5);
+    });
+
+    it('rejects multi-column queries', async () => {
+      const result = queryScalars('SELECT * FROM workspaces WHERE id <= 10;', z.string());
+      await expect(result).rejects.toThrow('Expected exactly one column');
+    });
+  });
+
+  describe('queryScalar', () => {
+    it('returns a single scalar value', async () => {
+      const id = await queryScalar('SELECT id FROM workspaces WHERE id = 1;', z.string());
+      assert.equal(id, '1');
+    });
+
+    it('handles parameters', async () => {
+      const id = await queryScalar('SELECT id FROM workspaces WHERE id = $1;', [1], z.string());
+      assert.equal(id, '1');
+    });
+
+    it('rejects results with zero rows', async () => {
+      const result = queryScalar('SELECT id FROM workspaces WHERE id = -1;', z.string());
+      await expect(result).rejects.toThrow('Incorrect rowCount: 0');
+    });
+
+    it('rejects results with multiple rows', async () => {
+      const result = queryScalar('SELECT id FROM workspaces;', z.string());
+      await expect(result).rejects.toThrow('Incorrect rowCount: 100');
+    });
+
+    it('rejects multi-column queries', async () => {
+      const result = queryScalar('SELECT * FROM workspaces WHERE id = 1;', z.string());
+      await expect(result).rejects.toThrow('Expected exactly one column');
+    });
+  });
+
+  describe('queryOptionalScalar', () => {
+    it('returns a scalar value when present', async () => {
+      const id = await queryOptionalScalar('SELECT id FROM workspaces WHERE id = 1;', z.string());
+      assert.equal(id, '1');
+    });
+
+    it('handles parameters', async () => {
+      const id = await queryOptionalScalar(
+        'SELECT id FROM workspaces WHERE id = $1;',
+        [1],
+        z.string(),
+      );
+      assert.equal(id, '1');
+    });
+
+    it('returns null for zero rows', async () => {
+      const id = await queryOptionalScalar('SELECT id FROM workspaces WHERE id = -1;', z.string());
+      assert.isNull(id);
+    });
+
+    it('rejects results with multiple rows', async () => {
+      const result = queryOptionalScalar('SELECT id FROM workspaces;', z.string());
+      await expect(result).rejects.toThrow('Incorrect rowCount: 100');
+    });
+
+    it('rejects multi-column queries', async () => {
+      const result = queryOptionalScalar('SELECT * FROM workspaces WHERE id = 1;', z.string());
+      await expect(result).rejects.toThrow('Expected exactly one column');
+    });
+  });
+
+  describe('callScalars', () => {
+    it('returns all scalar values', async () => {
+      const ids = await callScalars('test_sproc_one_column', [10], z.string());
+      assert.lengthOf(ids, 10);
+      assert.equal(ids[0], '1');
+    });
+
+    it('handles no parameters', async () => {
+      const ids = await callScalars('test_sproc_one_column_ten_rows', z.string());
+      assert.lengthOf(ids, 10);
+    });
+
+    it('rejects multi-column sprocs', async () => {
+      const result = callScalars('test_sproc_two_columns', [10], z.string());
+      await expect(result).rejects.toThrow('Expected exactly one column');
+    });
+  });
+
+  describe('callScalar', () => {
+    it('returns a single scalar value', async () => {
+      const id = await callScalar('test_sproc_one_column_one_row', z.string());
+      assert.equal(id, '1');
+    });
+
+    it('handles parameters', async () => {
+      const id = await callScalar('test_sproc_one_column', [1], z.string());
+      assert.equal(id, '1');
+    });
+
+    it('rejects results with zero rows', async () => {
+      const result = callScalar('test_sproc_one_column', [0], z.string());
+      await expect(result).rejects.toThrow('Incorrect rowCount: 0');
+    });
+
+    it('rejects results with multiple rows', async () => {
+      const result = callScalar('test_sproc_one_column', [100], z.string());
+      await expect(result).rejects.toThrow('Incorrect rowCount: 100');
+    });
+
+    it('rejects multi-column sprocs', async () => {
+      const result = callScalar('test_sproc_two_columns', [1], z.string());
+      await expect(result).rejects.toThrow('Expected exactly one column');
+    });
+  });
+
+  describe('callOptionalScalar', () => {
+    it('returns a scalar value when present', async () => {
+      const id = await callOptionalScalar('test_sproc_one_column_one_row', z.string());
+      assert.equal(id, '1');
+    });
+
+    it('handles parameters', async () => {
+      const id = await callOptionalScalar('test_sproc_one_column', [1], z.string());
+      assert.equal(id, '1');
+    });
+
+    it('returns null for zero rows', async () => {
+      const id = await callOptionalScalar('test_sproc_one_column', [0], z.string());
+      assert.isNull(id);
+    });
+
+    it('rejects results with multiple rows', async () => {
+      const result = callOptionalScalar('test_sproc_one_column', [100], z.string());
+      await expect(result).rejects.toThrow('Incorrect rowCount: 100');
+    });
+
+    it('rejects multi-column sprocs', async () => {
+      const result = callOptionalScalar('test_sproc_two_columns', [1], z.string());
+      await expect(result).rejects.toThrow('Expected exactly one column');
+    });
+  });
+
   describe('queryCursor', () => {
     it('handles single column', async () => {
-      const cursor = await queryCursor('SELECT id FROM workspaces WHERE id = 1;', z.string());
-      const allRows: string[] = [];
+      const cursor = await queryCursor(
+        'SELECT id FROM workspaces WHERE id = 1;',
+        z.object({ id: z.string() }),
+      );
+      const allRows: { id: string }[] = [];
       for await (const rows of cursor.iterate(10)) {
         allRows.push(...rows);
       }
-      assert.equal(allRows[0], '1');
+      assert.equal(allRows[0].id, '1');
     });
 
     it('handles multiple columns', async () => {