Nitrogenous Polymorphic Molecule

    ts-mongoose
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.24 • Public • Published

    ts-mongoose

    Automatically infer TypeScript interfaces from mongoose schemas.

    Build Status npm module

    Installation

    npm i ts-mongoose mongoose @types/mongoose
    yarn add ts-mongoose mongoose @types/mongoose

    The Problem

    When using mongoose and Typescript, you must define schemas and interfaces. Both definitions must be maintained separately and must match each other. It can be error-prone during development and cause overhead.

    ts-mongoose is a very lightweight library that allows you to create a mongoose schema and a typescript type from a common definition.
    All types as created from 1-liner functions and does not depend on decorators❗️.

    For example:
    Type.string({ required: true }) returns {type: String, required: true}, which is the same definition required in the original mongoose library.

    Example

    Before:

    import { Schema, model, Model, Document } from 'mongoose';
     
    const AddressSchema = new Schema(
      {
        city: { type: String, required: true },
        country: String,
        zip: String,
      },
      { _id: false, timestamps: true }
    );
     
    const PhoneSchema = new Schema({
      phoneNumber: { type: Schema.Types.Number, required: true },
      name: String,
    });
     
    const UserSchema = new Schema(
      {
        title: { type: String, required: true },
        author: { type: String, required: true },
        body: { type: String, required: true },
        comments: [
          {
            body: { type: String, required: true },
            date: { type: Date, required: true },
          },
        ],
        date: { type: Date, default: Date.now, required: true },
        hidden: { type: Boolean, required: true },
        meta: {
          votes: { type: Schema.Types.Number },
          favs: { type: Schema.Types.Number },
        },
        m: {
          type: Schema.Types.Mixed,
          required: true,
        },
        gender: {
          type: Schema.Types.String,
          required: true,
          enum: ['male', 'female'],
        },
        otherId: {
          type: Schema.Types.ObjectId,
          required: true,
        },
        address: {
          type: AddressSchema,
          required: true,
        },
        phones: {
          type: [PhoneSchema],
          required: true,
        },
      },
      { timestamps: { createdAt: true } }
    );
     
    interface UserProps extends Document {
      title: string;
      author: string;
      body: string;
      // Duplicate all props from the above schema :(
    }
     
    const User: Model<UserProps> = model('User', UserSchema);

    🎉🎉🎉 After:

    import { createSchema, Type, typedModel } from 'ts-mongoose';
     
    const genders = ['male', 'female'] as const;
     
    const AddressSchema = createSchema(
      {
        city: Type.string({ required: true }),
        country: Type.string(),
        zip: Type.string(),
      },
      { _id: false, timestamps: true }
    );
     
    const PhoneSchema = createSchema({
      phoneNumber: Type.number({ required: true }),
      name: Type.string(),
    });
     
    const UserSchema = createSchema(
      {
        title: Type.string({ required: true }),
        author: Type.string({ required: true }),
        body: Type.string({ required: true }),
        comments: Type.array().of({
          body: Type.string({ required: true }),
          date: Type.date({ required: true }),
        }),
        date: Type.date({ default: Date.now as any }),
        hidden: Type.boolean({ required: true }),
        meta: Type.object().of({
          votes: Type.number({ required: true }),
          favs: Type.number({ required: true }),
        }),
        m: Type.mixed({ required: true }),
        gender: Type.string({ required: true, enum: genders }),
        otherId: Type.objectId({ required: true }),
        address: Type.schema({ required: true }).of(AddressSchema),
        phones: Type.array({ required: true }).of(PhoneSchema),
      },
      { timestamps: { createdAt: true } }
    );
     
    const User = typedModel('User', UserSchema);
    User.findById('123').then(user => {
      if (user) {
        user. // autocomplete here
      }
    });

    API

    • Each type has two forms: required and optional
    {
      // same as {type: String}
      firstNameType.string(),
      // same as {type: String, required: true}
      emailType.string({ required: true }),
    }
    • Each type accepts the same options from mongoose
    {
      // same as {type: String, required: true, unique: true, index: true}
      emailType.string({ required: true, unique: true, index: true });
    }
    • Note that enum values need to be readonly array to be treated as literals by typescript
    const genders = ['male', 'female'] as const;
    {
      // same as {type: String, enum: ['male', 'female']}
      genderType.string({ enum: genders });
    }
    • schema, object, array types have a method of where you must provide a child type
    {
      // same as {type: [String], required: true}
      tagsType.array({ required: true }).of(Type.string({ required: true }));
    }
    • schema.of(ExampleSchema) has typical for Subdocument additional fields and methods. Setting { _id: false } in SchemaOptions won't attach _id property in Subdocument
    const AddressSchema = createSchema(
      { city: Type.string({ required: true }) },
      { _id: false, timestamps: true }
    );
    {
      // same as {type: AddressSchema}
      addressType.schema().of(AddressSchema);
    }
    // address property has city property, other Subdocument methods and properties except '_id'
    • array.of(ExampleSchema) will return DocumentArray instead of standard array
    const PhoneSchema = createSchema(
      { phoneNumber: Type.number({ required: true }) },
      { _id: false }
    );
    {
      // same as {type: [PhoneSchema]}
      phonesType.array().of(PhoneSchema);
    }
    // phones property has such methods as create(), id(), but also those typical for arrays like map(), filter() etc
    • ref is a special type for creating references
    {
      // same as [{type: Schema.Types.ObjectId, ref: 'Comment'}]
      commentsType.array().of(
        Type.ref(Type.objectId()).to('Comment', CommentSchema)
      ),
    }
    • populateTs(property: string) use this function to populate a property and adjust the returned type automatically. Under the hood it calls only the native populate method.
      Method will be available if you import a special plugin.
    // models.ts
     
    import 'ts-mongoose/plugin';
     
    User.find().populateTs('comments');

    Extracting Document type

    Use ExtractDoc to extract generated document type.
    Use ExtractProps to extract generated base model properties.
    Example:

    import {
      createSchema,
      Type,
      typedModel,
      ExtractDoc,
      ExtractProps,
    } from 'ts-mongoose';
     
    export const UserSchema = createSchema({
      email: Type.string({ required: true }),
      username: Type.string({ required: true }),
      isBlocked: Type.boolean(),
    });
     
    export const User = typedModel('User', UserSchema);
    export type UserDoc = ExtractDoc<typeof UserSchema>;
    export type UserProps = ExtractProps<typeof UserSchema>;
     
    // example function
     
    async function blockUser(user: UserDoc) {
      user.isBlocked = true;
      // access all properties + Document methods and properties
      await user.save();
    }
     
    function randomUser(): UserProps {
      // must return `email`, `username`
      // `isBlocked` is optional
      return {
        email: 'user1@example.com',
        username: 'user1',
      };
    }

    Refs

    Refs and populations are supported.
    Check code under example/example4.ts.

    alt autocomplete

    Custom Field

    If you need to specify custom fields in the model, you can add a fake annotation.
    It's only required if you add virtual fields or custom methods to the model.

    const UserSchema = createSchema({
      title: Type.string({ required: true }),
      author: Type.string({ required: true }),
      ...({} as {
        generatedField: string;
        customFunction: () => number;
      }),
    });
    const User = typedModel('User', UserSchema);

    Autocomplete popup:
    alt autocomplete

    Static methods

    If you need to have static custom methods on Model you can pass them as 5th parameter of typedModel function. It should automatically figured out returning value, but you can declare it too.

    const UserSchema = createSchema({
      name: Type.string({ required: true }),
      age: Type.number({ required: true }),
    });
     
    const User = typedModel('User', UserSchema, undefined, undefined, {
      findByName: function(name: string) {
        return this.find({ name });
      },
      findOneByName: function(name: string) {
        return this.findOne({ name });
      },
      countLetters: function(name: string, bonus?: number) {
        return name.length + (bonus ? bonus : 0);
      },
    });
    const u = await User.findOne({});
    if (u) u.name;

    Connection model

    If you are using mongoose.createConnection(...), you can pass a <mongoose.Connection> as the 6th parameter of typedModel. Then the module will be added to that connection instead.
    (Note: If using the connection parameter, the skipInit parameter will not be used)

    import mongoose from 'mongoose'
    import { typedModel } from 'ts-mongoose'
     
    const UserSchema = createSchema({
      name: Type.string({ required: true }),
      age: Type.number({ required: true }),
    });
     
    const connection = mongoose.createConnection(`mongodb://localhost:27017/test`, {...})
     
    const User = typedModel('User', UserSchema, undefined, undefined, undefined, connection);
     
     
    console.log(connection.modelNames()) // Prints: [ 'User' ]
     
    // Now you can use the model directly
    User.find({ name: 'Peter' })
    // Or through the connection
    connection.model('User').find({ name: 'Peter' })
     

    TODO

    • support types: Map

    MIT

    Keywords

    none

    Install

    npm i ts-mongoose

    DownloadsWeekly Downloads

    61,750

    Version

    0.0.24

    License

    MIT

    Unpacked Size

    39.2 kB

    Total Files

    46

    Last publish

    Collaborators

    • lsentkiewicz
    • lchimaru