Ian/v.nullable (#42913)

- extra sugar

GitOrigin-RevId: fa2580bfde61b27d880d025e1e3c2919257deef4

Author: ianmacartney

npm-packages/convex/src/values/validator.ts

@@ -222,6 +222,13 @@ export const v = {
   optional: <T extends GenericValidator>(value: T) => {
     return value.asOptional() as VOptional<T>;
   },
+
+  /**
+   * Allows specifying a value or null.
+   */
+  nullable: <T extends GenericValidator>(value: T) => {
+    return v.union(value, v.null());
+  },
 };
 
 /**

npm-packages/docs/docs/functions/validation.mdx

@@ -92,6 +92,8 @@ export default mutation({
 });
 ```
 
+For convenience, `v.nullable(foo)` is equivalent to `v.union(foo, v.null())`.
+
 ### Literals
 
 Fields that are a constant can be expressed with `v.literal`. This is especially

npm-packages/private-demos/typescript-modern/convex/messages.ts

@@ -34,7 +34,7 @@ const messageDoc = messageValidator.extend({
 
 export const get = query({
   args: { id: v.id("messages") },
-  returns: v.union(v.null(), messageDoc),
+  returns: v.nullable(messageDoc),
   handler: async (ctx, { id }) => {
     return await ctx.db.get(id);
   },