npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@reflet/mongoose

v2.0.0

Published

Well-defined and well-typed mongoose decorators

Downloads

1,893

Readme

@reflet/mongoose 🌠

lines coverage statements coverage functions coverage branches coverage

[!IMPORTANT]
Upgrade from v1 to v2 : Migration guide

The best decorators for Mongoose. Have a look at Reflet's philosophy.

Getting started

  1. Enable experimental decorators in TypeScript compiler options.No need to install "reflect-metadata".

    "experimentalDecorators": true,
  2. Install the package along with peer dependencies.

    npm i @reflet/mongoose mongoose
  3. Create your decorated models.

    // user.model.ts
    import { Model, Field } from '@reflet/mongoose'
    
    @Model()
    export class User extends Model.I {
      static findByEmail(email) {
        return this.findOne({ email });
      }
    
      @Fied({ type: String, required: true })
      email: string
    
      getProfileUrl() {
        return `https://mysite.com/${this.email}`;
      }
    }
  4. Connect to MongoDB and save your documents.

    // server.ts
    import 'reflect-metadata'
    import * as mongoose from 'mongoose'
    import { User } from './user.model.ts'
    
    mongoose.connect('mongodb://localhost/test', { useNewUrlParser: true })
    
    User.create({ email: '[email protected]' }).then((user) => {
      console.log(`User ${user._id} has been saved.`)
    })

The Mongoose way

Connect Mongoose in the way you already know. Models defined with Reflet will simply be attached to the default Mongoose connection. This means you can progressively decorate your Mongoose models. 😉

Schema definition

🔦 @Field(schemaType) 💫 Related Mongoose object: SchemaTypes

Mongoose already allows you to load an ES6 class to attach getters, setters, instance and static methods to a schema. But what about properties ? Enters the @Field decorator :

class User {
  @Field({ type: String, required: true })
  firstname: string

  @Field({ type: String, required: true })
  lastname: string

  @Field(Number)
  age?: number

  get fullname() {
    return `${this.firstname} ${this.lastname}`
  }
}

The @Field API is a direct wrapper of Mongoose SchemaType, you can put in there everything that you used to.

Nested properties

🔦 @Field.Nested(schemaTypes)

class User {
  @Field.Nested({
    street: { type: String, required: true },
    city: { type: String, required: true },
    country: { type: String, required: true },
  })
  address: {
    street: string
    city: string
    country: string
  }
}

@Field.Nested works the same as @Field at runtime. Its type is simply looser to allow nested objects.

Model

🔦 @Model(collection?, connection?) 💫 Related Mongoose method: model

TypeScript class decorators can modify and even replace class constructors. Reflet takes advantage of this feature and transforms a class directly into a Mongoose Model.

This means you don't have to deal with the procedural and separate creation of both schema and model anymore ! And now your properties and methods are statically typed.

@Model()
class User extends Model.Interface {
  @Field({ type: String, required: true })
  email: string
}

const user = await User.create({
  email: '[email protected] '
})



interface UserDocument extends mongoose.Document {
  email: string
}

const userSchema = new mongoose.Schema({
  email: { type: String, required: true }
})

const User = mongoose.model<UserDocument>('User', userSchema)

const user = await User.create({
  email: '[email protected] '
})

⚠️ @Model should always be at the top of your class decorators. Why? Because decorators are executed bottom to top, so if @Model directly compiles your class into a Mongooose Model, other class decorators won't be properly applied. Reflet will warn you with its own decorators.

Correct model and document interface

Your class needs to inherit a special empty class, Model.Interface or Model.I, to have Mongoose document properties and methods.

Custom collection name

By default, Mongoose automatically creates a collection named as the plural, lowercased version of your model name. You can customize the collection name, with the first argument:

@Model('people')
class User extends Model.I {
  @Field({ type: String, required: true })
  email: string
}

Custom Mongoose connection

You can use a different database by creating a Mongoose connection and passing it as the second argument:

const otherDb = mongoose.createConnection('mongodb://localhost/other', { useNewUrlParser: true })

@Model(undefined, otherDb)
class User extends Model.I {
  @Field({ type: String, required: true })
  email: string
}

Schema options

🔦 @SchemaOptions(options) 💫 Related Mongoose object: Schema options

@Model()
@SchemaOptions({
  autoIndex: false,
  strict: 'throw'
})
class User extends Model.I {           
  @Field(String)
  name: string
}



interface UserDocument extends mongoose.Document {
  name: string
}

const userSchema = new mongoose.Schema(
  { name: String },
  {
    autoIndex: false,
    strict: 'throw'
  }
)

const User = mongoose.model<UserDocument>('User', userSchema)

The @SchemaOptions API is a direct wrapper of Mongoose schema options, you can put in there everything that you used to.

Timestamps

