Reference <T>

Wrapper around an entity that provides lazy loading capabilities and identity-preserving reference semantics.

Hierarchy

• Reference
  • LoadedReference

Index

Constructors

• constructor

Methods

• getEntity
• getProperty
• isInitialized
• load
• loadOrFail
• loadProperty
• populated
• toJSON
• unwrap
• create
• createFromPK
• createNakedFromPK
• isReference
• unwrapReference
• wrapReference

Constructors

constructor

• new Reference<T>(entity): Reference<T>

• Parameters

  • entity: T

  Returns Reference<T>

Methods

getEntity

• getEntity(): T

• Returns the underlying entity, throwing an error if the reference is not initialized.

  ---

  Returns T

getProperty

• getProperty<K>(prop): T[K]

• Returns the value of a property on the underlying entity. Throws if the reference is not initialized.

  ---

  Parameters

  • prop: K

  Returns T[K]

isInitialized

• isInitialized(): boolean

• Returns whether the underlying entity has been fully loaded from the database.

  ---

  Returns boolean

load

• load<TT, P, F, E>(options): Promise<null | Loaded<TT, P, F, E>>

• Ensures the underlying entity is loaded first (without reloading it if it already is loaded). Returns the entity. If the entity is not found in the database (e.g. it was deleted in the meantime, or currently active filters disallow loading of it) the method returns null. Use loadOrFail() if you want an error to be thrown in such a case.

  ---

  Parameters

  • options: LoadReferenceOptions<TT, P, F, E> = {}

  Returns Promise<null | Loaded<TT, P, F, E>>

loadOrFail

• loadOrFail<TT, P, F, E>(options): Promise<Loaded<TT, P, F, E>>

• Ensures the underlying entity is loaded first (without reloading it if it already is loaded). Returns the entity or throws an error just like em.findOneOrFail() (and respects the same config options).

  ---

  Parameters

  • options: LoadReferenceOrFailOptions<TT, P, F, E> = {}

  Returns Promise<Loaded<TT, P, F, E>>

loadProperty

• loadProperty<TT, P, K>(prop, options): Promise<Loaded<TT, P>[K]>

• Loads the entity if needed, then returns the value of the specified property.

  ---

  Parameters

  • prop: K

  • optionaloptions: LoadReferenceOrFailOptions<TT, P, *, never>

  Returns Promise<Loaded<TT, P>[K]>

populated

• populated(populated): void

• Marks the underlying entity as populated or not for serialization purposes.

  ---

  Parameters

  • optionalpopulated: boolean

  Returns void

toJSON

• toJSON(...args): Dictionary

• Serializes the underlying entity to a plain JSON object.

  ---

  Parameters

  • rest...args: any[]

  Returns Dictionary

unwrap

• unwrap(): T

• Returns the underlying entity without checking initialization state.

  ---

  Returns T

staticcreate

• create<T>(entity): Ref<T>

• Creates a Reference wrapper for the given entity, preserving identity if one already exists.

  ---

  Parameters

  • entity: T | Ref<T>

  Returns Ref<T>

staticcreateFromPK

• createFromPK<T>(entityType, pk, options): Ref<T>

• Creates a Reference wrapper for an entity identified by its primary key, wrapped in a Ref.

  ---

  Parameters

  • entityType: EntityClass<T>

  • pk: T extends { [PrimaryKeyProp]?: PK } ? PK extends undefined ? Omit<T<T>, typeof PrimaryKeyProp> : PK extends keyof T<T> ? ReadonlyPrimary<UnwrapPrimary<T<T>[PK<PK>]>> : PK extends keyof T<T>[] ? ReadonlyPrimary<PrimaryPropToType<T<T>, PK<PK>>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T

  • optionaloptions: { schema?: string }

  • optionalschema: string

  Returns Ref<T>

staticcreateNakedFromPK

• createNakedFromPK<T>(entityType, pk, options): T

• Creates an uninitialized entity reference by primary key without wrapping it in a Reference.

  ---

  Parameters

  • entityType: EntityClass<T>

  • pk: T extends { [PrimaryKeyProp]?: PK } ? PK extends undefined ? Omit<T<T>, typeof PrimaryKeyProp> : PK extends keyof T<T> ? ReadonlyPrimary<UnwrapPrimary<T<T>[PK<PK>]>> : PK extends keyof T<T>[] ? ReadonlyPrimary<PrimaryPropToType<T<T>, PK<PK>>> : PK : T extends { _id?: PK } ? string | ReadonlyPrimary<PK> : T extends { id?: PK } ? ReadonlyPrimary<PK> : T extends { uuid?: PK } ? ReadonlyPrimary<PK> : T

  • optionaloptions: { schema?: string }

  • optionalschema: string

  Returns T

staticisReference

• isReference<T>(data): data is Reference<T>

• Checks whether the argument is instance of Reference wrapper.

  ---

  Parameters

  • data: any

  Returns data is Reference<T>

staticunwrapReference

• unwrapReference<T>(ref): T

• Returns wrapped entity.

  ---

  Parameters

  • ref: T | Reference<T> | ScalarReference<T> | Ref<T>

  Returns T

staticwrapReference

• wrapReference<T, O>(entity, prop): T | Reference<T>

• Wraps the entity in a Reference wrapper if the property is defined as ref.

  ---

  Parameters

  • entity: T | Reference<T>

  • prop: EntityProperty<O, T>

  Returns T | Reference<T>