mongoose-tsgen

mongoose-tsgen

An plug-n-play Typescript interface generator for Mongoose.

• Features
• Compatibility
• Installation
• Usage
• Example
• Development

Features

• Automatically generate an index.d.ts file containing Typescript interfaces for each Mongoose document, model and subdocument
• Works out of the box, don't need to rewrite your schemas
• Add custom interfaces to augment generated interfaces
• Includes a "Mongoose-less" version of each interface (Mongoose typings removed)

Compatibility

• All Mongoose types and arrays
• Virtual properties
• Both Typescript and Javascript schema files
• Typescript path aliases
• Mongoose method, static & query functions
• Typesafe document creation with Model.Create
• Setting subdocument arrays without casting to any (currently you need to do user.friends = [{ uid, name }] as any or you can initialize the subdocument prior to setting it).

Installation

$ npm install -D mongoose-tsgen
$ npx mtgen --help # print usage

Usage

mtgen [ROOT_PATH]

Generate an index.d.ts file containing Mongoose Schema interfaces.

USAGE
  $ mtgen [ROOT_PATH - default = "."]

OPTIONS
  -d, --dry-run          print output rather than writing to file
  -h, --help             show CLI help
  -j, --js               search for Mongoose schemas in Javascript files rather than in Typescript files
  -o, --output=output    [default: ./src/types/mongoose] path of output index.d.ts file
  -p, --project=project  [default: ./] path of tsconfig.json or its root folder
  --no-format            disable formatting generated files with prettier and fixing with eslint
  --no-func-types        disable using TS compiler API for method, static and query typings

All sub-directories of ROOT_PATH will be searched for models/*.ts files (or models/*.js). Files in this folder (other than an index file) are expected to export a Mongoose model.

NOTE: --output requires a folder path or a file path ending in index.d.ts. If the path does not exist, it will be created.

See code: src/index.ts

Example

./src/models/user.ts

// NOTE: you will need to import these types after your first ever run of the CLI
// See the 'Initializing Schemas' section
import mongoose, { UserDocument, UserModel, UserQueries } from "mongoose";
const { Schema } = mongoose;

const UserSchema = new Schema({
  email: {
    type: String,
    required: true
  },
  firstName: {
    type: String,
    required: true
  },
  lastName: {
    type: String,
    required: true
  },
  metadata: Schema.Types.Mixed,
  friends: [
    {
      uid: {
        type: Schema.Types.ObjectId,
        ref: "User",
        required: true
      },
      nickname: String
    }
  ],
  city: {
    coordinates: {
      type: [Number],
      index: "2dsphere"
    }
  }
});

// NOTE: `this: UserDocument` and `this: UserModel` is 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}`;
});

// method functions
UserSchema.methods = {
  isMetadataString(this: UserDocument) {
    return typeof this.metadata === "string";
  }
};

// static functions
UserSchema.statics = {
  // friendUids could also use the type `ObjectId[]` here
  async getFriends(this: UserModel, friendUids: UserDocument["_id"][]) {
    return await this.aggregate([{ $match: { _id: { $in: friendUids } } }]);
  }
};

// query functions - no `this: UserDocument` required here, just provide UserQueries type
const queryFuncs: UserQueries = {
  populateFriends() {
    return this.populate("friends.uid", "firstName lastName");
  }
};

UserSchema.query = queryFuncs;

export const User: UserModel = mongoose.model<UserDocument, UserModel>("User", UserSchema);
export default User;

generate interfaces

$ mtgen

generated interface file ./src/types/mongoose/index.d.ts

/* tslint:disable */
/* eslint-disable */

// ######################################## THIS FILE WAS GENERATED BY MONGOOSE-TSGEN ######################################## //

// NOTE: ANY CHANGES MADE WILL BE OVERWRITTEN ON SUBSEQUENT EXECUTIONS OF MONGOOSE-TSGEN.
// TO ADD CUSTOM INTERFACES, DEFINE THEM IN THE `custom.d.ts` FILE.

import mongoose from "mongoose";

declare module "mongoose" {
  interface UserFriend {
    uid: User["_id"] | User;
    nickname?: string;
    _id: mongoose.Types.ObjectId;
  }

  interface UserQueries {
    populateFriends<Q extends mongoose.DocumentQuery<any, UserDocument, {}>>(
      this: Q,
      ...args: any[]
    ): Q;
  }

  interface UserModel extends Model<UserDocument, UserQueries> {
    getFriends: (this: any, friendUids: UserDocument["_id"][]) => Promise<any>;
  }

  interface User {
    email: string;
    firstName: string;
    lastName: string;
    friends: UserFriend[];
    city: {
      coordinates?: number[];
    };
    _id: mongoose.Types.ObjectId;
  }

  type UserFriendDocument = mongoose.Types.Subdocument & {
    uid: UserDocument["_id"] | UserDocument;
  } & UserFriend;

  type UserDocument = mongoose.Document & {
    metadata?: any;
    friends: mongoose.Types.DocumentArray<UserFriendDocument>;
    city: {};
    name: any;
    isMetadataString: (this: any) => boolean;
  } & User;
}

Initializing Schemas

Once you've generated your index.d.ts file, all you need to do is add the following types to your schema definitions:

user.ts before:

import mongoose from "mongoose";

const UserSchema = new Schema(...);

export const User = mongoose.model("User", UserSchema);
export default User;

user.ts after:

import mongoose, { UserDocument, UserModel } from "mongoose";

const UserSchema = new Schema(...);

export const User: UserModel = mongoose.model<UserDocument, UserModel>("User", UserSchema);
export default User;

Then you can import the interfaces across your application from the Mongoose module and use them for document types:

// import interface from mongoose module
import { UserDocument } from "mongoose";

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();
}

Development

• The generating piece of src/helpers/parser.ts needs to be rewritten using ts-morph. Currently it builds the interfaces by appending generated lines of code to a string sequentially, with no knowledge of the AST. This leads to pretty confusing logic, using the TS compiler API would simplify it a ton.
• Query function parameters are typed using a rest parameter (...args: any[]), this needs to be fine tunned to use the actual parameters and types.
• Top-level schema fields that refer to the schema itself (i.e. an array of User friend IDs at the root of the User schema) will be typed as the barebones Mongoose-less Schema interface, rather than the Document type (in example above, would refer to User instead of UserDocument). This is because the Document type is a TS type, rather than an interface, thus it cannot reference itself. This edge-case only really arises to users if they populate that specific property, otherwise this would references an ObjectId in both cases.
• Generating types for specifically the method and static functions objects. This is how query functions are currently handled, it removes the need to fill in the "fake this" parameter for each function.