🔦 @CreatedAt, @UpdatedAt 💫 Related Mongoose option property: timestamps

@Model()
@SchemaOptions({ minimize: false })
class User extends Model.I {             
  @Field(String)
  name: string

  @CreatedAt
  creationDate: Date

  @UpdatedAt
  updateDate: Date
}





interface UserDocument extends mongoose.Document {
  name: string
  creationDate: Date
  updateDate: Date
}

const userSchema = new mongoose.Schema(
  { name: String },
  {
    minimize: false,
    timestamps: {
      createdAt: 'creationDate',
      updatedAt: 'updateDate'
    },
  }
)

const User = mongoose.model<UserDocument>('User', userSchema)

Advanced schema manipulation

🔦 @SchemaCallback(callback) 💫 Related Mongoose object: Schema

If you need more advanced schema manipulation before @Model compiles it, you can use @SchemaCallback:

@Model()
@SchemaCallback((schema) => {
  schema.index({ name: 1, type: -1 })
})
class Animal extends Model.I {          
  @Field(String)
  name: string

  @Field(String)
  type: string
}

interface AnimalDocument extends mongoose.Document {
  name: string
  type: string
}

const userSchema = new mongoose.Schema({
  name: String,
  type: String
})

userSchema.index({ name: 1, type: -1 })

const Animal = mongoose.model<AnimalDocument>('Animal', userSchema)

Beware of defining hooks in the callback if your schema has embedded discriminators. Mongoose documentation recommends declaring hooks before embedded discriminators, the callback is applied after them. You should use the dedicated hooks decorators @PreHook and @PostHook.

Schema retrieval

🔦 schemaFrom(class)

You can retrieve a schema from any decorated class, for advanced manipulation or embedded use in another schema.

@SchemaOptions({ _id: false })
abstract class Location {
  @Field(Number)
  lat: number

  @Field(Number)
  lng: number
}

@Model()
class City extends Model.I {            
  @Field(String)
  name: string

  @Field(schemaFrom(Location))
  location: Location
}

const citySchema = schemaFrom(City)
interface CityDocument extends mongoose.Document {
  name: string
  location: {
    lat: number,
    lng: number
  }
}

const locationSchema = new mongoose.Schema(
  { lat: Number, lng: Number },
  { _id: false }
)

const citySchema = new mongoose.Schema({
  name: String,
  location: locationSchema
})

const City = mongoose.model<CityDocument>('City', citySchema)

🗣️ As a good practice, you should make your schema-only classes abstract, so you don't instantiate them by mistake.

Sub schemas

🔦 Field.Schema(class)

As an alternative for the above use of schemaFrom inside the Field decorator, you can do:

@Model()
class City extends Model.I {            
  @Field.Schema(Location)
  location: Location
}

Hooks

Pre hook

🔦 @PreHook(method, callback) 💫 Related Mongoose method: schema.pre

@Model()
@PreHook<User>('save', function(next) {
  next()
})
class User extends Model.I {     
  @Field(String)
  name: string
}


interface UserDocument extends mongoose.Document {
  name: string
}

const userSchema = new mongoose.Schema({ name: String })

userSchema.pre<UserDocument>('save', function (doc, next) {
  next()
})

const User = mongoose.model<UserDocument>('User', userSchema)

The @PreHook API is a direct wrapper of Mongoose Schema.pre method, you can put in there everything that you used to.

Successive @PreHook will be applied in the order they are written, even though decorator functions in JS are executed in a bottom-up way (due to their wrapping nature).

Post hook

🔦 @PostHook(method, callback) 💫 Related Mongoose method: schema.post

@Model()
@PostHook<User>('find', function(result) {
  console.log(result)
})
class User extends Model.I {     
  @Field(String)
  name: string
}


interface UserDocument extends mongoose.Document {
  name: string
}

const userSchema = new mongoose.Schema({ name: String })

userSchema.post<UserDocument>('find', function (result) {
  console.log(result)
})

const User = mongoose.model<UserDocument>('User', userSchema)

The @PostHook API is a direct wrapper of Mongoose Schema.post method, you can put in there everything that you used to.

Successive @PostHook will be applied in the order they are written, even though decorator functions in JS are executed in a bottom-up way (due to their wrapping nature).

Post error handling middleware

To help the compiler accurately infer the error handling middleware signature, pass a second type argument to @PostHook:

@Model()
@PostHook<User, Error>('save', function(error, doc, next) {
  if (error.name === 'MongoError' && error.code === 11000) {
    next(new Error('There was a duplicate key error'))
  } else {
    next()
  }
})
class User extends Model.I {
  @Field(String)
  name: string
}

Model discriminators

🔦 @Model.Discriminator(rootModel) 💫 Related Mongoose method: model.discriminator

