MongoCollectionService

import { MongoCollectionService } from '@opra/mongodb';

Hierarchy: ServiceBase → MongoService → MongoEntityService → MongoCollectionService

---

Constructor

new MongoCollectionService<T>(dataType: Type | string, options?: MongoCollectionService.Options)

---

Properties

Property	Type	Description
defaultLimit	number	Maximum records returned by findMany when no limit option is given

---

Methods

assert

assert(id: AnyId, options?: ExistsOptions<T>): Promise<void>

Throws ResourceNotAvailableError if no document with the given _id exists.

options — ExistsOptions<T>

---

create

create(input: PartialDTO<T>, options: RequiredSome<CreateOptions, 'projection'>): Promise<PartialDTO<T>>
create(input: PartialDTO<T>, options?: CreateOptions): Promise<T>

Inserts a new document and fetches it back. If projection is supplied the return type narrows to PartialDTO<T>.

options — CreateOptions

---

count

count(options?: CountOptions<T>): Promise<number>

Returns the number of documents matching the filter.

options — CountOptions<T>

---

delete

delete(id: AnyId, options?: DeleteOptions<T>): Promise<number>

Removes the document with the given _id. Returns the number of deleted documents.

options — DeleteOptions<T>

---

deleteMany

deleteMany(options?: DeleteManyOptions<T>): Promise<number>

Removes all documents matching the filter. Returns the number of deleted documents.

options — DeleteManyOptions<T>

---

distinct

distinct(field: string, options?: DistinctOptions<T>): Promise<any[]>

Returns distinct values for a field across documents matching the filter.

options — DistinctOptions<T>

---

exists

exists(id: AnyId, options?: ExistsOptions<T>): Promise<boolean>

Returns true if a document with the given _id exists.

options — ExistsOptions<T>

---

existsOne

existsOne(options?: ExistsOptions<T>): Promise<boolean>

Returns true if at least one document matches the filter.

options — ExistsOptions<T>

---

findById

findById(id: AnyId, options: RequiredSome<FindOneOptions<T>, 'projection'>): Promise<PartialDTO<T> | undefined>
findById(id: AnyId, options?: FindOneOptions<T>): Promise<T | undefined>

Fetches a document by _id. Returns undefined if not found.

options — FindOneOptions<T>

---

findOne

findOne(options: RequiredSome<FindOneOptions<T>, 'projection'>): Promise<PartialDTO<T> | undefined>
findOne(options?: FindOneOptions<T>): Promise<T | undefined>

Fetches the first document matching the filter. Returns undefined if not found.

options — FindOneOptions<T>

---

findMany

findMany(options: RequiredSome<FindManyOptions<T>, 'projection'>): Promise<PartialDTO<T>[]>
findMany(options?: FindManyOptions<T>): Promise<T[]>

Fetches a list of documents. Applies defaultLimit when options.limit is not specified.

options — FindManyOptions<T>

---

findManyWithCount

findManyWithCount(options: RequiredSome<FindManyOptions<T>, 'projection'>): Promise<{ count: number; items: PartialDTO<T>[] }>
findManyWithCount(options?: FindManyOptions<T>): Promise<{ count: number; items: T[] }>

Same as findMany but also returns the total count of matching documents before pagination.

options — FindManyOptions<T>

---

get

get(id: AnyId, options: RequiredSome<FindOneOptions<T>, 'projection'>): Promise<PartialDTO<T>>
get(id: AnyId, options?: FindOneOptions<T>): Promise<T>

Fetches a document by _id. Throws ResourceNotAvailableError if not found.

options — FindOneOptions<T>

---

replace

replace(id: AnyId, input: PartialDTO<T>, options: RequiredSome<ReplaceOptions<T>, 'projection'>): Promise<PartialDTO<T>>
replace(id: AnyId, input: PartialDTO<T>, options?: CreateOptions): Promise<T>

Replaces the full document with the given _id and returns the new document.

options — ReplaceOptions<T>

---

update

