@prairielearn/postgres 1.7.6 → 1.7.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @prairielearn/postgres
 
+## 1.7.8
+
+### Patch Changes
+
+- 8dd894623: Upgrade all dependencies
+
+## 1.7.7
+
+### Patch Changes
+
+- bd0053577: Upgrade all dependencies
+
 ## 1.7.6
 
 ### Patch Changes

package/README.md

@@ -79,7 +79,7 @@ console.log(result.rows);
 
 The `queryAsync` function returns a [`pg.Result`](https://node-postgres.com/apis/result) object; see linked documentation for a list of additional properties that are available on that object.
 
-There are a variety of utility methods that can make assertions about the results:
+There are also utility methods that can make assertions about the results:
 
 - `queryOneRowAsync`: Throws an error if the result doesn't have exactly one row.
 - `queryZeroOrOneRowAsync`: Throws an error if the result has more than one row.
@@ -116,7 +116,7 @@ For increased safety and confidence, you can describe the shape of data you expe
 
 ```ts
 import { z } from 'zod';
-import { loadSqlEquiv, queryValidatedRows } from '@prairielearn/postgres';
+import { loadSqlEquiv, queryRows, queryRow, queryOptionalRow } from '@prairielearn/postgres';
 
 const sql = loadSqlEquiv(import.meta.url);
 
@@ -126,11 +126,40 @@ const User = z.object({
   age: z.number(),
 });
 
-const users = await queryValidatedOneRow(sql.select_user, { user_id: 1 }, User);
-console.log(users[0].name);
+// Get all users. Returns an array of objects.
+const users = await queryRows(sql.select_users, User);
+
+// Get single user. Returns a single object.
+const user = await queryRow(sql.select_user, { user_id: '1' }, User);
+
+// Get a user that may not exist. Returns `null` if the user cannot be found.
+const maybeUser = await queryOptionalRow(sql.select_user, { user_id: '1' }, User);
 ```
 
-As with the non-validated query functions, there are several variants available:
+These functions have some behaviors that can make them more convenient to work with:
+
+- Passing an object with parameters is optional.
+
+- If the query returns a single column, that column is validated and returned directly. For example, consider the following query:
+
+  ```sql
+  -- BLOCK select_user_names
+  SELECT
+    name
+  FROM
+    users;
+  ```
+
+  If we then use that query with `queryRows`, the returned Promise resolves to an array of strings:
+
+  ```ts
+  const userNames = await queryRows(sql.select_user_names, z.string());
+
+  // Prints something like `["Alice", "Bob"]`.
+  console.log(userNames);
+  ```
+
+There are also a number of legacy functions available, though these are discouraged in new code.
 
 - `queryValidatedRows`
 - `queryValidatedOneRow`
@@ -142,6 +171,8 @@ As with the non-validated query functions, there are several variants available:
 - `callValidatedOneRow`
 - `callValidatedZeroOrOneRow`
 
+For details on the behavior of these functions, see the source code.
+
 ### Transactions
 
 To use transactions, wrap your queries with the `runInTransactionAsync` function:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prairielearn/postgres",
-  "version": "1.7.6",
+  "version": "1.7.8",
   "main": "./dist/index.js",
   "repository": {
     "type": "git",
@@ -14,21 +14,21 @@
   },
   "devDependencies": {
     "@prairielearn/tsconfig": "^0.0.0",
-    "@types/mocha": "^10.0.1",
-    "@types/multipipe": "^3.0.1",
-    "@types/node": "^18.17.14",
+    "@types/mocha": "^10.0.3",
+    "@types/multipipe": "^3.0.3",
+    "@types/node": "^18.18.7",
     "mocha": "^10.2.0",
     "ts-node": "^10.9.1",
     "typescript": "^5.2.2"
   },
   "dependencies": {
-    "@types/debug": "^4.1.8",
-    "@types/lodash": "^4.14.198",
-    "@types/pg-cursor": "^2.7.0",
+    "@types/debug": "^4.1.10",
+    "@types/lodash": "^4.14.200",
+    "@types/pg-cursor": "^2.7.1",
     "multipipe": "^4.0.0",
     "pg": "^8.11.3",
     "pg-cursor": "^2.10.3",
     "pg-pool": "^3.6.1",
-    "zod": "^3.22.2"
+    "zod": "^3.22.4"
   }
 }