Class: AmbitenModel<T>

Returns

this

afterAggregate()

afterAggregate(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5534

Parameters

handler

Returns

this

afterBulkInsert()

afterBulkInsert(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5518

Parameters

handler

Returns

this

afterBulkUpdate()

afterBulkUpdate(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5526

Parameters

handler

Returns

this

afterDeleteMany()

afterDeleteMany(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5510

Parameters

handler

Returns

this

afterDeleteOne()

afterDeleteOne(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5502

Parameters

handler

Returns

this

afterFind()

afterFind(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5470

Parameters

handler

Returns

this

afterFindOne()

afterFindOne(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5478

Parameters

handler

Returns

this

afterFindOneAndDelete()

afterFindOneAndDelete(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5550

Parameters

handler

Returns

this

afterFindOneAndReplace()

afterFindOneAndReplace(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5558

Parameters

handler

Returns

this

afterFindOneAndUpdate()

afterFindOneAndUpdate(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5542

Parameters

handler

Returns

this

afterFindOneAndUpsert()

afterFindOneAndUpsert(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5566

Parameters

handler

Returns

this

afterSave()

afterSave(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5486

Parameters

handler

Returns

this

afterUpdateOne()

afterUpdateOne(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5494

Parameters

handler

Returns

this

aggregate()

aggregate<U>(pipeline, options?, externalSession?, ctx?, queryOptions?): Promise<U[]>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3507

Executes an aggregation pipeline against the model collection.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered aggregate middlewares, supports optional query-result caching, and publishes a database change event after execution.

When caching is enabled through QueryOptions, the aggregation result is stored and reused using a tenant-aware cache key derived from the collection, pipeline, options, and runtime context.

Type Parameters

U

U extends Document

The aggregation result document shape.

Parameters

pipeline

object[]

MongoDB aggregation pipeline stages.

options?

AggregateOptions = {}

Optional MongoDB aggregation options.

externalSession?

ClientSession

Optional explicit client session to use for the aggregation.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

queryOptions?

QueryOptions

Optional query-level features such as caching.

Returns

Promise<U[]>

The aggregation result array.

Throws

When the pipeline is missing or invalid.

aggregateWithCache()

aggregateWithCache(pipeline, cacheKey, cacheDuration?): Promise<T[]>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3984

Aggregates documents in the collection using a pipeline with caching.

Parameters

pipeline

object[]

The aggregation pipeline.

cacheKey

string

The cache key.

cacheDuration?

number = 300

The cache duration in seconds.

Returns

Promise<T[]>

The aggregation result as an array.

Throws

If the pipeline is not valid or the cache key is not a string.

aggregateWithTransaction()

aggregateWithTransaction<U>(pipeline, options?, ctx?): Promise<U[]>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3649

Executes an aggregation pipeline inside a transaction-aware runtime context.

This transactional variant runs within the active Ambiten runtime context, executes registered aggregate middlewares, triggers schema aggregate hooks, instruments the query through measureQuery, and publishes a database change event after execution.

Type Parameters

U

U extends Document

The aggregation result document shape.

Parameters

pipeline

object[]

MongoDB aggregation pipeline stages.

options?

AggregateOptions = {}

Optional MongoDB aggregation options.

ctx?

AmbitenMiddlewareOperation

Optional model execution context for tenant, database, collection, session, and transaction-aware runtime overrides.

Returns

Promise<U[]>

The aggregation result array.

Throws

When the pipeline is missing or invalid.

before()

before(operation, handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5446

Parameters

operation

handler

Returns

this

beforeAggregate()

beforeAggregate(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5530

Parameters

handler

Returns

this

beforeBulkInsert()

beforeBulkInsert(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5514

Parameters

handler

Returns

this

beforeBulkUpdate()

beforeBulkUpdate(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5522

Parameters

handler

Returns

this

beforeDeleteMany()

beforeDeleteMany(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5506

Parameters

handler

Returns

this

beforeDeleteOne()

beforeDeleteOne(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5498

Parameters

handler

Returns

this

beforeFind()

beforeFind(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5466

Parameters

handler

Returns

this

beforeFindOne()

beforeFindOne(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5474

Parameters

handler

Returns

this

beforeFindOneAndDelete()

beforeFindOneAndDelete(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5546

Parameters

handler

Returns

this

beforeFindOneAndReplace()

beforeFindOneAndReplace(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5554

Parameters

handler

Returns

this

beforeFindOneAndUpdate()

beforeFindOneAndUpdate(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5538

Parameters

handler

Returns

this

beforeFindOneAndUpsert()

beforeFindOneAndUpsert(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5562

Parameters

handler

Returns

this

beforeSave()

beforeSave(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5482

Parameters

handler

Returns

this

beforeUpdateOne()

beforeUpdateOne(handler): this

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5490

Parameters

handler

Returns

this

bind()

bind(ctx): AmbitenModel<T>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:512

Returns a model instance bound to a default context.

Parameters

ctx

Context to bind to the cloned model.

Returns

AmbitenModel<T>

A cloned model instance with merged default context.

bulkInsert()

bulkInsert(docs, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:1273

Inserts multiple documents into the model collection.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered bulkInsert middlewares, validates each incoming document against the model schema, triggers schema bulk insert hooks, invalidates relevant cache patterns, and publishes a database change event after successful insertion.

Parameters

docs

OptionalUnlessRequiredId<T>[]

The documents to insert.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the operation completes.

bulkUpdate()

bulkUpdate(updates, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:1395

Updates multiple documents using MongoDB bulk write semantics.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered bulkUpdate middlewares, triggers schema bulk update hooks, invalidates relevant cache patterns, and publishes a database change event after completion.

Each update entry is translated into an updateOne bulk operation using $set with the provided partial update document.

Parameters

updates

object[]

Array of filter/update pairs to execute as bulk updates.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the operation completes.

Throws

When the updates payload is invalid.

bulkWriteWithTransaction()

bulkWriteWithTransaction(operations, options?, ctx?): Promise<BulkWriteResult>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:2125

Executes multiple MongoDB bulk write operations inside a transaction-aware runtime context.

This transactional variant runs within the active Ambiten runtime context, executes registered bulk update middlewares, triggers schema bulk update hooks with transactional metadata, invalidates relevant cache patterns, and publishes a database change event after completion.

Parameters

operations

AnyBulkWriteOperation<T>[]

MongoDB bulk write operations to execute.

options?

BulkWriteOptions = {}

Optional MongoDB bulk write options.

ctx?

Optional model execution context for tenant, database, collection, session, and transaction-aware runtime overrides.

Returns

Promise<BulkWriteResult>

The MongoDB bulk write result.

Throws

When the operations payload is missing or invalid.

create()

create(doc, ctx?): Promise<ModelResult<T>>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:753

Creates a new document in the model collection.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered create middlewares, validates the incoming document against the model schema, triggers schema create hooks, invalidates relevant cache patterns, and publishes a database change event after successful insertion.

Parameters

doc

OptionalUnlessRequiredId<T>

The document to insert.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<ModelResult<T>>

The created document as a normalized model result.

Throws

When the provided document is missing or invalid.

createIndex()

createIndex(fields, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4104

Creates an index on the model collection.

Parameters

fields

Partial<Record<keyof T, 1 | -1>>

Index field specification where each key maps to ascending (1) or descending (-1) index order.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the index has been created.

Throws

When the field specification is missing or invalid.

createWithTransaction()

createWithTransaction(doc, ctx?): Promise<ModelResult<T>>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:2004

Creates a new document inside a transaction-aware runtime context.

This transactional variant runs within the active Ambiten runtime context, executes registered create middlewares, validates the incoming document, triggers schema create hooks with transactional metadata, invalidates relevant cache patterns, and publishes a database change event after successful insertion.

Parameters

doc

OptionalUnlessRequiredId<T>

The document to insert.

ctx?

Optional model execution context for tenant, database, collection, session, and transaction-aware runtime overrides.

Returns

Promise<ModelResult<T>>

The created document as a normalized model result.

Throws

When the provided document is missing or invalid.

deleteMany()

deleteMany(filter, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:1726

Deletes multiple documents matching the provided filter.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered deleteMany middlewares, supports middleware-driven soft delete flows, triggers schema delete or update hooks as appropriate, invalidates relevant cache patterns, and publishes a database change event after completion.

When middleware metadata enables soft delete, matched documents are updated instead of being physically removed from the collection.

Parameters

filter

Filter<T>

MongoDB filter used to identify the documents to delete.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the operation completes.

Throws

When the filter is missing or invalid.

Throws

When soft delete is enabled but no softDeleteUpdate payload is provided.

deleteOne()

deleteOne(filter, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:1553

Deletes a single document matching the provided filter.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered delete middlewares, supports middleware-driven soft delete flows, triggers schema delete or update hooks as appropriate, invalidates relevant cache patterns, and publishes a database change event after completion.

When middleware metadata enables soft delete, the matched document is updated instead of being physically removed from the collection.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to delete.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the operation completes.

Throws

When the filter is missing or invalid.

Throws

When soft delete is enabled but no softDeleteUpdate payload is provided.

deleteSecure()

deleteSecure(filter, user, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3387

Deletes a single document matching the provided filter using an admin-only secure operation.

This method enforces authorization before executing the delete flow. It runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered model middlewares, triggers schema delete hooks with security metadata, invalidates relevant cache patterns, and publishes a database change event after a successful deletion.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to delete.

user

User

Authenticated user performing the operation. Must have the admin role.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the operation completes.

Throws

When the user is not authorized to perform the operation.

Throws

When the filter is missing or invalid.

Throws

When the user payload is missing.

deleteWithTransaction()

deleteWithTransaction(filter, ctx?): Promise<boolean>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:2254

Deletes a single document inside a transaction-aware runtime context.

This transactional variant runs within the active Ambiten runtime context, executes registered delete middlewares, triggers schema delete hooks with transactional metadata, invalidates relevant cache patterns, and publishes a database change event after completion.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to delete.

ctx?

Optional model execution context for tenant, database, collection, session, and transaction-aware runtime overrides.

Returns

Promise<boolean>

true when a document was deleted, otherwise false.

Throws

When the filter is missing or invalid.

dropIndex()

dropIndex(indexName): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4137

Drops an index from the collection by its name.

Parameters

indexName

string

The name of the index to drop.

Returns

Promise<void>

Resolves when the index is dropped.

find()

find(filter?, ctx?, options?): Promise<ModelResultArray<T>>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:865

Finds documents matching the provided filter.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered find middlewares, supports optional result caching, triggers schema find hooks, and returns normalized model results.

Parameters

filter?

Filter<T> = {}

MongoDB filter used to match documents.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

options?

QueryOptions

Optional query-level features such as caching.

Returns

Promise<ModelResultArray<T>>

An array of normalized model results.

Throws

When the filter is invalid.

findOne()

findOne(filter, ctx?, options?): Promise<ModelResult<T> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:1010

Finds a single document matching the provided filter.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered findOne middlewares, supports optional result caching, triggers schema find hooks, and returns a normalized model result when a document is found.

Parameters

filter

Filter<T>

MongoDB filter used to match the document.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

options?

QueryOptions

Optional query-level features such as caching.

Returns

Promise<ModelResult<T> | null>

The matched document as a normalized model result, or null if no document matched.

Throws

When the filter is missing or invalid.

findOneAndDelete()

findOneAndDelete(filter, ctx?): Promise<ModelResult<T> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:2673

Finds a single document matching the provided filter and deletes it.

Supports both hard delete and middleware-driven soft delete flows. When soft delete is enabled via middleware metadata, the matched document is updated using the provided soft-delete update operation instead of being physically removed from the collection.

The operation:

runs within the active Ambiten runtime context
is instrumented through measureQuery
executes registered before/after model middlewares
triggers schema delete/update hooks as appropriate
invalidates relevant cache patterns after mutation
publishes a database change event through PubSub

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to delete.

ctx?

Optional model execution context for tenant, database, session, cache, and collection overrides.

Returns

Promise<ModelResult<T> | null>

The deleted document as a model result, or null if no document matched.

Throws

When the filter is missing or invalid.

findOneAndReplace()

findOneAndReplace(filter, replacement, ctx?): Promise<ModelResult<T> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:2880

Finds a single document matching the provided filter and replaces it with the supplied replacement document.

This operation runs inside the active Ambiten runtime context, executes model middlewares, triggers schema update hooks, invalidates relevant cache entries, and publishes a database change event after a successful replacement.

The replacement document is fully validated before being persisted.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to replace.

replacement

T

The full replacement document that will overwrite the matched document.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<ModelResult<T> | null>

The replaced document in its updated form, or null if no document matched the filter.

Throws

When the filter is missing or invalid.

Throws

When the replacement document fails validation.

findOneAndUpdate()

findOneAndUpdate(filter, update, ctx?): Promise<ModelResult<T> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:2538

Finds a single document matching the provided filter and updates it.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered findOneAndUpdate middlewares, triggers schema update hooks, invalidates relevant cache patterns, and publishes a database change event after completion.

The updated document is returned in its post-update state when a matching document is found.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to update.

update

UpdateFilter<T>

MongoDB update document to apply.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<ModelResult<T> | null>

The updated document as a normalized model result, or null if no document matched the filter.

Throws

When the filter is missing or invalid.

Throws

When the update document is missing or invalid.

findOneAndUpsert()

findOneAndUpsert(filter, update, ctx?): Promise<ModelResult<T> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3002

Finds a single document matching the provided filter and updates it. If no matching document exists, a new one is inserted using MongoDB upsert semantics.

This operation runs within the active Ambiten runtime context, is instrumented through measureQuery, executes registered model middlewares, triggers schema update hooks, invalidates relevant cache patterns, and publishes a database change event after completion.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to update or insert.

update

UpdateFilter<T>

MongoDB update document applied to the matched document or to the inserted document during upsert.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<ModelResult<T> | null>

The updated or newly upserted document in its final state, or null if no document could be resolved from the operation result.

Throws

When the filter is missing or invalid.

Throws

When the update document is missing or invalid.

findOneAndUpsertWithTransaction()

findOneAndUpsertWithTransaction(filter, update, ctx?): Promise<ModelResult<T> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3124

Finds a single document matching the provided filter and updates it inside a transaction. If no document matches, a new one is inserted using MongoDB upsert semantics.

This transactional variant runs inside the active Ambiten runtime context, executes registered model middlewares, triggers schema update hooks with transactional metadata, invalidates relevant cache patterns, and publishes a database change event after completion.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to update or insert.

update

UpdateFilter<T>

MongoDB update document applied to the matched document or inserted document.

ctx?

Optional model execution context for tenant, database, collection, session, and transaction-aware runtime overrides.

Returns

Promise<ModelResult<T> | null>

The updated or newly inserted document in its final state, or null if no document could be resolved from the operation result.

Throws

When the filter is missing or invalid.

Throws

When the update document is missing or invalid.

findOneAndUpsertWithTransactionSecure()

findOneAndUpsertWithTransactionSecure(filter, update, user, ctx?): Promise<ModelResult<T> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3253

Finds a single document matching the provided filter and updates it inside a secure transaction. If no document matches, a new one is inserted using MongoDB upsert semantics.

This secure transactional variant enforces an admin-only authorization rule before performing the operation. It runs inside the active Ambiten runtime context, executes registered model middlewares, triggers schema update hooks with transactional and security metadata, invalidates relevant cache patterns, and publishes a database change event after completion.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to update or insert.

update

UpdateFilter<T>

MongoDB update document applied to the matched document or inserted document.

user

User

Authenticated user performing the operation. Must have the admin role.

ctx?

Optional model execution context for tenant, database, collection, session, and transaction-aware runtime overrides.

Returns

Promise<ModelResult<T> | null>

The updated or newly inserted document in its final state, or null if no document could be resolved from the operation result.

Throws

When the user is not authorized to perform the operation.

Throws

When the filter is missing or invalid.

Throws

When the update document is missing or invalid.

getContext()

getContext(): object

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4243

Returns

object

ctx

ctx: ModelContext

getSchema()

getSchema(): AmbitenSchema<T>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:585

Returns the schema attached to this model.

Returns

AmbitenSchema<T>

init()

init(): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:474

Initializes the model by validating configuration, resolving the collection, and creating the GC TTL index when enabled.

Returns

Promise<void>

invalidateDocumentCache()

invalidateDocumentCache(doc, ctx?): Promise<number>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4292

Invalidates cache entries related to a specific document within the current model scope.

This helper is useful only when document-specific cache keys are part of the active cache strategy.

Parameters

doc

T

The document whose cache entries should be invalidated.

ctx?

Optional model execution context.

Returns

Promise<number>

A promise that resolves when invalidation completes.

Throws

When the document is missing a valid _id.

invalidateModelPattern()

invalidateModelPattern(pattern, ctx?): Promise<number>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4258

Invalidates cache entries for the current model scope using a pattern.

This helper resolves tenant, database, and collection scope from the provided context and applies the pattern within the Ambiten cache namespace.

Parameters

pattern

string

Partial cache pattern (e.g. "find:", "aggregate:").

ctx?

Optional model execution context.

Returns

Promise<number>

Number of deleted cache entries.

Throws

When the pattern is invalid.

off()

off(event, listener): void

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:441

Removes a subscribed event listener.

Parameters

event

Event type.

listener

(...args) => void

Event listener callback.

Returns

void

on()

on(event, listener): void

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:421

Subscribes to a model event.

Parameters

event

Event type.

listener

(...args) => void

Event listener callback.

Returns

void

once()

once(event, listener): void

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:431

Subscribes to a model event once.

Parameters

event

Event type.

listener

(...args) => void

Event listener callback.

Returns

void

paginatedFind()

paginatedFind(filter, pageSize, lastId?): Promise<T[]>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4031

Cursor-based pagination using _id comparison instead of skip.

Parameters

filter

Partial<T>

The filter for documents.

pageSize

number

Number of documents per page.

lastId?

string

Last document _id from the previous page.

Returns

Promise<T[]>

Array of documents for the current page. This method uses the _id field for pagination, which is more efficient than using skip.

populateMany()

populateMany<K>(doc, field, relatedModel): Promise<T & Record<string, unknown> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:1962

Populates an array reference field on a document by resolving the related documents from another model.

This helper performs a follow-up lookup using the referenced field values as _id values of the related documents. If the target field is empty, undefined, or not an array, the original document is returned unchanged.

Type Parameters

K

K extends Document

The related model document type.

Parameters

doc

T

The source document containing the reference array field.

field

keyof T

The field on the source document that stores related document identifiers.

relatedModel

AmbitenModel<K>

The model used to resolve the related documents.

Returns

Promise<T & Record<string, unknown> | null>

The source document with the populated field replaced by the related document results, or null when the input document is invalid.

populateOne()

populateOne<K>(doc, field, relatedModel): Promise<T & Record<string, unknown> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:1920

Populates a single reference field on a document by resolving the related document from another model.

This helper performs a follow-up lookup using the referenced field value as the _id of the related document. If the target field is empty or undefined, the original document is returned unchanged.

Type Parameters

K

K extends Document

The related model document type.

Parameters

doc

T

The source document containing the reference field.

field

keyof T

The field on the source document that stores the related document identifier.

relatedModel

AmbitenModel<K>

The model used to resolve the related document.

Returns

Promise<T & Record<string, unknown> | null>

The source document with the populated field replaced by the related document result, or null when the input document is invalid.

registerModel()

registerModel(options): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:523

Registers or reconfigures the model.

Parameters

options

AmbitenModelOptions<T>

Model registration options.

Returns

Promise<void>

removeListener()

removeListener(event, listener): void

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:451

Removes a specific event listener.

Parameters

event

Event type.

listener

(...args) => void

Event listener callback.

Returns

void

restoreMany()

restoreMany(filter, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5213

Restores multiple soft-deleted documents matching the provided filter.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered restore middlewares, triggers schema update hooks, invalidates relevant cache patterns, and publishes a document restoration event after completion.

The actual restore behavior is driven by the update document returned from buildRestoreUpdate.

Parameters

filter

Filter<T>

MongoDB filter used to identify the documents to restore.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the operation completes.

Throws

When the filter is missing or invalid.

restoreOne()

restoreOne(filter, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5063

Restores a single soft-deleted document matching the provided filter.

The actual restore behavior is driven by the update document returned from buildRestoreUpdate.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to restore.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the operation completes.

Throws

When the filter is missing or invalid.

runCommand()

runCommand(command, ...args): Promise<any>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4411

Runs a custom command on the collection.

Parameters

command

string

The command to run.

args

...any[]

The arguments for the command.

Returns

Promise<any>

The result of the command.

runGC()

runGC(ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4434

Runs garbage collection for expired documents in the model collection.

This operation uses the model GC configuration to locate expired documents and either soft-delete them or permanently delete them. When configured, expired documents may be archived before deletion.

The operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered GC-related middlewares, triggers schema update/delete hooks as appropriate, invalidates relevant cache patterns, and publishes a garbage collection event after completion.

Parameters

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when garbage collection completes.

runInTransaction()

runInTransaction<R>(operation, ctx?): Promise<R>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3825

Executes the provided operation inside a transaction-aware Ambiten runtime context.

This helper ensures the operation runs with a resolved MongoDB client session and within the active Ambiten runtime context for the current tenant, database, and collection. If a session already exists in the merged model context, that session is reused and no new transaction boundary is created.

Use this method when multiple model operations must be executed atomically within a single transactional unit of work.

Type Parameters

R

R

The operation result type.

Parameters

operation

(session) => Promise<R>

Callback executed with the resolved MongoDB client session.

ctx?

Optional model execution context for tenant, database, collection, and session overrides.

Returns

Promise<R>

The resolved result of the transactional operation.

setSoftDeleteConfig()

setSoftDeleteConfig(config): void

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:5396

Parameters

config

deletedAtField

string

isDeletedField

string

Returns

void

startAutoGC()

startAutoGC(intervalMs?): void

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4669

Starts the automatic garbage collection process.

Parameters

intervalMs?

number = 3600000

The interval in milliseconds for the garbage collection to run.

Returns

void

streamAggregation()

streamAggregation<U>(pipeline, options?, ctx?): Promise<Readable & AsyncIterable<U, any, any>>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:3871

Creates a readable stream for an aggregation pipeline.

This method runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered aggregate middlewares, triggers schema aggregate hooks, and publishes a database change event after the aggregation stream is created.

This method instruments stream creation only. It does not track the full lifecycle of stream consumption unless additional listeners are attached by the caller or by a higher-level observability layer.

Type Parameters

U

U extends Document

The aggregation result document shape.

Parameters

pipeline

object[]

MongoDB aggregation pipeline stages.

options?

AggregateOptions = {}

Optional MongoDB aggregation options.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<Readable & AsyncIterable<U, any, any>>

A readable stream for the aggregation result set.

Throws

When the pipeline is missing or invalid.

updateOne()

updateOne(filter, update, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:1158

Updates a single document matching the provided filter.

This operation runs inside the active Ambiten runtime context, is instrumented through measureQuery, executes registered update middlewares, triggers schema update hooks, invalidates relevant cache patterns, and publishes a database change event after completion.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to update.

update

UpdateFilter<T>

MongoDB update document to apply.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when the operation completes.

Throws

When the filter is missing or invalid.

Throws

When the update document is missing or invalid.

updateWithTransaction()

updateWithTransaction(filter, update, ctx?): Promise<ModelResult<T> | null>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:2386

Updates a single document inside a transaction-aware runtime context.

This transactional variant runs within the active Ambiten runtime context, executes registered update middlewares, validates the projected updated document, triggers schema update hooks with transactional metadata, invalidates relevant cache patterns, and publishes a database change event after completion.

Parameters

filter

Filter<T>

MongoDB filter used to identify the document to update.

update

UpdateFilter<T>

MongoDB update document to apply.

ctx?

Optional model execution context for tenant, database, collection, session, and transaction-aware runtime overrides.

Returns

Promise<ModelResult<T> | null>

The updated document as a normalized model result, or null if no document matched the filter.

Throws

When the filter is missing or invalid.

Throws

When the update document is missing or invalid.

validateAsync()

validateAsync(doc): Promise<T>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:606

Validates a document asynchronously against the model schema. Useful for schemas that perform async validation, such as checking uniqueness

Parameters

doc

OptionalUnlessRequiredId<T>

Document to validate.

Returns

Promise<T>

The validated document.

warmCache()

warmCache(queries?, defaultTtl?, ctx?): Promise<void>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4946

Warms cache entries for selected model queries.

When query definitions are provided, this helper executes the corresponding find operations and stores the results using Ambiten's scoped cache key strategy. When no queries are provided, it warms a default collection-wide find({}) cache entry, subject to a safety threshold for large collections.

This helper is best suited for controlled cache priming scenarios such as startup warmup, scheduled maintenance, or high-traffic query preparation.

Parameters

queries?

object[]

Optional list of query definitions to warm.

defaultTtl?

number = 3600

Default TTL in seconds for warmed entries.

ctx?

Optional model execution context for tenant, database, collection, session, and related runtime overrides.

Returns

Promise<void>

A promise that resolves when cache warming completes.

Throws

When cache warming fails.

watchChanges()

watchChanges(callback, ctx?): Promise<ChangeStream<T, ChangeStreamDocument<T>>>

Defined in: packages/core/src/lib-core/ambitenModelFactory.ts:4066

Opens a MongoDB change stream on the model collection and registers a change callback.

This helper initializes the model, resolves the collection within the active Ambiten runtime context, creates a change stream, and subscribes the provided callback to "change" events.

The method is intentionally lightweight: it manages change stream creation, but does not yet instrument the full lifecycle of emitted change events. That can be added later by higher-level observability or evidence collection layers.

Parameters

callback

(change) => void

Function invoked whenever a change event is emitted by the collection change stream.

ctx?