Every single entity relation is mapped to an entity reference. Reference is an entity that has only its identifier. This reference is stored in identity map so you will get the same object reference when fetching the same document from database.
You can call
await wrap(entity).init() to initialize the entity. This will trigger database call
and populate itself, keeping the same reference in identity map.
Better Type-safety with
When you define
@OneToOne properties on your entity, TypeScript compiler
will think that desired entities are always loaded:
You can overcome this issue by using the
Reference<T> wrapper. It simply wraps the entity,
load(): Promise<T> method that will first lazy load the association if not already
available. You can also use
unwrap(): T method to access the underlying entity without loading
You can also use
get<K extends keyof T>(prop: K): Promise<T[K]> helper, that will call
for you, making sure the entity is initialized first, then returning the value of given property
There are also
getProperty() methods that are synchronous getters,
that will first check if the wrapped entity is initialized, and if not, it will throw
If you use different metadata provider than
ReflectMetadataProvider), you will also need to explicitly set
When you define the property as
Reference wrapper, you will need to assign the
to it instead of the entity. You can create it via
Reference.create() factory, or use
Another way is to use
toReference() method available as part of
If the reference already exist, you can also re-assign to it via
IdentifiedReference is an intersection type that adds primary key property to the
interface. It allows to get the primary key from
Reference instance directly.
By default, we try to detect the PK by checking if a property with a known name exists.
We check for those in order:
id - with a way to manually set the property
PrimaryKeyProp symbol (
We can also override this via second generic type argument.
You can also have non-standard primary key:
For MongoDB, defined the PK generic type argument as
'id' | '_id' to access both
ObjectId PK values:
As opposed to
EntityHelper.init()which always refreshes the entity,
Reference.load()method will query the database only if the entity is not already loaded in Identity Map.