Specialized Helpers

Mongoose provides several specialized types, such as ObjectId and Buffer. @nullix/zod-mongoose includes dedicated helpers to easily define these types in your Zod schemas.

zObjectId(options?)

Helper to create a Zod schema representing a Mongoose ObjectId.

• options: Optional MongooseMeta for this field.

By default, zObjectId() creates a required Zod field (unless .optional() is used) but omits the field from the generated Mongoose schema. This allows Mongoose to manage the automatic generation and internal lifecycle of the _id field without conflicts.

import { z } from 'zod/v4';
import { zObjectId } from '@nullix/zod-mongoose';

const UserZodSchema = z.object({
  _id: zObjectId(), // Required for Zod validation, omitted from Mongoose schema
  name: z.string(),
});

To explicitly define the _id field in the Mongoose schema (e.g., to add an index, a custom getter, or to disable auto-generation), use the includeId: true flag.

const CustomIdSchema = z.object({
  _id: zObjectId({ includeId: true, index: true }),
});

zPopulated(ref, schema, options?)

Helper for fields that can be either an ObjectId (unpopulated) or a populated object.

• ref: The name of the Mongoose model being referenced.
• schema: The Zod schema representing the populated object.
• options: Optional MongooseMeta for this field.

const UserSchema = z.object({ name: z.string() });
const PostSchema = z.object({
  author: zPopulated('User', UserSchema),
});

PopulatedSchema<T, K>

TypeScript utility type to extract the populated object type from a zPopulated union within a larger type. This is useful for typing Mongoose results after calling .populate().

• T: The Zod-inferred type (e.g., z.infer<typeof PostSchema>).
• K: The key(s) to populate (optional). If omitted, it will try to populate all zPopulated fields in the object.

import { PopulatedSchema } from '@nullix/zod-mongoose';

// Populate only the 'author' field
type PostWithAuthor = PopulatedSchema<z.infer<typeof PostSchema>, 'author'>;

// Populate all possible fields
type FullPost = PopulatedSchema<z.infer<typeof PostSchema>>;

zBuffer(options?)

Helper to create a Zod schema representing a Mongoose Buffer.

• options: Optional MongooseMeta for this field.

import { zBuffer } from '@nullix/zod-mongoose';

const ProductSchema = z.object({
  imageData: zBuffer({ required: true }),
});

genTimestampsSchema(createdAtField?, updatedAtField?)

Returns a plain object (Zod shape) with timestamp fields. This allows for easy spreading into z.object().

• createdAtField: Name of the "created at" field (default: createdAt).
• updatedAtField: Name of the "updated at" field (default: updatedAt).

Pass null as a name to disable a specific field.

import { z } from 'zod/v4';
import { genTimestampsSchema, withMongoose } from '@nullix/zod-mongoose';

const userSchema = withMongoose(
  z.object({
    ...genTimestampsSchema(),
    name: z.string(),
  }),
  { timestamps: true }
);

const mongooseSchema = toMongooseSchema(userSchema);
// Resulting Mongoose schema will have { timestamps: true } automatically.