Hydrate MongoDB documents into TypeScript-defined objects
When using MongoDB with TypeScript we usually want to save our "strongly-typed" entities into database collection and then retrieve them back at some later time. During this we face three major difficulties:
- objects returned by
mongodbdriver are plain objects. This means that if we have saved an object with some functions, these functions will not be saved and will not be present on the retrieved document. If we were to assign all properties of received object to a properly TypeScript-typed object, we would have to do this recursively, since some properties can also be typed objects and have own functions. - there is not easy way to reference other collections. In a noSQL database relations should be avoided, but we all know this is not always a viable option. In such case we define a field with id referencing some other collection and then make separate request to retrieve referenced entity and append it to referencing entity. This is tedious and not easy to explain well to TypeScript's static typing.
- class definitions should reflect database schema. In particular: we want to use a property decorator to define database indexes
This package strives to facilitate at these points by wrapping official mongodb package. It utilizes class-transformer package to hydrate and de-hydrate plain object into classed objects and vice-versa.
It may seem that it is a TypeScript equivalent to mongoose package, but this is not the case, since it does not provide any validation, stripping of non-defined properties or middleware.
This package is trying to be as non-restrictive as possible and to let the developer access underlying mongodb functions and mechanism (such as cursors) while still providing hydration, population and schema reflection.
$ npm install mongodb-typescript
Make sure to enable emitDecoratorMetadata and experimentalDecorators in tsconfig.json
import { id, Repository } from 'mongodb-typescript';
// define your entity
class User {
@id id: ObjectId;
name: string;
age: number = 15;
hello() {
return `Hello, my name is ${this.name} and I am ${this.age} years old`;
}
}
const repository = new Repository<User>(User, mongodbClient);
// create new user entity (MongoDB document)
const user = new User();
user.name = 'tom';
await userRepo.insert(user);
// prints "User { id: 5ba2648a6f74af5def444491, name: 'tom', age: 15 }"
console.log(user);
// now let's retrieve entity from database
const saved = await userRepo.findById(user.id);
// prints `Hello, my name is tom and I am 15 years old`
console.log(saved.hello());Required. Defines primary id that will be used as _id of the mongo collection.
class Post {
@id myId: ObjectId;
}All properties except ones decorated with @id that are of type ObjectId (from bson package) must have @objectId because underlying package class-transformer does not handle it correctly.
class Post {
...
@objectId authorId: ObjectId;
}Used to mark nested entity or array of entities.
| Parameter | |
|---|---|
| typeFunction | Function that returns type of nested entity |
Example usage:
class Texts {
main: string;
doc: string;
}
class Comment {
text: string;
}
class Post {
@id id: ObjectId;
title: string;
@nested(() => Texts) text: Texts;
@nested(() => Comment) comments: Comment[]
}This would represent following mongo document:
{
"_id": ObjectId("5b27c8da65ec1b5c0c0e8ed4"),
"title": "My new post",
"timestamps": {
"postedAt": ISODate("2018-09-15T10:50:38.718Z"),
"lastUpdateAt": ISODate("2018-09-15T10:50:38.718Z"),
},
"comments": [
{ "text": "This is good." },
{ "text": "This is bad." }
]
}Used to mark a property as ignored so it will not ba saved in the database.
Example usage:
class User {
@id id: ObjectId;
name: string;
@ignore onlyImportantAtRuntime: number;
}This would represent following mongo document:
// user
{
"_id": ObjectId("5b27d15bfab97f681aac2862"),
"name": "gregory"
}Used to define an entity or array of entities that will not be saved into another collection and only have a key or array of keys saved on referencing entity's collection.
This key will be saved in a field named {@ref field name}Id or {@ref field name}Ids.
To access this key directly or apply a custom name you can pass a parameter with name of your key field. See example below.
| Parameter | |
|---|---|
| refId | Optional. Name of field should hold referencing key |
Example usage:
class User {
@id id: ObjectId;
name: string;
}
class Post {
@id id: ObjectId;
title: string;
@ref() author: User;
}This would represent following mongo documents:
// post
{
"_id": ObjectId("5b27c8da65ec1b5c0c0e8ed4"),
"title": "My new post",
"authorId": ObjectId("5b27d15bfab97f681aac2862")
}
// user
{
"_id": ObjectId("5b27d15bfab97f681aac2862"),
"name": "gregory"
}Custom referencing key:
class Post {
...
@objectId author_key: ObjectId;
@ref('author_key') author: User;
}Used to define an index on a field.
does not actually create the index. Use Repository.createIndexes to do so.
Parameters:
| parameter | |
|---|---|
| type | Type of index. Use 1 or -1 for ascending or descending order, respectively. Use string value for other index types (eg. '2dsphere' for geo spacial index). Defaults to 1 |
| options | Optional. SimpleIndexOptions. See table below, SimpleIndexOptions interface or mongodb docs |
SimpleIndexOptions:
| field | type | |
|---|---|---|
| name | string | Name of the index. Defaults to field name. |
| background | boolean | |
| unique | boolean | |
| partialFilterExpression | document | |
| sparse | boolean | |
| expireAfterSeconds | number | |
| storageEngine | document | |
| weights | document | |
| default_language | string | |
| language_override | string | |
| textIndexVersion | number | |
| 2dsphereIndexVersion | number | |
| bits | number | |
| min | number | |
| max | number | |
| bucketSize | number | |
| collation | Object |
Example usage:
class User {
...
@index(1, { unique: true, sparse: true, name: 'email_unique_index' }) email: string;
@index() someId: number;
}Used to define an indexes on a entity (most likely compound).
does not actually create the index. Use Repository.createIndexes to do so.
Parameters:
| parameter | type |
|---|---|
| indexes | IndexOptions[] |
IndexOptions:
| field | type | |
|---|---|---|
| name | string | Required. Name of the index |
| key | document | A document that contains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1. See mongodb documentation |
| ... | All properties of SimpleIndexOptions |
Reference to mongodb collection that handles hydration and de-hydration of documents into entities and vice-versa.
Repository is a generic class that requires type parameter T should be type of entity that is stored in referenced collection.
Different repositories may reference collections in different databases at different hosts.
| parameter | type | |
|---|---|---|
| entity | type | type of stored entities. Must equal T |
| mongoClient | MongoClient | mongo client to use for all requests |
| collection | string | name of collection to reference |
const userRepo = new Repository<User>(User, mongoClient, 'users');mongodb collection used to make all the requests to the database.
Can be used to access all features of mongodb, but returns non-hydrated (plain) objects.
const raw = await userRepo.c.findOne({ name: 'tom' });Gets number of documents matching the filter.
| parameter | type | |
|---|---|---|
| filter | Filter | Optional mongodb filter |
const total = await userRepo.count();
const adults = await userRepo.count({ age: { $gte: 18 } });Creates all indexes defined using @index and @indexes decorators on entity.
| parameter | type | |
|---|---|---|
| forceBackground | boolean | Forces background index creation |
await userRepo.createIndexes();
await userRepo.createIndexes(true);Inserts a new entity into database and assigns generated _id back to entity.
| parameter | type | |
|---|---|---|
| entity | T | Entity to insert |
const user = new User();
user.name = 'tom';
await userRepo.insert(user);
// user.id is now populatedReplaces an existing entity in database.
| parameter | type | |
|---|---|---|
| entity | T | Entity to update |
| options | ReplaceOptions | Options passed to replaceOne |
await userRepo.update(user);
await userRepo.update(user, { upsert: true });Inserts or updates entity depending on presence of id.
await userRepo.save(user);Finds a single document and returns hydrated entity.
| parameter | type | |
|---|---|---|
| filter | Filter | mongodb filter |
const user = await userRepo.findOne({ name: 'tom' });Finds entity by its id.
| parameter | type | |
|---|---|---|
| id | ObjectId | Entity id |
const user = await userRepo.findById(userId);Finds multiple entities by their ids.
| parameter | type | |
|---|---|---|
| ids | ObjectId[] | Array of ids |
const users = await userRepo.findManyById([id1, id2]);Returns mongodb cursor that hydrates entities automatically.
| parameter | type | |
|---|---|---|
| filter | Filter | mongodb filter |
const cursor = userRepo.find({ age: { $gte: 18 } });
const users = await cursor.toArray();Populates a reference field on a single entity.
Works for both single and array references.
| parameter | type | |
|---|---|---|
| entity | object | Entity instance |
| refName | string | Name of reference field |
await userRepo.populate(post, 'author');
await userRepo.populate(post, 'pinnedBy');Populates a reference field on multiple entities in a single batch query.
This is more efficient than calling populate in a loop.
| parameter | type | |
|---|---|---|
| entities | object[] | Array of entities |
| refName | string | Name of reference field |
await userRepo.populateMany(posts, 'author');
await userRepo.populateMany(comments, 'commentator');Converts a plain object from database into typed entity with functions, typed nested entities and correctly named _id field.
Use this function when fetching documents via vanilla mongodb collection.
const raw = await userRepo.c.findOne({});
const entity = userRepo.hydrate(raw);Returns plain object that can be saved to database.
Handles custom _id names, nested entities and dereferencing of referenced objects.
This is a standalone function and does not require associated repository.
const plain = dehydrate(entity);