joi-objectid-ext

A Joi extension for validating MongoDB ObjectIDs in your validation schemas.

Features

• Validates ObjectID strings (24 character hex strings)
• Works with actual MongoDB ObjectId instances
• Compatible with multiple ObjectId implementations:
  • MongoDB native driver (mongodb)
  • BSON package (bson)
  • Mongoose ObjectIds (mongoose.Types.ObjectId)
• TypeScript support
• Zero dependencies
• Simple API

Installation

1npm install joi-objectid-ext --save
2# or
3yarn add joi-objectid-ext

Usage

Basic usage

1import Joi from "joi";
2import { extendJoiWithObjectId } from "joi-objectid-ext";
3
4// Extend Joi with the ObjectId type
5const ExtendedJoi = extendJoiWithObjectId(Joi);
6
7// Create a schema with ObjectId validation
8const schema = ExtendedJoi.object({
9  id: ExtendedJoi.objectId().required(),
10  optionalId: ExtendedJoi.objectId(),
11});
12
13// Validate a string ObjectId
14const result1 = schema.validate({
15  id: "507f191e810c19729de860ea",
16  optionalId: "507f191e810c19729de860eb",
17});
18// result1.error is undefined (validation passes)
19
20// Validate with invalid ObjectId
21const result2 = schema.validate({
22  id: "not-an-objectid",
23});
24// result2.error contains validation error

Using with MongoDB's ObjectId

1import Joi from "joi";
2import { ObjectId } from "mongodb";
3import { extendJoiWithObjectId } from "joi-objectid-ext";
4
5const ExtendedJoi = extendJoiWithObjectId(Joi);
6
7const schema = ExtendedJoi.object({
8  id: ExtendedJoi.objectId().required(),
9});
10
11// Create a MongoDB ObjectId instance
12const objectId = new ObjectId("507f191e810c19729de860ea");
13
14// Validate the ObjectId instance
15const result = schema.validate({ id: objectId });
16// result.error is undefined (validation passes)

Using with Mongoose

1import Joi from "joi";
2import mongoose from "mongoose";
3import { extendJoiWithObjectId } from "joi-objectid-ext";
4
5const ExtendedJoi = extendJoiWithObjectId(Joi);
6
7const schema = ExtendedJoi.object({
8  id: ExtendedJoi.objectId().required(),
9});
10
11// Create a Mongoose ObjectId
12const objectId = new mongoose.Types.ObjectId("507f191e810c19729de860ea");
13
14// Validate the Mongoose ObjectId
15const result = schema.validate({ id: objectId });
16// result.error is undefined (validation passes)

Using with BSON package

1import Joi from "joi";
2import { ObjectId } from "bson";
3import { extendJoiWithObjectId } from "joi-objectid-ext";
4
5const ExtendedJoi = extendJoiWithObjectId(Joi);
6
7const schema = ExtendedJoi.object({
8  id: ExtendedJoi.objectId().required(),
9});
10
11// Create a BSON ObjectId
12const objectId = new ObjectId("507f191e810c19729de860ea");
13
14// Validate the BSON ObjectId
15const result = schema.validate({ id: objectId });
16// result.error is undefined (validation passes)

API

extendJoiWithObjectId(joi)

Extends a Joi instance with the ObjectId extension.

Parameters:

• joi: Joi module to extend

Returns: Extended Joi with ObjectId validation support

Joi.objectId()

Creates a Joi schema that validates ObjectIds.

• Validates strings of exactly 24 hex characters
• Works with MongoDB ObjectId instances, Mongoose ObjectIds, and BSON package ObjectIds

Compatibility

• Works with Joi v17+
• Compatible with Node.js 12+
• TypeScript 4.0+

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.