`null` vs `undefined` generates a lot of boilerplate code

[pupeno]

Hello,

I'm new to Convex, so maybe I'm missing something, but so far I can't find it. I created a super tiny application, a CRUD for a table that just stores some numbers, that's it. This application ended up having a lot of boilerplate, with the structure of the data having to be defined 4 times, which feels very error prone.

One of the problems was that Convex demands nulls to represent blank fields in the API, and undefined to represent blank fields when calling db.patch, so there's a need to convert between these representations. This could be fixed by either db.patch accepting nulls or the API accepting (and not silently dropping) undefineds.

You can see the little app here: https://github.com/pupeno/convex-nextjs-playground

The reason there are 4 representations of the shape of the data is because there's an extra one for the schema, and another one for the form, because the forms, at least in React Hook Form, use "" to represent blank. I don't believe Convex can contribute in any way to this.

[graham]

Thanks for the feedback! I understand the frustration with the conversion boilerplate.

The difference between null and undefined in Convex is intentional and represents two distinct operations:

• undefined in db.patch means "unset this field" - the field becomes undefined (and is only an option if the field is optional)
• null in the API means "set this field to null" - an explicit value (that is allowed by a union or v.null).

If we changed db.patch to accept null with the same "unset" behavior as undefined, you'd lose the ability to explicitly set a field to null when patching. Similarly, if the API silently accepted undefined, you couldn't distinguish between "the value is null" and "unset this field."

Both behaviors are necessary for different use cases. The current design ensures you can express both "unset the field" and "set to null" operations. While this does require conversion logic in your code, changing it would actually hide functionality that some users need.

That said, we understand this creates friction. We're always looking for ways to improve the developer experience while preserving these important distinctions.

There may be a border case I'm missing, and if there is, please mention it, but I don't think this change we'd be willing to make.

[pupeno]

In that case, there's no way through an API to unset a field. I didn't look about the API serialization, is there no way to serialize "unset this field"?

I believe if I was using PostgreSQL or MySQL, the explicit null and unsetting the field would mean the same thing, but the Convex database has two different options here.

[graham]

Ahh i think i understand what you are saying a little more, am i getting this right?

if you have an mutation with a 'optional' field, there is no way to determine the difference between "no update leave the value as is" and "unset this value" since undefined would be the value for both?

[pupeno]

Exactly! Actually, if the client sends undefined to the API, Convex just drops it and it never gets to the mutation, same as if it was never sent. So the semantics of null and undefined are different between the API layer and patch.

[graham]

Ahh okay, I didn't exactly capture that the first read (sorry about that).

I'll talk to the team, my guess is this is something that isn't easily solved. Since changing the behavior of sending null could have other downstream effects we don't know about (because someone might be relying on the current behavior).

My guess is that there is no change we can make that makes everyone happy, but...

1. I understand your issue.
2. I agree it is tough to work with, and if we can think of something that resolves it in a safe way, I'm sure the team would be open to changing it.
3. Undefined/null/etc is hard :)

I'll do my best to articulate your issue and if I have an answer or there is discussion I'll be sure to update this thread, however, it may take some time.

Thank you for bringing this up!