# mongoose-typescript

> Build mongoose schema with typescript and decorator

Latest version **3.4.0** (published 2025-12-24) · MIT license · 85 weekly downloads

## Install

```sh
npm install mongoose-typescript
pnpm add mongoose-typescript
yarn add mongoose-typescript
bun add mongoose-typescript
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: declining downloads.

## Facts

| | |
|---|---|
| Version | 3.4.0 |
| Published | 2025-12-24 |
| First published | 2018-11-08 |
| Weekly downloads | 85 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18.0.0 |
| Dependencies | 4 |
| Unpacked size | 45.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 14 |
| Author | bangbang93 |
| Maintainers | bangbang93 |
| Keywords | mongoose, typescript, decrator |

## Links

- npm: https://www.npmjs.com/package/mongoose-typescript
- Repository: https://github.com/bangbang93/mongoose-typescript
- Homepage: https://github.com/bangbang93/mongoose-typescript#readme
- Issues: https://github.com/bangbang93/mongoose-typescript/issues
- npm.io page: https://npm.io/package/mongoose-typescript

## Dependencies (4)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [type-fest](https://npm.io/package/type-fest.md) ^2.11.1
- [@sindresorhus/is](https://npm.io/package/@sindresorhus/is.md) ^4.2.0
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.1.13

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [electron-installer-squirrel-windows](https://npm.io/package/electron-installer-squirrel-windows.md) — 47 weekly downloads

## Recent versions

- 3.4.0 (latest) — 2025-12-24
- 1.2.0-0 (next) — 2021-05-12
- 3.3.0 — 2024-06-07
- 3.2.1 — 2023-11-30
- 3.2.0 — 2023-11-30
- 3.1.0 — 2023-11-29
- 3.0.1 — 2023-07-14
- 3.0.0 — 2023-06-27
- 2.4.0 — 2023-03-06
- 2.3.3 — 2022-08-01
- 2.3.2 — 2022-08-01
- 2.3.1 — 2022-02-18
- 2.3.0 — 2022-02-11
- 2.2.3 — 2022-02-09
- 2.2.2 — 2022-02-09
- … 50 more at https://npm.io/package/mongoose-typescript/versions

## README

# mongoose-typescript
Build mongoose schema with typescript and decorator

## Before Usage
make sure that both `experimentalDecorators` and `emitDecoratorMetadata` are set to true in tsconfig

## Example

```typescript
@subModel()
class Address {
  @prop() @required public country: string
  @prop() @required public province: string
  @prop() @required public city: string
  @prop() @required public address: string
}

@model('user')
class User extends Model<User> {
  @statics
  public static async findByName(name: string): Promise<User> {
    return this.findOne({username: name})
  }

  @id public readonly _id: mongoose.Types.ObjectId

  @prop() @unique @required public username: string
  @prop() @hidden public password: string
  @prop() @indexed public loginCount: number
  @array(Address) public addresses: Address[]

  @methods
  public addAddress(address: Address) {
    this.addresses.push(address)
    return this
  }
}

@model('organization')
@index({user: 1, name: 1}, {unique: true})
class Organization extends Model<Organization> {
  @statics
  public static async listByUser(userId: string) {
    return this.find({
      members: userId,
    })
  }

  @id public readonly _id: mongoose.Types.ObjectId

  @ref(User) @required public user: Ref<User>
  @prop() @unique @required public name: string
  @array() @ref(User) public members: Array<Ref<User>>

  @methods
  public async addMember(userId: mongoose.Types.ObjectId) {
    this.members.push(userId)
    return this.save()
  }
}

const UserModel: typeof User = getModel(User)

const user = new UserModel({
  username: 'abc',
  password: 'wow',
  addresses: [{
    country: 'china',
    provicne: 'zhejiang',
    city: 'hangzhou',
    address: 'xihu',
  }],
})

user.save()
```

## Function
`getSchema(model): Schema` get Schema for custom config

`getModel(model): Model` get Model

## Model level Decorators

`@model(name: string, options?: SchemaOptions)`

`@index(fields: IIndexArgs['fields'], options?: IIndexArgs['options'])`

`@plugin<T>(plugin: IPluginType<T>, options?: T)` registers a mongoose [schema plugin](https://mongoosejs.com/docs/plugins.html)

`@subModel(options: SchemaOptions & {name?: string} = {})`

## Schema level Decorators

`@prop(options: SchemaTypeOpts<T> = {}, type?: T)` type is optional, mongoose-typescript will try to determined the type automatically

`@array(type?: T, options?: SchemaTypeOpts<T>)` because of typescript only mark the type as Array, so array field need set type manually, or using mixed

`@id` empty decorator, just for emit Reflect metadata for `_id`

`@required` set field `{required: true}`

`@indexed` set field `{index: true}`

`@hidden` set field `{select: false}`

`@unique` set field `{unique: true}`

`@type(type)` set field `{type: type}`

`@defaults(value)` set field `{default: value}`

`@ref(nameOrClass: string | IMongooseClass)` set field `{ref: nameOrClass}`
if type isn't set, and the argument is class, `mongoose-typescript` will try to using the typeof `class._id`

`@statics` register static method

`@methods` register instance method

`@query` register query helper

`@virtual` register virtual field

## APIDOC
<https://bangbang93.github.io/mongoose-typescript>

---
_Source: https://npm.io/package/mongoose-typescript · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._