update(id: AnyId, input: MongoPatchDTO<T> | UpdateFilter<T>, options: RequiredSome<UpdateOneOptions<T>, 'projection'>): Promise<PartialDTO<T> | undefined>
update(id: AnyId, input: MongoPatchDTO<T> | UpdateFilter<T>, options?: UpdateOneOptions<T>): Promise<T | undefined>

Applies a partial update to the document with the given _id and returns the updated document. Returns undefined if not found.

Accepts either a MongoPatchDTO<T> (OPRA patch object) or a raw MongoDB UpdateFilter<T>. The two forms are mutually exclusive.

options — UpdateOneOptions<T>

---

updateOnly

updateOnly(id: AnyId, input: MongoPatchDTO<T> | UpdateFilter<T>, options?: UpdateOneOptions<T>): Promise<number>

Same as update but does not fetch and return the updated document. Returns the number of matched documents.

options — UpdateOneOptions<T>

---

updateMany

updateMany(input: MongoPatchDTO<T> | UpdateFilter<T>, options?: UpdateManyOptions<T>): Promise<number>

Applies a partial update to all documents matching the filter. Returns the number of matched documents.

options — UpdateManyOptions<T>

---

Interfaces

MongoCollectionService.Options

Extends MongoEntityService.Options → MongoService.Options.

Option	Type	Default	Description
defaultLimit	number	10	Default maximum number of records returned by findMany

---

CreateOptions

Extends mongodb.InsertOneOptions.

Option	Type	Description
projection	string | string[] | Document | '*'	Fields to return in the fetched-back document. Omit for all fields.

---

CountOptions

Extends mongodb.CountOptions.

Option	Type	Description
filter	FilterInput<T>	Filter criteria to count.

---

DeleteOptions

Extends mongodb.DeleteOptions.

Option	Type	Description
filter	FilterInput<T>	Additional filter criteria for the delete.

---

DeleteManyOptions

Extends mongodb.DeleteOptions.

Option	Type	Description
filter	FilterInput<T>	Filter criteria — only matching documents are deleted.

---

DistinctOptions

Extends mongodb.DistinctOptions.

Option	Type	Description
filter	FilterInput<T>	Filter criteria to apply before collecting distinct values.

---

ExistsOptions

Extends mongodb.CommandOperationOptions (minus session).

Option	Type	Description
filter	FilterInput<T>	Additional filter criteria for the existence check.

---

FindOneOptions

Same as FindManyOptions<T> without the limit property.

---

FindManyOptions

Extends mongodb.AggregateOptions.

Option	Type	Description
filter	FilterInput<T>	Filter criteria (maps to a $match aggregation stage).
projection	string | string[] | Document | '*'	Fields to include. '*' returns all fields.
sort	string[]	Sort directives, e.g. ['name', '-createdAt'] (prefix - for descending).
limit	number	Maximum number of documents to return. Defaults to defaultLimit.
skip	number	Number of documents to skip before returning results.
preStages	mongodb.Document[]	Aggregation stages inserted before the filter stage.
postStages	mongodb.Document[]	Aggregation stages appended after the limit stage.
noDecode	boolean	Skip OPRA output decoding and return raw MongoDB documents.

---

ReplaceOptions

Extends mongodb.FindOneAndReplaceOptions (minus projection).

Option	Type	Description
projection	string | string[] | Document | '*'	Fields to return in the replaced document.
filter	FilterInput<T>	Additional filter criteria for the replace.

---

UpdateOneOptions

Extends mongodb.FindOneAndUpdateOptions (minus projection, returnDocument, includeResultMetadata).

Option	Type	Description
projection	string | string[] | Document | '*'	Fields to return in the updated document.
filter	FilterInput<T>	Additional filter criteria for the update.
initArrayFields	string[]	Array field names to initialize as [] if they don't exist before the update.

---

UpdateManyOptions

Extends mongodb.UpdateOptions (minus upsert).

Option	Type	Description
filter	FilterInput<T>	Filter criteria — only matching documents are updated.
initArrayFields	string[]	Array field names to initialize as [] if they don't exist before the update.