Collection <T, O>

Represents a to-many relation (1:m or m:n) as an iterable, managed collection of entities.

Hierarchy

• Collection
  • LoadedCollection

Index

Constructors

• constructor

Properties

• owner

Accessors

• length

Methods

• [iterator]
• add
• contains
• count
• exists
• filter
• find
• getIdentifiers
• getItems
• indexBy
• init
• isDirty
• isEmpty
• isInitialized
• isPartial
• load
• loadCount
• loadItems
• map
• matching
• populated
• reduce
• remove
• removeAll
• set
• setDirty
• shouldPopulate
• slice
• toArray
• toJSON
• create

Constructors

constructor

• new Collection<T, O>(owner, items, initialized): Collection<T, O>

• Parameters

  • owner: O

  • optionalitems: T[]

  • initialized: boolean = true

  Returns Collection<T, O>

Properties

readonlyowner

owner: O

Accessors

length

• get length(): number

• Returns number

Methods

[iterator]

• [iterator](): IterableIterator<T, any, any>

• Returns IterableIterator<T, any, any>

add

• add<TT>(entity, ...entities): number

• Adds one or more items to the collection, propagating the change to the inverse side. Returns the number of items added.

  ---

  Parameters

  • entity: TT | Reference<TT> | Iterable<TT | Reference<TT>, any, any>

  • rest...entities: (TT | Reference<TT>)[]

  Returns number

contains

• contains<TT>(item, check): boolean

• Checks whether the collection contains the given item.

  ---

  Parameters

  • item: TT | Reference<TT>

  • check: boolean = true

  Returns boolean

count

• count(): number

• Returns the number of items in the collection. Throws if the collection is not initialized.

  ---

  Returns number

exists

• exists(cb): boolean

• Tests for the existence of an element that satisfies the given predicate.

  ---

  Parameters

  • cb: (item) => boolean

  Returns boolean

filter

• filter<S>(cb): S[]
• filter(cb): T[]

• Extracts a subset of the collection items.

  ---

  Parameters

  • cb: (item, index) => item is S

  Returns S[]

find

• find<S>(cb): undefined | S
• find(cb): undefined | T

• Returns the first element of this collection that satisfies the predicate.

  ---

  Parameters

  • cb: (item, index) => item is S

  Returns undefined | S

getIdentifiers

• getIdentifiers<U>(field): U[]

• Returns the primary key values (or a specific field) of all items in the collection.

  ---

  Parameters

  • optionalfield: string | string[]

  Returns U[]

getItems

• getItems(check): T[]

• Returns the items (the collection must be initialized)

  ---

  Parameters

  • check: boolean = true

  Returns T[]

indexBy

• indexBy<K1, K2>(key): Record<T[K1] & PropertyKey, T>
• indexBy<K1, K2>(key, valueKey): Record<T[K1] & PropertyKey, T[K2]>

• Maps the collection items to a dictionary, indexed by the key you specify. If there are more items with the same key, only the first one will be present.

  ---

  Parameters

  • key: K1

  Returns Record<T[K1] & PropertyKey, T>

init

• init<TT, P>(options): Promise<LoadedCollection<Loaded<TT, P>>>

• Initializes the collection by loading its items from the database.

  ---

  Parameters

  • options: InitCollectionOptions<TT, P, *, never> = {}

  Returns Promise<LoadedCollection<Loaded<TT, P>>>

isDirty

• isDirty(): boolean

• Returns boolean

isEmpty

• isEmpty(): boolean

• Returns true if the collection has no items. Throws if the collection is not initialized.

  ---

  Returns boolean

isInitialized

• isInitialized(fully): boolean

• Returns whether the collection has been initialized. Pass fully = true to also check that all items are initialized.

  ---

  Parameters

  • fully: boolean = false

  Returns boolean

isPartial

• isPartial(): boolean

• Returns whether the collection was partially loaded (propagation is disabled for partial collections).

  ---

  Returns boolean

load

• load<TT, P>(options): Promise<LoadedCollection<Loaded<TT, P>>>