@Model()
class User extends Model.I {
  @Field(String)
  name: string
}

@Model.Discriminator(User)
class Worker extends User {
  @Field(String)
  job: string

  // No need to decorate the default discriminatorKey.
  __t: 'Worker'

  // You can strictly type the constructor of a discriminator model by using the Plain Helper (see below).
  constructor(worker: Plain.Omit<Worker, '_id' | '__t'>) {
    super() // required by the compiler.
  }
}

const worker = await Worker.create({ name: 'Jeremy', job: 'developer' })
// { _id: '5d023ae14043262bcfd9b384', __t: 'Worker', name: 'Jeremy', job: 'developer' }

As you know, _t is the default discriminatorKey, and its value will be the class name. If you want to customize both the key and the value, check out the following @Kind decorator.

⚠️ @Model.Discriminator should always be at the top of your class decorators. Why? Because decorators are executed bottom to top, so if @Model.Discriminator directly compiles your class into a Mongooose Model, other class decorators won't be properly applied. Reflet will warn you with its own decorators.

Kind / DiscriminatorKey

🔦 @Kind(value?) alias @DiscriminatorKey 💫 Related Mongoose option property: discriminatorKey

Mongoose discriminatorKey is usually defined in the parent model options, and appears in the children model documents. @Kind (or its alias @DiscriminatorKey) exists to define discriminatorKey directly on the children class instead of the parent model.

@Model()
class User extends Model.I {
  @Field(String)
  name: string
}

@Model.Discriminator(User)
class Developer extends User {
  @Kind
  kind: 'Developer' // Value will be the class name by default.
}

@Model.Discriminator(User)
class Doctor extends User {
  @Kind('doctor') // Customize the discriminator value by passing a string.
  kind: 'doctor'
}

// This is equivalent to setting `{ discriminatorKey: 'kind' }` on User schema options.

A mecanism will check and prevent you from defining a different @Kind key on sibling discriminators.

Embedded discriminators

Single nested discriminators

🔦 @Field.Union(classes[], options?) 💫 Related Mongoose method: SingleNestedPath.discriminator

@Field.Union allows you to embed discriminators on an single property.

abstract class Circle {
  @Field(Number)
  radius: number

  __t: 'Circle'
  // __t is the default discriminatorKey (no need to decorate).
  // Value will be the class name.
}

abstract class Square {
  @Field(Number)
  side: number

  __t: 'Square'
}

@Model()
class Shape extends Model.I {
  @Field.Union([Circle, Square], { 
    required: true, // Make the field itself `shape` required.
    strict: true // Make the discriminator key `__t` required and narrowed to its possible values.
  })
  shape: Circle | Square
}

const circle = new Shape({ shape: { __t: 'Circle', radius: 5 } })
const square = new Shape({ shape: { __t: 'Square', side: 4 } })

Embedded discriminators in arrays

🔦 @Field.ArrayOfUnion(classes[], options?) 💫 Related Mongoose method: DocumentArrayPath.discriminator

@Field.ArrayOfUnion allows you to embed discriminators in an array.

@SchemaOptions({ _id: false })
abstract class Clicked {
  @Field({ type: String, required: true })
  message: string

  @Field({ type: String, required: true })
  element: string

  @Kind
  kind: 'Clicked'
}

@SchemaOptions({ _id: false })
abstract class Purchased {
  @Field({ type: String, required: true })
  message: string

  @Field({ type: String, required: true })
  product: string

  @Kind
  kind: 'Purchased'
}

@Model()
class Batch extends Model.I {
  @Field.ArrayOfUnion([Clicked, Purchased], { 
    strict: true  // Make the discriminator key `kind` required and narrowed to its possible values.
  })
  events: (Clicked | Purchased)[]
}

const batch = new Batch({
  events: [
    { kind: 'Clicked', element: '#hero', message: 'hello' },
    { kind: 'Purchased', product: 'action-figure', message: 'world' },
  ]
})

Virtuals

🔦 @Virtual 💫 Related Mongoose method: schema.virtual

@Virtual helps you define a writable virtual property (both a getter and a setter), which is properly serialized with toJson: { virtuals: true }, and not saved to the database.Can be used with or without invokation.

@Model()
@SchemaOptions({ 
  toObject: { virtuals: true },
  toJson: { virtuals: true }
})
class S3File extends Model.I {
  @Field(String)
  key: string

  @Virtual
  url: string
}

const photo = await S3File.findOne({ key })
photo.url = await getSignedUrl(photo.key)
res.send(photo)

Populated virtuals

🔦 @Virtual.Populate(options) 💫 Related Mongoose method: schema.virtual

@Virtual.Populate helps you define populate virtuals.

@Model()
class Person extends Model.I {
  @Field(String)
  name: string

  @Field(String)
  band: string
}

