All non-required inferred fields are nullable

[skrukwa]

Prerequisites

• I have written a descriptive issue title

Mongoose version

9.0.1

Node.js version

24.11.0

MongoDB version

n/a

Operating system

None

Operating system version (i.e. 20.04, 11.3, 10)

No response

Issue

I think that users should be allowed to configure whether they want inferred types to include | null for ANY type (even optional ones) unless explicitly included. Maybe an option inside interface DefaultSchemaOptions?

My rational is that when users create separate interfaces and use them to define their schema instead of using automatic type inference, I very rarely see people include | null for EVERY OPTIONAL TYPE. Despite it being possible for null values to be stored, most users do not want to deal with it in their types. I guess this relates to #14421.

Thanks!

[vkarpov15]

Mongoose allows null for any non-required path, so I think adding | null is important to ensuring our types are accurate. What's your use case for not wanting null?

[skrukwa]

My use case is that I do not store null values in the database (either explicitly or implicitly through undefined serialization), and having the | null type for every non-required path makes passing my documents to other services/APIs after calling toObject or toJSON cumbersome. Given that fields can always be unset as a way of defining "nothing", I do not see null values being necessary.

Furthermore, for those that may want to migrate from separate document interface definitions where they did NOT explicitly define each non-required type with | null to automatic type inference, having to now handle all the | null types will likely be burdensome.

In the official docs, avatar is missing the | null "correct" type:

interface User {
  name: string;
  email: string;
  avatar?: string;
}

In a perfect world, it would be very nice to have to explicitly set nullable (default is non-nullable) and that be reflected in the inferred types.

Value	Nullable	Behaviour
null	true	null is stored
undefined	true	null is stored if field is required, otherwise field is omitted
null	false or unset	validation error
undefined	false or unset	validation error if field is required, otherwise field is omitted

However, given that the current behaviour is that every non-required field is nullable by default, it probably makes sense to have to explicitly set nonNullable instead to preserve backwards compatibility (or maybe as required: nonNullable).

Value	NonNullable	Behaviour
null	false or unset	null is stored
undefined	false or unset	leave as current behaviour for backwards compatibility
null	true	validation error
undefined	true	validation error if field is required, otherwise field is omitted

I really do think that conversations like this and #14421 will keep coming up as long as | null values are left in the inferred types (including raw type).

Thanks!

[vkarpov15]

How do you validate that you don't store null? And what services/APIs make these nulls cumbersome?

[skrukwa]

To be honest, I do not rigorously validate that I don't store null. I presume using a custom validator for each optional field (e.g., validate: { validator: (v) => v !== null }) would prevent null from being saved explicitly. Also, regarding #14421, I don't understand your comment that

new User({ lastName: undefined }) would end up being saved to the database as lastName: null: the MongoDB Node driver serializes undefined as null...

Based on a quick test, undefined is omitted..?

---

Here are some examples of how | null can be cumbersome:

• Unnecessary type widening during REST API ingesting

  • When consuming data from virtually any modern generated API client, Mongoose's | null inferred types cause unnecessary type widening. The Google JSON Style Guide suggests to "consider removing empty or null values" from e.g. OAS specs.
  • e.g. AWS SDK v3: Responses use optional fields exclusively. For example, S3's HeadObject returns Metadata?: Record<string, string>. Assigning to a Mongoose-inferred | null field causes unnecessary type widening.

• Redundant | null types leaking into service's own REST API spec

  • Again, it is common practice for modern APIs to return optional fields, but not nullable fields. This is not natively supported by returning the results of toObject or toJSON without an extra step to remove/transform null values.
  • e.g. Zod / Validation Schemas: When defining API contracts with Zod (z.string().optional()), the inferred type is string | undefined. Mongoose documents cannot be returned directly because string | undefined | null is not assignable to string | undefined.

• Friction with fundamental functions and frameworks

  • React: Most component props are typed as optional (?). Passing a Mongoose field requires val ?? undefined everywhere.
  • Array.prototype.join(separator): Passing undefined uses the default comma. Passing null inserts the literal string "null", corrupting data exports.
  • URLSearchParams: Passing undefined omits the key (correct). Passing null sends the string "null", which causes API authentication errors (e.g. apiKey=null).
  • Intl Constructors: new Intl.NumberFormat('en', options) throws a TypeError if options is null, whereas undefined correctly uses system defaults.
  • etc. etc. etc. Basically all standard functions have optional arguments as optional, not nullable.

---

Revisiting some possible solutions that maintain backwards compatibility:

• Global Config Solution: A allowOptionalAsNullable schema option (default: true). If set to false, it would infer optional fields as T | undefined and guard against nulls being saved.
• Per-Field Solution: A required: 'nonNullable' option that would exclude | null from the inferred type and guard against nulls being saved.

Thanks for the consideration.

[github-actions]

This issue is stale because it has been open 14 days with no activity. Remove stale label or comment or this will be closed in 5 days