• Ensures the collection is loaded first (without reloading it if it already is loaded). Returns the Collection instance (itself), works the same as Reference.load().

  ---

  Parameters

  • options: InitCollectionOptions<TT, P, *, never> = {}

  Returns Promise<LoadedCollection<Loaded<TT, P>>>

loadCount

• loadCount(options): Promise<number>

• Gets the count of collection items from database instead of counting loaded items. The value is cached (unless you use the where option), use refresh: true to force reload it.

  ---

  Parameters

  • options: boolean | LoadCountOptions<T> = {}

  Returns Promise<number>

loadItems

• loadItems<TT, P>(options): Promise<Loaded<TT, P>[]>

• Initializes the collection and returns the items

  ---

  Parameters

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

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

map

• map<R>(mapper): R[]

• Maps the collection items based on your provided mapper function.

  ---

  Parameters

  • mapper: (item, index) => R

  Returns R[]

matching

• matching<TT, P>(options): Promise<Loaded<TT, P>[]>

• Queries a subset of the collection items from the database with custom filtering, ordering, and pagination.

  ---

  Parameters

  • options: MatchingOptions<T, P>

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

populated

• populated(populated): void

• Marks the collection as populated or not for serialization purposes.

  ---

  Parameters

  • populated: undefined | boolean = true

  Returns void

reduce

• reduce<R>(cb, initial): R

• Maps the collection items based on your provided mapper function to a single object.

  ---

  Parameters

  • cb: (obj, item, index) => R

  • initial: R = ...

  Returns R

remove

• remove<TT>(entity, ...entities): number

• Remove specified item(s) from the collection. Note that removing item from collection does not necessarily imply deleting the target entity, it means we are disconnecting the relation - removing items from collection, not removing entities from database - Collection.remove() is not the same as em.remove(). If we want to delete the entity by removing it from collection, we need to enable orphanRemoval: true, which tells the ORM we don't want orphaned entities to exist, so we know those should be removed.

  ---

  Parameters

  • entity: TT | Reference<TT> | Iterable<TT | Reference<TT>, any, any> | (item) => boolean

  • rest...entities: (TT | Reference<TT>)[]

  Returns number

removeAll

• removeAll(): void

• Remove all items from the collection. Note that removing items from collection does not necessarily imply deleting the target entity, it means we are disconnecting the relation - removing items from collection, not removing entities from database - Collection.remove() is not the same as em.remove(). If we want to delete the entity by removing it from collection, we need to enable orphanRemoval: true, which tells the ORM we don't want orphaned entities to exist, so we know those should be removed.

  ---

  Returns void

set

• set(items): void

• Replaces all items in the collection with the given items.

  ---

  Parameters

  • items: Iterable<T | Reference<T>, any, any>

  Returns void

setDirty

• setDirty(dirty): void

• Parameters

  • dirty: boolean = true

  Returns void

shouldPopulate

• shouldPopulate(populated): boolean

• Returns whether this collection should be included in serialization based on its populated state.

  ---

  Parameters

  • optionalpopulated: boolean

  Returns boolean

slice

• slice(start, end): T[]

• Extracts a slice of the collection items starting at position start to end (exclusive) of the collection. If end is null it returns all elements from start to the end of the collection.

  ---

  Parameters

  • start: number = 0

  • optionalend: number

  Returns T[]

toArray

• toArray<TT>(): EntityDTO<TT>[]

• Converts all items in the collection to plain DTO objects.

  ---

  Returns EntityDTO<TT>[]

toJSON

• toJSON<TT>(): EntityDTO<TT>[]

• Serializes the collection items to plain JSON objects. Returns an empty array if not initialized.

  ---

  Returns EntityDTO<TT>[]

staticcreate

• create<T, O>(owner, prop, items, initialized): Collection<T, O>

• Creates new Collection instance, assigns it to the owning entity and sets the items to it (propagating them to their inverse sides)

  ---

  Parameters

  • owner: O

  • prop: EntityKey<O>

  • items: undefined | T[]

  • initialized: boolean

  Returns Collection<T, O>