@Model()
@SchemaOptions({
  toObject: { virtuals: true },
  toJson: { virtuals: true }
})
class Band extends Model.I {
  @Field(String)
  name: string

  @Virtual.Populate<Band, Person>({
    ref: 'Person',
    foreignField: 'band',
    localField: 'name'
  })
  readonly members: string[]
}

const bands = await Band.find({}).populate('members')

Plain helper

🔦 Plain<class, options?>

Reflet provides a generic type to discard Mongoose properties and methods from a Document.

  • Plain<T> removes inherited Mongoose properties (except _id) and all methods from T.
  • Plain.Partial<T> does the same as Plain and makes remaining properties of T optional.
  • Plain.PartialDeep<T> does the same as Plain.Partial recursively.

Plain also has a second type argument to omit other properties and/or make them optional:

  • Plain<T, { Omit: keyof T; Optional: keyof T } >

These options exist as standalone generics as well: Plain.Omit<T, keyof T> and Plain.Optional<T, keyof T>.

With this you can narrow the return type of toObject() and toJson():

const userPlain = user.toObject({ getters: false }) as Plain.Omit<User, 'fullname'>

Allow string for ObjectId

🔦 Plain.AllowString<class, options?>

When creating or querying documents, you can pass ObjectId as string. To allow this, Reflet provides a generic type with the same API as Plain:

  • Plain.AllowString<T, { Omit: keyof T; Optional: keyof T } >
  • Plain.AllowString.Partial<T>
  • Plain.AllowString.PartialDeep<T>

One document, multiple shapes

In each of your models, some fields might be present when you read the document from the database, but optional or even absent when you create it. 😕

Given the following model:

@Model()
class User extends Model.I {
  @Field({ type: String, required: true })
  firstname: string

  @Field({ type: String, required: true })
  lastname: string

  @Field({ type: Boolean, default: () => false })
  activated: boolean

  @CreatedAt
  createdAt: Date

  get fullname() {
    return `${this.firstname} ${this.lastname}`
  }
}

This is how you can type constructor and create parameters:

type NewUser = Plain.AllowString<User, { Omit: 'fullname' | 'createdAt'; Optional: '_id' | 'activated' }>

@Model()
class User extends Model.I<typeof User>  {
  // @ts-ignore implementation
  constructor(doc?: NewUser, strict?: boolean | 'throw')
}

const user = new User({ firstname: 'John', lastname: 'Doe' })
await user.save()
await User.create({ firstname: 'Jeremy', lastname: 'Doe', activated: true })

By passing typeof User to Model.I, Reflet is now able to use the constructor signature to type the following static methods: create, insertMany and replaceOne.

The compiler checks NewUser as we need, so you can safely use ts-ignore on the constructor to avoid implementing an empty one (remember that @Model will replace it with mongoose Model constructor).

Augmentations

Reflet comes with a dedicated global namespace RefletMongoose, so you can augment or narrow specific types.

SchemaType options augmentation

If you use plugins like mongoose-autopopulate, you can augment the global interface SchemaTypeOptions to have new options in the @Field API.

declare global {
  namespace RefletMongoose {
    interface SchemaTypeOptions {
      autopopulate?: boolean
    }
  }
}

Now you have access to autopopulate option in your schemas:

@Model()
class User extends Model.I {
  @Field({
    type: mongoose.Schema.Types.ObjectId,
    ref: Company,
    autopopulate: true
  })
  company: Company
}

Virtual options

The same can be done with the @Virtual decorator:

declare global {
  namespace RefletMongoose {
    interface VirtualOptions {}
  }
}

Model and Document augmentation

You can augment Model and Document interfaces with the dedicated global interfaces. Here is an example with the @casl/mongoose plugin:

declare global {
  namespace RefletMongoose {
    interface Model {
      accessibleBy<T extends mongoose.Document>(ability: AnyMongoAbility, action?: string): mongoose.DocumentQuery<T[], T>
    }
    interface Document {}
  }
}

References narrowing

SchemaType ref option can be either a Model or a model name. With Reflet, by default, any class can be passed as a Model and any string can be passed as a model name.

By augmenting the global interface Ref, you can:

  • Narrow the class to an union of your models.
  • Narrow the string to an union of your models' names.
// company.model.ts
@Model()
class Company extends Model.I {
  @Field(String)
  name: string
}

// You should augment the global interface in each of your models' files, to keep it close to the model.
declare global {
  namespace RefletMongoose {
    interface Ref {
      Company: Company
    }
  }
}
// user.model.ts
@Model()
class User extends Model.I {
  @Field({
    type: mongoose.Schema.Types.ObjectId,
    ref: 'Company',
  })
  company: Company
}

declare global {
  namespace RefletMongoose {
    interface Ref {
      User: User
    }
  }
}