A Typescript interface generator for Mongoose that works out of the box.
npm install mongoose-tsgenA plug-n-play Typescript generator for Mongoose.
- Motivation
- Features
- Compatibility
- Installation
- The Gist
- Usage
- Example
- Known Issues
- Development
Using Mongoose with Typescript requires duplicating Mongoose Schemas using Typescript interfaces. To avoid duplication, libraries like typegoose define a custom schema syntax that is used to generate both the Mongoose Schemas and the Typescript interfaces. Unfortunately, this requires users to completely rewrite their Mongoose Schemas into an unfamiliar syntax and does not support the entire Mongoose feature set.
This library aims to remove these drawbacks by instead parsing your already-written Mongoose Schemas and generating associated Typescript interfaces. This removes the need to learn new syntax and makes this library extremely simple to integrate into an existing Mongoose project.
- 😌 Automatically generate Typescript typings for each Mongoose document, model and subdocument
- 📦 Works out of the box, don't need to rewrite your schemas
- ⛑ Type-safe population
- âž• Includes a "Mongoose-less" version of each schema interface (Mongoose typings removed)
- ✅ All Mongoose types, arrays and maps
- ✅ Virtual properties
- ✅ Mongoose method, static & query functions
- ✅ Multiple schemas per file
- ✅ Typescript path aliases
Find your Mongoose version below and install the associated mongoose-tsgen version. Ensure to refer to each version's respective README for documentation (hyperlinked in table).
| mongoose | mongoose-tsgen |
| -------------- | -------------- |
| 6.1.5+ | latest |
| 5.11.19-6.1.14 | 8.4.7 |
| 5.11.0-5.11.18 | 7.1.3 |
| <5.11.0 | 6.0.10 |
> Note: For Mongoose v6.3.2 - v6.4.0, see Known Issues first.
mongoose-tsgen can be installed globally or locally as a dev dependency. Refer to the table above to ensure you are using the correct version.
``bashinstall with npm or yarn
npm install -D mongoose-tsgen
The Gist
Once you've generated your typings file (see Usage), all you need to do is use the generated types in your schema definitions and throughout your project.
$3
typescript
import mongoose from "mongoose";const UserSchema = new Schema(...);
export const User = mongoose.model("User", UserSchema);
`$3
typescript
import mongoose from "mongoose";
import { UserDocument, UserModel, UserSchema } from "../interfaces/mongoose.gen.ts";const UserSchema: UserSchema = new Schema(...);
export const User: UserModel = mongoose.model("User", UserSchema);
`Then you can import the typings across your application from the Mongoose module and use them for document types:
typescript
import { UserDocument } from "./interfaces/mongoose.gen.ts";async function getUser(uid: string): UserDocument {
// user will be of type User
const user = await User.findById(uid);
return user;
}
async function editEmail(user: UserDocument, newEmail: string): UserDocument {
user.email = newEmail;
return await user.save();
}
`Note that this practice is well documented online, I've found the following two Medium articles especially useful:
- Complete guide for Typescript with Mongoose for Node.js
- Strongly typed models with Mongoose and TypeScript
Usage
Generate a Typescript file containing Mongoose Schema typings.
> If you run into unknown type issues, check your Mongoose version. For Mongoose v5.11+, ensure you have removed the deprecated community typings
.`
USAGE
$ mtgen [MODEL_PATH] [-c ] [-d] [-h] [-i ] [--no-format] [-o ] [-p ] [--debug]
[--no-mongoose] [--dates-as-strings] [--no-populate-overload] [--no-experimental-resolver]FLAGS
-c, --config= [default: ./] Path of
or its root folder. CLI flag options will
take precendence over settings in mtgen.config.json. -d, --dry-run Print output rather than writing to file.
-h, --help Show CLI help.
-i, --imports=... Custom import statements to add to the output file. Useful if you use third-party types
in your mongoose schema definitions. For multiple imports, specify this flag more than
once.
-o, --output= [default: ./src/interfaces] Path of output file to write generated typings. If a folder
path is passed, the generator will create a
mongoose.gen.ts file in the specified
folder. -p, --project= [default: ./] Path of
tsconfig.json or its root folder. --dates-as-strings Dates will be typed as strings. Useful for types returned to a frontend by API
requests.
--debug Print debug information if anything isn't working
--no-experimental-resolver Disable experimentalResolver for ts-node. This can resolve issues with external
modules.
--no-format Disable formatting generated files with prettier.
--no-mongoose Don't generate types that reference mongoose (i.e. documents). Replace ObjectId with
string.
--no-populate-overload Disable augmenting mongoose with Query.populate overloads (the overloads narrow the
return type of populated documents queries).
`Specify the directory of your Mongoose schema definitions using
. Defaults to "**/models/!(index).ts"_See code: src/index.ts_
Blob patterns and
Wrap blob patterns with double quotes like so:
.Use escape characters for wrapping blob patterns in
package.json:`json
"scripts": {
"generate-mongoose-types": "mtgen \"models/*/.ts\""
}
`
Configuration File
All CLI options can be provided using a
file. Use the --config option to provide the folder path containing this file ("./" will be searched if no path is provided). CLI options will take precendence over options in the mtgen.config.json file.> mtgen.config.json
`json
{
"imports": ["import Stripe from \"stripe\""],
"output": "./src/custom/path/mongoose-types.ts"
}
`Use as a module
can also be imported or required and used programmatically. Below is an example:`typescript
import MongooseTsgen from "mongoose-tsgen";async function run() {
const tsgen = new MongooseTsgen();
await tsgen.generateDefinitions({
flags: {
"dry-run": false,
"no-format": false,
"no-mongoose": false,
"no-populate-overload": false,
"dates-as-strings": false,
debug: false,
output: "./src/interfaces",
project: "./tsconfig.test.json"
},
args: {
model_path: "./src/helpers/tests/artifacts/*/.ts" // optional
}
});
}
run()
`Query Population
Mongoose fields with a
property will be typed as RefDocument["_id"] | RefDocument. As part of the generated file, mongoose will be augmented with Query.populate overloads to narrow return types of populated queries (this can be disabled using the --no-populate-overload flag). A helper type PopulatedDocument and a type guard function IsPopulated will also be generated to help with handling populated documents, see usage below:`typescript
import { IsPopulated, PopulatedDocument } from "../interfaces/mongoose.gen.ts";// UserDocument["bestFriend"] = mongoose.Types.ObjectId | UserDocument
function unsafeType(user: UserDocument) {
// type guard
if (IsPopulated(user.bestFriend))) {
// user.bestFriend is confirmed to be populated, typescript will allow accessing its properties now
console.log(user.bestFriend._id)
}
}
//
user is typed as a UserDocument with bestFriend populated
function safeType(user: PopulatedDocument) {
console.log(user.bestFriend._id)
}// due to the
Query.populate overload, user will be typed as PopulatedDocument
// rather than the usual
const user = await User.findById(uid).populate("bestFriend").exec()// completely type-safe
safeType(user)
Both the mongoose
overload and the PopulateDocument type handle nested and array types with ease; you rarely need to worry about enforcing types manually. In the case that the populated type cannot be determined, types will fallback to the generic RefDocument["_id"] | RefDocument.Example
$3
`typescript
import mongoose, { Schema } from "mongoose";
import { UserDocument, UserModel, UserSchema, UserObject } from "../interfaces/mongoose.gen.ts";// UserSchema type
const UserSchema: UserSchema = new Schema({
email: {
type: String,
required: true
},
firstName: {
type: String,
required: true
},
lastName: {
type: String,
required: true
},
metadata: Schema.Types.Mixed,
bestFriend: {
type: Schema.Types.ObjectId,
ref: "User"
},
friends: [
{
uid: {
type: Schema.Types.ObjectId,
ref: "User",
required: true
},
nickname: String
}
],
city: {
coordinates: {
type: [Number]
}
}
});
// NOTE:
this: UserDocument is required for virtual properties to tell TS the type of this value using the "fake this" feature
// you will need to add these in after your first ever run of the CLI
UserSchema.virtual("name").get(function (this: UserDocument) {
return ${this.firstName} ${this.lastName};
});UserSchema.methods = {
isMetadataString() {
return this.metadata === "string";
}
};
UserSchema.statics = {
async getFriends(friendUids: UserDocument["_id"][]): Promise {
return await this.aggregate([{ $match: { _id: { $in: friendUids } } }]);
}
};
UserSchema.query = {
populateFriends() {
return this.populate("bestFriend", "firstName lastName");
}
};
export const User = mongoose.model("User", UserSchema);
`$3
bash
run mongoose-tsgen
npx mtgen
`$3
typescript
import mongoose from "mongoose";export type UserFriend = {
uid: User["_id"] | User;
nickname?: string;
_id: mongoose.Types.ObjectId;
}
export type UserObject = User;
export type UserQueries = {
populateFriends: () => mongoose.Query & UserQueries;
}
export type UserMethods = {
isMetadataString: (this: UserDocument) => boolean;
}
export type UserStatics = {
getFriends: (this: UserModel, friendUids: UserDocument["_id"][]) => Promise;
}
export type UserModel = mongoose.Model & UserStatics
export type UserSchema = mongoose.Schema
export type User = {
email: string;
firstName: string;
lastName: string;
bestFriend?: User["_id"] | User;
friends: UserFriend[];
city: {
coordinates: number[];
};
_id: mongoose.Types.ObjectId;
}
export type UserFriendDocument = mongoose.Types.Subdocument & {
uid: UserDocument["_id"] | UserDocument;
nickname?: string;
_id: mongoose.Types.ObjectId;
};
export type UserDocument = mongoose.Document &
UserMethods & {
email: string;
firstName: string;
lastName: string;
metadata?: any;
bestFriend?: UserDocument["_id"] | UserDocument;
friends: mongoose.Types.DocumentArray;
city: {
coordinates: mongoose.Types.Array;
};
name: string;
_id: mongoose.Types.ObjectId;
};
`Known Issues
$3
This issue is present when using Mongoose v6.3.2 - v6.4.0 due to a conflict in types.
Workarounds:
- Fix your Mongoose version to
or >6.4.0.
- Use the --no-populate-overload flag.References:
- https://github.com/Automattic/mongoose/issues/11787
- https://github.com/francescov1/mongoose-tsgen/issues/95
Development
- [ ] Consider population field selection when typing populates
- [ ] Slim down dependencies:
oclif is unnecessarily large, prettier` should be handled by users if desired.