Class: AmbitenModel<T>

Returns

this

afterAggregate()

afterAggregate(handler): this

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

Parameters

handler

Returns

this

afterBulkInsert()

afterBulkInsert(handler): this

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

Parameters

handler

Returns

this

afterBulkUpdate()

afterBulkUpdate(handler): this

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

Parameters

handler

Returns

this

afterDeleteMany()

afterDeleteMany(handler): this

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

Parameters

handler

Returns

this

afterDeleteOne()

afterDeleteOne(handler): this

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

Parameters

handler

Returns

this

afterFind()

afterFind(handler): this

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

Parameters

handler

Returns

this

afterFindOne()

afterFindOne(handler): this

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

Parameters

handler

Returns

this

afterFindOneAndDelete()

afterFindOneAndDelete(handler): this

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

Parameters

handler

Returns

this

afterFindOneAndReplace()

afterFindOneAndReplace(handler): this

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

Parameters

handler

Returns

this

afterFindOneAndUpdate()

afterFindOneAndUpdate(handler): this

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

Parameters

handler

Returns

this

afterFindOneAndUpsert()

afterFindOneAndUpsert(handler): this

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

Parameters

handler

Returns

this

afterSave()

afterSave(handler): this

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

Parameters

handler

Returns

this

afterUpdateOne()

afterUpdateOne(handler): this

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

Parameters

handler

Returns

this

aggregate()

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

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

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:3932

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:3597

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:5394

Parameters

operation

handler

Returns

this

beforeAggregate()

beforeAggregate(handler): this

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

Parameters

handler

Returns

this

beforeBulkInsert()

beforeBulkInsert(handler): this

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

Parameters

handler

Returns

this

beforeBulkUpdate()

beforeBulkUpdate(handler): this

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

Parameters

handler

Returns

this

beforeDeleteMany()

beforeDeleteMany(handler): this

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

Parameters

handler

Returns

this

beforeDeleteOne()

beforeDeleteOne(handler): this

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

Parameters

handler

Returns

this

beforeFind()

beforeFind(handler): this

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

Parameters

handler

Returns

this

beforeFindOne()

beforeFindOne(handler): this

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

Parameters

handler

Returns

this

beforeFindOneAndDelete()

beforeFindOneAndDelete(handler): this

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

Parameters

handler

Returns

this

beforeFindOneAndReplace()

beforeFindOneAndReplace(handler): this

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

Parameters

handler

Returns

this

beforeFindOneAndUpdate()

beforeFindOneAndUpdate(handler): this

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

Parameters

handler

Returns

this

beforeFindOneAndUpsert()

beforeFindOneAndUpsert(handler): this

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

Parameters

handler

Returns

this

beforeSave()

beforeSave(handler): this

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

Parameters

handler

Returns

this

beforeUpdateOne()

beforeUpdateOne(handler): this

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

Parameters

handler

Returns

this

bind()

bind(ctx): AmbitenModel<T>

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

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:1221

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:1343

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:2073

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:703

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:4052

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:1952

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:1674

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:1501

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:3335

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:2202

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:4085

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:813

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:958

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:2621

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:2828

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:2486

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:2950

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:3072

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:3201

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:4191

Returns

object

ctx

ctx: ModelContext

getSchema()

getSchema(): AmbitenSchema<T>

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

Returns the schema attached to this model.

Returns

AmbitenSchema<T>

init()

init(): Promise<void>

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

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:4240

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:4206

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:392

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:372

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:382

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:3979

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:1910

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:1868

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:473

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:402

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:5161

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:5011

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:4359

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:4382

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:3773

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:5344

Parameters

config

deletedAtField

string

isDeletedField

string

Returns

void

startAutoGC()

startAutoGC(intervalMs?): void

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

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:3819

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:1106

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:2334

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:556

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:4894

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:4014

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?