Typegoose

Define Mongoose models using TypeScript classes

ORMMongoDB
typegoose/typegoosetypegoose.github.io/typegoose/@typegoose/typegoose

README

Typegoose


(These badges are from typegoose:master) [![Node.js Tests](https://github.com/typegoose/typegoose/workflows/Node.js%20Tests/badge.svg?branch=master)](https://github.com/typegoose/typegoose/actions?query=workflow%3A"Node.js+Tests") [![codecov.io](https://codecov.io/github/typegoose/typegoose/coverage.svg?branch=master)](https://codecov.io/github/typegoose/typegoose?branch=master) [![npm](https://img.shields.io/npm/dt/@typegoose/typegoose.svg)](https://www.npmjs.com/package/@typegoose/typegoose)

Define Mongoose models using TypeScript classes

Migration


Migration Guides:  
(Date format: dd-mm-yyyy)

- 8 to 9 (released on22-09-2021)
- 7 to 8 (released on28-07-2021)
- 6 to 7 (released on01-04-2020)
- 5 to 6 (released on30-09-2019)

Basic usage


  1. ```ts
  2. import { prop, getModelForClass } from '@typegoose/typegoose';
  3. import * as mongoose from 'mongoose';

  5. class User {
  6.   @prop()
  7.   public name?: string;

  9.   @prop({ type: () => [String] })
  10.   public jobs?: string[];
  11. }

  13. const UserModel = getModelForClass(User); // UserModel is a regular Mongoose Model with correct types

  15. (async () => {
  16.   await mongoose.connect('mongodb://localhost:27017/', { useNewUrlParser: true, useUnifiedTopology: true, dbName: 'test' });

  18.   const { _id: id } = await UserModel.create({ name: 'JohnDoe', jobs: ['Cleaner'] } as User); // an "as" assertion, to have types for all properties
  19.   const user = await UserModel.findById(id).exec();

  21.   console.log(user); // prints { _id: 59218f686409d670a97e53e0, name: 'JohnDoe', __v: 0 }
  22. })();
  23. ```

Motivation


A common problem when using Mongoose with TypeScript is that you have to define both the Mongoose model and the TypeScript interface. If the model changes, you also have to keep the TypeScript interface file in sync or the TypeScript interface would not represent the real data structure of the model.

Typegoose aims to solve this problem by defining only a TypeScript interface (class), which needs to be enhanced with special Typegoose decorators (like @prop).

Under the hood it uses the Reflect & reflect-metadata API to retrieve the types of the properties, so redundancy can be significantly reduced.

Instead of writing this:

  1. ```ts
  2. // This is a representation of how typegoose's compile output would look like
  3. interface Car {
  4.   model?: string;
  5. }

  7. interface Job {
  8.   title?: string;
  9.   position?: string;
  10. }

  12. interface User {
  13.   name?: string;
  14.   age!: number;
  15.   preferences?: string[];
  16.   mainJob?: Job;
  17.   jobs?: Job[];
  18.   mainCar?: Car | string;
  19.   cars?: (Car | string)[];
  20. }

  22. const JobSchema = new mongoose.Schema({
  23.   title: String;
  24.   position: String;
  25. });

  27. const CarModel = mongoose.model('Car', {
  28.   model: string,
  29. });

  31. const UserModel = mongoose.model('User', {
  32.   name: { type: String },
  33.   age: { type: Number, required: true },
  34.   preferences: [{ type: String }],
  35.   mainJob: { type: JobSchema },
  36.   jobs: [{ type: JobSchema }],
  37.   mainCar: { type: Schema.Types.ObjectId, ref: 'Car' },
  38.   cars: [{ type: Schema.Types.ObjectId, ref: 'Car' }],
  39. });
  40. ```

You can just write this:

  1. ```ts
  2. class Job {
  3.   @prop()
  4.   public title?: string;

  6.   @prop()
  7.   public position?: string;
  8. }

  10. class Car {
  11.   @prop()
  12.   public model?: string;
  13. }

  15. class User {
  16.   @prop()
  17.   public name?: string;

  19.   @prop({ required: true })
  20.   public age!: number; // This is a single Primitive

  22.   @prop({ type: () => [String] })
  23.   public preferences?: string[]; // This is a Primitive Array

  25.   @prop()
  26.   public mainJob?: Job; // This is a single SubDocument

  28.   @prop({ type: () => Job })
  29.   public jobs?: Job[]; // This is a SubDocument Array

  31.   @prop({ ref: () => Car })
  32.   public mainCar?: Ref<Car>; // This is a single Reference

  34.   @prop({ ref: () => Car })
  35.   public cars?: Ref<Car>[]; // This is a Reference Array
  36. }
  37. ```

Extra Examples


Requirements & Install


Typegoose's Quick Start Guide

Testing


  1. ```sh
  2. yarn install
  3. yarn run test
  4. ```

Versioning


This Project should comply with Semver. It uses theMajor.Minor.Fix standard (or in NPM terms, Major.Minor.Patch).

Join Our Discord Server


To ask questions or just talk with us, join our Discord Server.

Documentation


Typegoose Documentation
Quick start guide

Known Issues


Here are the known-issues

FAQ


Here is the FAQ

Notes


Please don't add +1 or similar comments to issues. Use the reactions instead.