convex-helpers
Version:
A collection of useful code to complement the official convex package.
425 lines (424 loc) • 15.8 kB
JavaScript
import { z } from "zod";
import { v, ConvexError, } from "convex/values";
import { NoOp, splitArgs, } from "./customFunctions";
/**
* Create a validator for a Convex `Id`.
*
* When used as a validator, it will check that it's for the right table.
* When used as a parser, it will only check that the Id is a string.
*
* @param tableName - The table that the `Id` references. i.e.` Id<tableName>`
* @returns - A Zod object representing a Convex `Id`
*/
export const zid = (tableName) => new Zid({ typeName: "ConvexId", tableName });
/**
* zCustomQuery is like customQuery, but allows validation via zod.
* You can define custom behavior on top of `query` or `internalQuery`
* by passing a function that modifies the ctx and args. Or NoOp to do nothing.
*
* Example usage:
* ```js
* const myQueryBuilder = zCustomQuery(query, {
* args: { sessionId: v.id("sessions") },
* input: async (ctx, args) => {
* const user = await getUserOrNull(ctx);
* const session = await db.get(sessionId);
* const db = wrapDatabaseReader({ user }, ctx.db, rlsRules);
* return { ctx: { db, user, session }, args: {} };
* },
* });
*
* // Using the custom builder
* export const getSomeData = myQueryBuilder({
* args: { someArg: z.string() },
* handler: async (ctx, args) => {
* const { db, user, session, scheduler } = ctx;
* const { someArg } = args;
* // ...
* }
* });
* ```
*
* Simple usage only modifying ctx:
* ```js
* const myInternalQuery = zCustomQuery(
* internalQuery,
* customCtx(async (ctx) => {
* return {
* // Throws an exception if the user isn't logged in
* user: await getUserByTokenIdentifier(ctx),
* };
* })
* );
*
* // Using it
* export const getUser = myInternalQuery({
* args: { email: z.string().email() },
* handler: async (ctx, args) => {
* console.log(args.email);
* return ctx.user;
* },
* });
*
* @param query The query to be modified. Usually `query` or `internalQuery`
* from `_generated/server`.
* @param mod The modifier to be applied to the query, changing ctx and args.
* @returns A new query builder using zod validation to define queries.
*/
export function zCustomQuery(query, mod) {
// Looking forward to when input / args / ... are optional
const inputMod = mod.input ?? NoOp.input;
const inputArgs = mod.args ?? NoOp.args;
function customQueryBuilder(fn) {
if ("args" in fn) {
const convexValidator = zodToConvexFields(fn.args);
return query({
args: {
...convexValidator,
...inputArgs,
},
handler: async (ctx, allArgs) => {
const { split, rest } = splitArgs(inputArgs, allArgs);
const added = await inputMod(ctx, split);
const parsed = z.object(fn.args).safeParse(rest);
if (!parsed.success) {
throw new ConvexError({
ZodError: JSON.parse(JSON.stringify(parsed.error.errors, null, 2)),
});
}
const result = await fn.handler({ ...ctx, ...added.ctx }, { ...parsed.data, ...added.args });
if (fn.output) {
// We don't catch the error here. It's a developer error and we
// don't want to risk exposing the unexpected value to the client.
return fn.output.parse(result);
}
return result;
},
});
}
if (Object.keys(inputArgs).length > 0) {
throw new Error("If you're using a custom function with arguments for the input " +
"modifier, you must declare the arguments for the function too.");
}
const handler = fn.handler ?? fn;
return query({
handler: async (ctx, args) => {
const { ctx: modCtx } = await inputMod(ctx, args);
return await handler({ ...ctx, ...modCtx }, args);
},
});
}
return customQueryBuilder;
}
/**
* zCustomMutation is like customMutation, but allows validation via zod.
* You can define custom behavior on top of `mutation` or `internalMutation`
* by passing a function that modifies the ctx and args. Or NoOp to do nothing.
*
* Example usage:
* ```js
* const myMutationBuilder = zCustomMutation(mutation, {
* args: { sessionId: v.id("sessions") },
* input: async (ctx, args) => {
* const user = await getUserOrNull(ctx);
* const session = await db.get(sessionId);
* const db = wrapDatabaseReader({ user }, ctx.db, rlsRules);
* return { ctx: { db, user, session }, args: {} };
* },
* });
*
* // Using the custom builder
* export const getSomeData = myMutationBuilder({
* args: { someArg: z.string() },
* handler: async (ctx, args) => {
* const { db, user, session, scheduler } = ctx;
* const { someArg } = args;
* // ...
* }
* });
* ```
*
* Simple usage only modifying ctx:
* ```js
* const myInternalMutation = zCustomMutation(
* internalMutation,
* customCtx(async (ctx) => {
* return {
* // Throws an exception if the user isn't logged in
* user: await getUserByTokenIdentifier(ctx),
* };
* })
* );
*
* // Using it
* export const getUser = myInternalMutation({
* args: { email: z.string().email() },
* handler: async (ctx, args) => {
* console.log(args.email);
* return ctx.user;
* },
* });
*
* @param mutation The mutation to be modified. Usually `mutation` or `internalMutation`
* from `_generated/server`.
* @param mod The modifier to be applied to the mutation, changing ctx and args.
* @returns A new mutation builder using zod validation to define queries.
*/
export function zCustomMutation(mutation, mod) {
// Looking forward to when input / args / ... are optional
const inputMod = mod.input ?? NoOp.input;
const inputArgs = mod.args ?? NoOp.args;
function customMutationBuilder(fn) {
if ("args" in fn) {
const convexValidator = zodToConvexFields(fn.args);
return mutation({
args: {
...convexValidator,
...inputArgs,
},
handler: async (ctx, allArgs) => {
const { split, rest } = splitArgs(inputArgs, allArgs);
const added = await inputMod(ctx, split);
const parsed = z.object(fn.args).safeParse(rest);
if (!parsed.success) {
throw new ConvexError({
ZodError: JSON.parse(JSON.stringify(parsed.error.errors, null, 2)),
});
}
const result = await fn.handler({ ...ctx, ...added.ctx }, { ...parsed.data, ...added.args });
if (fn.output) {
// We don't catch the error here. It's a developer error and we
// don't want to risk exposing the unexpected value to the client.
return fn.output.parse(result);
}
return result;
},
});
}
if (Object.keys(inputArgs).length > 0) {
throw new Error("If you're using a custom function with arguments for the input " +
"modifier, you must declare the arguments for the function too.");
}
const handler = fn.handler ?? fn;
return mutation({
handler: async (ctx, args) => {
const { ctx: modCtx } = await inputMod(ctx, args);
return await handler({ ...ctx, ...modCtx }, args);
},
});
}
return customMutationBuilder;
}
/**
* zCustomAction is like customAction, but allows validation via zod.
* You can define custom behavior on top of `action` or `internalAction`
* by passing a function that modifies the ctx and args. Or NoOp to do nothing.
*
* Example usage:
* ```js
* const myActionBuilder = zCustomAction(action, {
* args: { sessionId: v.id("sessions") },
* input: async (ctx, args) => {
* const user = await getUserOrNull(ctx);
* const session = await db.get(sessionId);
* const db = wrapDatabaseReader({ user }, ctx.db, rlsRules);
* return { ctx: { db, user, session }, args: {} };
* },
* });
*
* // Using the custom builder
* export const getSomeData = myActionBuilder({
* args: { someArg: z.string() },
* handler: async (ctx, args) => {
* const { db, user, session, scheduler } = ctx;
* const { someArg } = args;
* // ...
* }
* });
* ```
*
* Simple usage only modifying ctx:
* ```js
* const myInternalAction = zCustomAction(
* internalAction,
* customCtx(async (ctx) => {
* return {
* // Throws an exception if the user isn't logged in
* user: await getUserByTokenIdentifier(ctx),
* };
* })
* );
*
* // Using it
* export const getUser = myInternalAction({
* args: { email: z.string().email() },
* handler: async (ctx, args) => {
* console.log(args.email);
* return ctx.user;
* },
* });
*
* @param action The action to be modified. Usually `action` or `internalAction`
* from `_generated/server`.
* @param mod The modifier to be applied to the action, changing ctx and args.
* @returns A new action builder using zod validation to define queries.
*/
export function zCustomAction(action, mod) {
// Looking forward to when input / args / ... are optional
const inputMod = mod.input ?? NoOp.input;
const inputArgs = mod.args ?? NoOp.args;
function customActionBuilder(fn) {
if ("args" in fn) {
const convexValidator = zodToConvexFields(fn.args);
return action({
args: {
...convexValidator,
...inputArgs,
},
handler: async (ctx, allArgs) => {
const { split, rest } = splitArgs(inputArgs, allArgs);
const added = await inputMod(ctx, split);
const parsed = z.object(fn.args).safeParse(rest);
if (!parsed.success) {
throw new ConvexError({
ZodError: JSON.parse(JSON.stringify(parsed.error.errors, null, 2)),
});
}
const result = await fn.handler({ ...ctx, ...added.ctx }, { ...parsed.data, ...added.args });
if (fn.output) {
// We don't catch the error here. It's a developer error and we
// don't want to risk exposing the unexpected value to the client.
return fn.output.parse(result);
}
return result;
},
});
}
if (Object.keys(inputArgs).length > 0) {
throw new Error("If you're using a custom function with arguments for the input " +
"modifier, you must declare the arguments for the function too.");
}
const handler = fn.handler ?? fn;
return action({
handler: async (ctx, args) => {
const { ctx: modCtx } = await inputMod(ctx, args);
return await handler({ ...ctx, ...modCtx }, args);
},
});
}
return customActionBuilder;
}
/**
* Turn a Zod validator into a Convex Validator.
* @param zod Zod validator can be a Zod object, or a Zod type like `z.string()`
* @returns Convex Validator (e.g. `v.string()` from "convex/values")
*/
export function zodToConvex(zod) {
const typeName = zod._def.typeName;
switch (typeName) {
case "ConvexId":
return v.id(zod._def.tableName);
case "ZodString":
return v.string();
case "ZodNumber":
case "ZodNaN":
return v.number();
case "ZodBigInt":
return v.int64();
case "ZodBoolean":
return v.boolean();
case "ZodNull":
return v.null();
case "ZodAny":
case "ZodUnknown":
return v.any();
case "ZodArray":
const inner = zodToConvex(zod._def.type);
if (inner.isOptional) {
throw new Error("Arrays of optional values are not supported");
}
return v.array(inner);
case "ZodObject":
return v.object(zodToConvexFields(zod._def.shape()));
case "ZodUnion":
case "ZodDiscriminatedUnion":
return v.union(...zod._def.options.map((v) => zodToConvex(v)));
case "ZodTuple":
const allTypes = zod._def.items.map((v) => zodToConvex(v));
if (zod._def.rest) {
allTypes.push(zodToConvex(zod._def.rest));
}
return v.array(v.union(...allTypes));
case "ZodLazy":
return zodToConvex(zod._def.getter());
case "ZodLiteral":
return v.literal(zod._def.value);
case "ZodEnum":
return v.union(...zod._def.values.map((l) => v.literal(l)));
case "ZodEffects":
return zodToConvex(zod._def.schema);
case "ZodOptional":
return v.optional(zodToConvex(zod.unwrap()));
case "ZodNullable":
const nullable = zodToConvex(zod.unwrap());
if (nullable.isOptional) {
// Swap nullable(optional(Z)) for optional(nullable(Z))
// Casting to any to ignore the mismatch of optional
return v.optional(v.union(v.null(), nullable));
}
return v.union(v.null(), nullable);
case "ZodBranded":
return zodToConvex(zod.unwrap());
case "ZodDefault":
const withDefault = zodToConvex(zod._def.innerType);
if (withDefault.isOptional) {
return withDefault;
}
return v.optional(withDefault);
case "ZodReadonly":
return zodToConvex(zod._def.innerType);
case "ZodPipeline":
return zodToConvex(zod._def.in);
default:
throw new Error(`Unknown zod type: ${typeName}`);
// N/A or not supported
// case "ZodDate":
// case "ZodSymbol":
// case "ZodUndefined":
// case "ZodNever":
// case "ZodVoid":
// case "ZodIntersection":
// case "ZodRecord":
// case "ZodMap":
// case "ZodSet":
// case "ZodFunction":
// case "ZodNativeEnum":
// case "ZodCatch":
// case "ZodPromise":
}
}
/**
* Like zodToConvex, but it takes in a bare object, as expected by Convex
* function arguments, or the argument to defineTable.
*
* @param zod Object with string keys and Zod validators as values
* @returns Object with the same keys, but with Convex validators as values
*/
export function zodToConvexFields(zod) {
return Object.fromEntries(Object.entries(zod).map(([k, v]) => [k, zodToConvex(v)]));
}
export class Zid extends z.ZodType {
_parse(input) {
return z.string()._parse(input);
}
}
/**
* Zod helper for adding Convex system fields to a record to return.
*
* @param tableName - The table where records are from, i.e. Doc<tableName>
* @param zObject - Validators for the user-defined fields on the document.
* @returns - Zod shape for use with `z.object(shape)` that includes system fields.
*/
export const withSystemFields = (tableName, zObject) => {
return { ...zObject, _id: zid(tableName), _creationTime: z.number() };
};