@ambiten/core 1.0.0

package/dist/lib-core/ambitenModelFactory.d.ts

@@ -0,0 +1,979 @@
+import 'dotenv/config';
+import { Filter, OptionalUnlessRequiredId, UpdateFilter, AggregateOptions, ClientSession, AnyBulkWriteOperation, ChangeStreamDocument, ChangeStream, BulkWriteOptions, BulkWriteResult } from 'mongodb';
+import type { User, Document, AmbitenModelOptions, EventType, ModelContext, ModelResult, ModelResultArray, AmbitenMiddlewareOperation, AmbitenMiddlewareHandler, QueryOptions, AmbitenCacheStats } from '../types';
+import { AmbitenSchema } from './ambitenSchema';
+/**
+ * A MongoDB-backed model with schema validation, middleware, multi-tenancy,
+ * transactions, caching, soft-delete support, and query instrumentation.
+ *
+ * @typeParam T - The MongoDB document shape handled by this model.
+ */
+export declare class AmbitenModel<T extends Document> {
+    private _provider;
+    private _collectionName;
+    private _collectionOverride?;
+    private _schema;
+    private _initialized;
+    private _defaultCtx?;
+    private readonly _modelGCConfig?;
+    private readonly _gcConfig?;
+    private _gcTimer?;
+    private eventEmitter;
+    private beforeMiddlewares;
+    private afterMiddlewares;
+    private _softDeleteConfig?;
+    /**
+     * Creates a new model instance.
+     *
+     * @param options - Model configuration including collection, schema, provider,
+     * default context, and optional GC configuration.
+     */
+    constructor(options: AmbitenModelOptions<T>);
+    /**
+     * Merges an explicit operation context with the model default context and the
+     * current runtime context.
+     *
+     * @param ctx - Optional operation context.
+     * @returns A merged context or `undefined` when no context values are present.
+     */
+    private mergeCtx;
+    /**
+     * Ensures a runtime Ambiten context exists before executing an instrumented action.
+     *
+     * This allows model methods to remain safe when invoked outside adapter-managed
+     * request lifecycles while still preserving tenant-aware instrumentation.
+     *
+     * @param ctx - Optional model context.
+     * @param action - The action to execute inside a runtime context.
+     * @returns The action result.
+     */
+    private runWithModelContext;
+    private isGCEnabled;
+    private resolveSchemaGCConfig;
+    /**
+     * Resolves the MongoDB collection for the current model and context.
+     *
+     * @param ctx - Optional model context.
+     * @returns The resolved MongoDB collection.
+     */
+    private getCollection;
+    /**
+     * Resolves a registered tenant configuration.
+     *
+     * @param tenantId - The tenant identifier.
+     * @returns The tenant configuration.
+     */
+    private getResolvedTenant;
+    /**
+     * Resolves the MongoDB database for the current operation.
+     *
+     * @param ctx - Optional model context.
+     * @returns The resolved MongoDB database instance.
+     */
+    private resolveDb;
+    /**
+     * Resolves the collection name for the current operation.
+     *
+     * @param ctx - Optional model context.
+     * @returns The collection name.
+     */
+    private resolveCollectionName;
+    /**
+     * Resolves the client session for the current operation.
+     *
+     * @param ctx - Optional model context.
+     * @returns The MongoDB client session if available.
+     */
+    private resolveSession;
+    /**
+   * Resolves the MongoDB client session to use for an operation.
+   *
+   * Precedence order:
+   * 1. Explicit externally supplied session
+   * 2. Per-call model context session
+   * 3. Active runtime session from AmbitenContext
+   *
+   * This ensures explicit caller intent always overrides implicit runtime state.
+   *
+   * @param ctx - Optional model execution context.
+   * @param externalSession - Optional explicit session supplied by the caller.
+   * @returns The resolved MongoDB client session, or `undefined` when no session is available.
+   */
+    private resolveSessionStrict;
+    /**
+     * Subscribes to a model event.
+     *
+     * @param event - Event type.
+     * @param listener - Event listener callback.
+     */
+    on(event: EventType, listener: (...args: any[]) => void): void;
+    /**
+     * Subscribes to a model event once.
+     *
+     * @param event - Event type.
+     * @param listener - Event listener callback.
+     */
+    once(event: EventType, listener: (...args: any[]) => void): void;
+    /**
+     * Removes a subscribed event listener.
+     *
+     * @param event - Event type.
+     * @param listener - Event listener callback.
+     */
+    off(event: EventType, listener: (...args: any[]) => void): void;
+    /**
+     * Removes a specific event listener.
+     *
+     * @param event - Event type.
+     * @param listener - Event listener callback.
+     */
+    removeListener(event: EventType, listener: (...args: any[]) => void): void;
+    /**
+     * Ensures the model has the minimum configuration required to operate.
+     */
+    private ensureConfigured;
+    /**
+     * Initializes the model by validating configuration, resolving the collection,
+     * and creating the GC TTL index when enabled.
+     */
+    init(): Promise<void>;
+    /**
+     * Returns a model instance bound to a default context.
+     *
+     * @param ctx - Context to bind to the cloned model.
+     * @returns A cloned model instance with merged default context.
+     */
+    bind(ctx: ModelContext): AmbitenModel<T>;
+    /**
+     * Registers or reconfigures the model.
+     *
+     * @param options - Model registration options.
+     */
+    registerModel(options: AmbitenModelOptions<T>): Promise<void>;
+    /**
+     * Ensures the TTL index used by the garbage collector exists.
+     *
+     * @param gc - GC configuration.
+     */
+    private ensureGCIndex;
+    /**
+     * Returns the schema attached to this model.
+     */
+    get schema(): AmbitenSchema<T>;
+    /**
+     * Returns the schema attached to this model.
+     */
+    getSchema(): AmbitenSchema<T>;
+    /**
+     * Validates a document against the model schema.
+     * Throws an error if validation fails.
+     * @param doc - Document to validate.
+     */
+    private validate;
+    /**
+     * Validates a document asynchronously against the model schema.
+     * Useful for schemas that perform async validation, such as checking uniqueness
+     * @param doc - Document to validate.
+     * @returns The validated document.
+     */
+    validateAsync(doc: OptionalUnlessRequiredId<T>): Promise<T>;
+    /**
+     * Initializes internal schema middleware for relationships, aggregation, and
+     * change notifications. This is called during model initialization and ensures that all registered
+     * middleware is set up before any operations are performed.
+     */
+    private initMiddleware;
+    /**
+     * Creates a new document in the model collection.
+     *
+     * This operation runs inside the active Ambiten runtime context, is instrumented
+     * through {@link 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.
+     *
+     * @param doc - The document to insert.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @returns The created document as a normalized model result.
+     * @throws {Error} When the provided document is missing or invalid.
+     */
+    create(doc: OptionalUnlessRequiredId<T>, ctx?: ModelContext): Promise<ModelResult<T>>;
+    /**
+   * Finds documents matching the provided filter.
+   *
+   * This operation runs inside the active Ambiten runtime context, is instrumented
+   * through {@link measureQuery}, executes registered find middlewares, supports
+   * optional result caching, triggers schema find hooks, and returns normalized
+   * model results.
+   *
+   * @param filter - MongoDB filter used to match documents.
+   * @param ctx - Optional model execution context for tenant, database,
+   * collection, session, and related runtime overrides.
+   * @param options - Optional query-level features such as caching.
+   * @returns An array of normalized model results.
+   * @throws {Error} When the filter is invalid.
+   */
+    find(filter?: Filter<T>, ctx?: ModelContext, options?: QueryOptions): Promise<ModelResultArray<T>>;
+    /**
+   * Finds a single document matching the provided filter.
+   *
+   * This operation runs inside the active Ambiten runtime context, is instrumented
+   * through {@link measureQuery}, executes registered findOne middlewares,
+   * supports optional result caching, triggers schema find hooks, and returns a
+   * normalized model result when a document is found.
+   *
+   * @param filter - MongoDB filter used to match the document.
+   * @param ctx - Optional model execution context for tenant, database,
+   * collection, session, and related runtime overrides.
+   * @param options - Optional query-level features such as caching.
+   * @returns The matched document as a normalized model result, or `null` if no document matched.
+   * @throws {Error} When the filter is missing or invalid.
+   */
+    findOne(filter: Filter<T>, ctx?: ModelContext, options?: QueryOptions): Promise<ModelResult<T> | null>;
+    /**
+    * Updates a single document matching the provided filter.
+    *
+    * This operation runs inside the active Ambiten runtime context, is instrumented
+    * through {@link measureQuery}, executes registered update middlewares,
+    * triggers schema update hooks, invalidates relevant cache patterns, and
+    * publishes a database change event after completion.
+    *
+    * @param filter - MongoDB filter used to identify the document to update.
+    * @param update - MongoDB update document to apply.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and related runtime overrides.
+    * @returns A promise that resolves when the operation completes.
+    * @throws {Error} When the filter is missing or invalid.
+    * @throws {Error} When the update document is missing or invalid.
+    */
+    updateOne(filter: Filter<T>, update: UpdateFilter<T>, ctx?: ModelContext): Promise<void>;
+    /**
+     * Inserts multiple documents into the model collection.
+     *
+     * This operation runs inside the active Ambiten runtime context, is instrumented
+     * through {@link 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.
+     *
+     * @param docs - The documents to insert.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @returns A promise that resolves when the operation completes.
+     */
+    bulkInsert(docs: OptionalUnlessRequiredId<T>[], ctx?: ModelContext): Promise<void>;
+    /**
+     * Updates multiple documents using MongoDB bulk write semantics.
+     *
+     * This operation runs inside the active Ambiten runtime context, is instrumented
+     * through {@link 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.
+     *
+     * @param updates - Array of filter/update pairs to execute as bulk updates.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @returns A promise that resolves when the operation completes.
+     * @throws {Error} When the updates payload is invalid.
+     */
+    bulkUpdate(updates: {
+        filter: Partial<T>;
+        update: Partial<T>;
+    }[], ctx?: ModelContext): Promise<void>;
+    /**
+    * Deletes a single document matching the provided filter.
+    *
+    * This operation runs inside the active Ambiten runtime context, is instrumented
+    * through {@link 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.
+    *
+    * @param filter - MongoDB filter used to identify the document to delete.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and related runtime overrides.
+    * @returns A promise that resolves when the operation completes.
+    * @throws {Error} When the filter is missing or invalid.
+    * @throws {Error} When soft delete is enabled but no softDeleteUpdate payload is provided.
+    */
+    deleteOne(filter: Filter<T>, ctx?: ModelContext): Promise<void>;
+    /**
+    * Deletes multiple documents matching the provided filter.
+    *
+    * This operation runs inside the active Ambiten runtime context, is instrumented
+    * through {@link 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.
+    *
+    * @param filter - MongoDB filter used to identify the documents to delete.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and related runtime overrides.
+    * @returns A promise that resolves when the operation completes.
+    * @throws {Error} When the filter is missing or invalid.
+    * @throws {Error} When soft delete is enabled but no softDeleteUpdate payload is provided.
+    */
+    deleteMany(filter: Filter<T>, ctx?: ModelContext): Promise<void>;
+    /**
+     * 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.
+     *
+     * @typeParam K - The related model document type.
+     * @param doc - The source document containing the reference field.
+     * @param field - The field on the source document that stores the related document identifier.
+     * @param relatedModel - The model used to resolve the related document.
+     * @returns The source document with the populated field replaced by the related
+     * document result, or `null` when the input document is invalid.
+     */
+    populateOne<K extends Document>(doc: T, field: keyof T, relatedModel: AmbitenModel<K>): Promise<(T & Record<string, unknown>) | null>;
+    /**
+    * 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.
+    *
+    * @typeParam K - The related model document type.
+    * @param doc - The source document containing the reference array field.
+    * @param field - The field on the source document that stores related document identifiers.
+    * @param relatedModel - The model used to resolve the related documents.
+    * @returns The source document with the populated field replaced by the related
+    * document results, or `null` when the input document is invalid.
+    */
+    populateMany<K extends Document>(doc: T, field: keyof T, relatedModel: AmbitenModel<K>): Promise<(T & Record<string, unknown>) | null>;
+    /**
+   * 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.
+   *
+   * @param doc - The document to insert.
+   * @param ctx - Optional model execution context for tenant, database,
+   * collection, session, and transaction-aware runtime overrides.
+   * @returns The created document as a normalized model result.
+   * @throws {Error} When the provided document is missing or invalid.
+   */
+    createWithTransaction(doc: OptionalUnlessRequiredId<T>, ctx?: ModelContext): Promise<ModelResult<T>>;
+    /**
+   * 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.
+   *
+   * @param operations - MongoDB bulk write operations to execute.
+   * @param options - Optional MongoDB bulk write options.
+   * @param ctx - Optional model execution context for tenant, database,
+   * collection, session, and transaction-aware runtime overrides.
+   * @returns The MongoDB bulk write result.
+   * @throws {Error} When the operations payload is missing or invalid.
+   */
+    bulkWriteWithTransaction(operations: AnyBulkWriteOperation<T>[], options?: BulkWriteOptions, ctx?: ModelContext): Promise<BulkWriteResult>;
+    /**
+   * 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.
+   *
+   * @param filter - MongoDB filter used to identify the document to delete.
+   * @param ctx - Optional model execution context for tenant, database,
+   * collection, session, and transaction-aware runtime overrides.
+   * @returns `true` when a document was deleted, otherwise `false`.
+   * @throws {Error} When the filter is missing or invalid.
+   */
+    deleteWithTransaction(filter: Filter<T>, ctx?: ModelContext): Promise<boolean>;
+    /**
+    * 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.
+    *
+    * @param filter - MongoDB filter used to identify the document to update.
+    * @param update - MongoDB update document to apply.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and transaction-aware runtime overrides.
+    * @returns The updated document as a normalized model result, or `null` if no
+    * document matched the filter.
+    * @throws {Error} When the filter is missing or invalid.
+    * @throws {Error} When the update document is missing or invalid.
+    */
+    updateWithTransaction(filter: Filter<T>, update: UpdateFilter<T>, ctx?: ModelContext): Promise<ModelResult<T> | null>;
+    /**
+   * Finds a single document matching the provided filter and updates it.
+   *
+   * This operation runs inside the active Ambiten runtime context, is instrumented
+   * through {@link 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.
+   *
+   * @param filter - MongoDB filter used to identify the document to update.
+   * @param update - MongoDB update document to apply.
+   * @param ctx - Optional model execution context for tenant, database,
+   * collection, session, and related runtime overrides.
+   * @returns The updated document as a normalized model result, or `null` if no
+   * document matched the filter.
+   * @throws {Error} When the filter is missing or invalid.
+   * @throws {Error} When the update document is missing or invalid.
+   */
+    findOneAndUpdate(filter: Filter<T>, update: UpdateFilter<T>, ctx?: ModelContext): Promise<ModelResult<T> | null>;
+    /**
+   * 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 {@link 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
+   *
+   * @param filter - MongoDB filter used to identify the document to delete.
+   * @param ctx - Optional model execution context for tenant, database,
+   * session, cache, and collection overrides.
+   * @returns The deleted document as a model result, or `null` if no document matched.
+   * @throws {Error} When the filter is missing or invalid.
+   */
+    findOneAndDelete(filter: Filter<T>, ctx?: ModelContext): Promise<ModelResult<T> | null>;
+    /**
+    * 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.
+    *
+    * @param filter - MongoDB filter used to identify the document to replace.
+    * @param replacement - The full replacement document that will overwrite the matched document.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and related runtime overrides.
+    * @returns The replaced document in its updated form, or `null` if no document matched the filter.
+    * @throws {Error} When the filter is missing or invalid.
+    * @throws {Error} When the replacement document fails validation.
+    */
+    findOneAndReplace(filter: Filter<T>, replacement: T, ctx?: ModelContext): Promise<ModelResult<T> | null>;
+    /**
+    * 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 {@link measureQuery}, executes registered model middlewares, triggers
+    * schema update hooks, invalidates relevant cache patterns, and publishes a
+    * database change event after completion.
+    *
+    * @param filter - MongoDB filter used to identify the document to update or insert.
+    * @param update - MongoDB update document applied to the matched document or to the inserted document during upsert.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and related runtime overrides.
+    * @returns The updated or newly upserted document in its final state, or `null`
+    * if no document could be resolved from the operation result.
+    * @throws {Error} When the filter is missing or invalid.
+    * @throws {Error} When the update document is missing or invalid.
+    */
+    findOneAndUpsert(filter: Filter<T>, update: UpdateFilter<T>, ctx?: ModelContext): Promise<ModelResult<T> | null>;
+    /**
+     * 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.
+     *
+     * @param filter - MongoDB filter used to identify the document to update or insert.
+     * @param update - MongoDB update document applied to the matched document or inserted document.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and transaction-aware runtime overrides.
+     * @returns The updated or newly inserted document in its final state, or `null`
+     * if no document could be resolved from the operation result.
+     * @throws {Error} When the filter is missing or invalid.
+     * @throws {Error} When the update document is missing or invalid.
+     */
+    findOneAndUpsertWithTransaction(filter: Filter<T>, update: UpdateFilter<T>, ctx?: ModelContext): Promise<ModelResult<T> | null>;
+    /**
+    * 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.
+    *
+    * @param filter - MongoDB filter used to identify the document to update or insert.
+    * @param update - MongoDB update document applied to the matched document or inserted document.
+    * @param user - Authenticated user performing the operation. Must have the `admin` role.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and transaction-aware runtime overrides.
+    * @returns The updated or newly inserted document in its final state, or `null`
+    * if no document could be resolved from the operation result.
+    * @throws {Error} When the user is not authorized to perform the operation.
+    * @throws {Error} When the filter is missing or invalid.
+    * @throws {Error} When the update document is missing or invalid.
+    */
+    findOneAndUpsertWithTransactionSecure(filter: Filter<T>, update: UpdateFilter<T>, user: User, ctx?: ModelContext): Promise<ModelResult<T> | null>;
+    /**
+     * 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
+     * {@link 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.
+     *
+     * @param filter - MongoDB filter used to identify the document to delete.
+     * @param user - Authenticated user performing the operation. Must have the `admin` role.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @returns A promise that resolves when the operation completes.
+     * @throws {Error} When the user is not authorized to perform the operation.
+     * @throws {Error} When the filter is missing or invalid.
+     * @throws {Error} When the user payload is missing.
+     */
+    deleteSecure(filter: Filter<T>, user: User, ctx?: ModelContext): Promise<void>;
+    /**
+     * Executes an aggregation pipeline against the model collection.
+     *
+     * This operation runs inside the active Ambiten runtime context, is instrumented
+     * through {@link measureQuery}, executes registered aggregate middlewares,
+     * supports optional query-result caching, and publishes a database change event
+     * after execution.
+     *
+     * When caching is enabled through {@link QueryOptions}, the aggregation result
+     * is stored and reused using a tenant-aware cache key derived from the
+     * collection, pipeline, options, and runtime context.
+     *
+     * @typeParam U - The aggregation result document shape.
+     * @param pipeline - MongoDB aggregation pipeline stages.
+     * @param options - Optional MongoDB aggregation options.
+     * @param externalSession - Optional explicit client session to use for the aggregation.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @param queryOptions - Optional query-level features such as caching.
+     * @returns The aggregation result array.
+     * @throws {Error} When the pipeline is missing or invalid.
+     */
+    aggregate<U extends Document>(pipeline: object[], options?: AggregateOptions, externalSession?: ClientSession, ctx?: ModelContext, queryOptions?: QueryOptions): Promise<U[]>;
+    /**
+     * 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 {@link measureQuery}, and publishes a database
+     * change event after execution.
+     *
+     * @typeParam U - The aggregation result document shape.
+     * @param pipeline - MongoDB aggregation pipeline stages.
+     * @param options - Optional MongoDB aggregation options.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and transaction-aware runtime overrides.
+     * @returns The aggregation result array.
+     * @throws {Error} When the pipeline is missing or invalid.
+     */
+    aggregateWithTransaction<U extends Document>(pipeline: object[], options?: AggregateOptions, ctx?: ModelContext): Promise<U[]>;
+    /**
+    * Executes the provided operation within a transaction-aware runtime context.
+    *
+    * Resolution order:
+    * 1. Reuse an existing session from the merged model context when available.
+    * 2. Start a provider-managed session when the active database provider
+    *    exposes a session factory.
+    * 3. Fall back to {@link AmbitenContext.withTransaction} to resolve a client
+    *    and execute the operation inside a transaction.
+    *
+    * When an existing session is supplied, the current transaction boundary is
+    * reused and no new transaction is started.
+    *
+    * @typeParam R - The operation result type.
+    * @param operation - Callback executed with the resolved MongoDB client session.
+    * @param ctx - Optional model execution context used to resolve tenant,
+    * database, collection, and session overrides.
+    * @returns The resolved operation result.
+    */
+    private withTransaction;
+    /**
+   * 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.
+   *
+   * @typeParam R - The operation result type.
+   * @param operation - Callback executed with the resolved MongoDB client session.
+   * @param ctx - Optional model execution context for tenant, database,
+   * collection, and session overrides.
+   * @returns The resolved result of the transactional operation.
+   */
+    runInTransaction<R>(operation: (session: ClientSession) => Promise<R>, ctx?: ModelContext): Promise<R>;
+    private getSession;
+    /**
+     * Creates a readable stream for an aggregation pipeline.
+     *
+     * This method runs inside the active Ambiten runtime context, is instrumented
+     * through {@link 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.
+     *
+     * @typeParam U - The aggregation result document shape.
+     * @param pipeline - MongoDB aggregation pipeline stages.
+     * @param options - Optional MongoDB aggregation options.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @returns A readable stream for the aggregation result set.
+     * @throws {Error} When the pipeline is missing or invalid.
+     */
+    streamAggregation<U extends Document>(pipeline: object[], options?: AggregateOptions, ctx?: ModelContext): Promise<import("stream").Readable & AsyncIterable<U>>;
+    /**
+     * Aggregates documents in the collection using a pipeline with caching.
+     * @param {object[]} pipeline - The aggregation pipeline.
+     * @param {string} cacheKey - The cache key.
+     * @param {number} [cacheDuration=300] - The cache duration in seconds.
+     * @returns {Promise<T[]>} The aggregation result as an array.
+     * @throws {Error} If the pipeline is not valid or the cache key is not a string.
+     */
+    aggregateWithCache(pipeline: object[], cacheKey: string, cacheDuration?: number): Promise<T[]>;
+    /**
+     * Cursor-based pagination using _id comparison instead of skip.
+     * @param filter - The filter for documents.
+     * @param pageSize - Number of documents per page.
+     * @param lastId - 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.
+     *
+     */
+    paginatedFind(filter: Partial<T>, pageSize: number, lastId?: string): Promise<T[]>;
+    /**
+     * 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.
+     *
+     * @param callback - Function invoked whenever a change event is emitted by the collection change stream.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @returns The active MongoDB change stream.
+     * @throws {Error} When the callback is not a valid function.
+     */
+    watchChanges(callback: (change: ChangeStreamDocument<T>) => void, ctx?: ModelContext): Promise<ChangeStream<T>>;
+    /**
+    * Creates an index on the model collection.
+    *
+    * @param fields - Index field specification where each key maps to ascending
+    * (`1`) or descending (`-1`) index order.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and related runtime overrides.
+    * @returns A promise that resolves when the index has been created.
+    * @throws {Error} When the field specification is missing or invalid.
+    */
+    createIndex(fields: Partial<Record<keyof T, 1 | -1>>, ctx?: ModelContext): Promise<void>;
+    /**
+     * Drops an index from the collection by its name.
+     * @param {string} indexName - The name of the index to drop.
+     * @returns {Promise<void>} Resolves when the index is dropped.
+     */
+    dropIndex(indexName: string): Promise<void>;
+    private invalidateCachePatterns;
+    /**
+     * Invalidates all cache entries matching the provided Redis key pattern.
+     *
+     * This method uses Redis `SCAN` to iterate over matching keys in batches and
+     * deletes them using a pipelined multi-operation for better efficiency.
+     *
+     * @param pattern - Redis key pattern to invalidate.
+     * @returns The number of successfully deleted keys.
+     * @throws {Error} When the pattern is invalid or cache invalidation fails.
+     */
+    static invalidatePattern(pattern: string): Promise<number>;
+    getContext(): {
+        ctx: ModelContext;
+    };
+    /**
+     * 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.
+     *
+     * @param pattern - Partial cache pattern (e.g. "find:*", "aggregate:*").
+     * @param ctx - Optional model execution context.
+     * @returns Number of deleted cache entries.
+     * @throws {Error} When the pattern is invalid.
+     */
+    invalidateModelPattern(pattern: string, ctx?: ModelContext): Promise<number>;
+    /**
+     * 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.
+     *
+     * @param doc - The document whose cache entries should be invalidated.
+     * @param ctx - Optional model execution context.
+     * @returns A promise that resolves when invalidation completes.
+     * @throws {Error} When the document is missing a valid `_id`.
+     */
+    invalidateDocumentCache(doc: T, ctx?: ModelContext): Promise<number>;
+    /**
+     * Returns cache statistics for the active Redis cache backend.
+     *
+     * This helper retrieves Redis memory and keyspace statistics, along with Ambiten
+     * cache hit/miss counters. When a tenant identifier is provided, it also counts
+     * cache keys scoped to that tenant within the Ambiten cache namespace.
+     *
+     * @param tenantId - Optional tenant identifier used to count tenant-scoped cache keys.
+     * @returns Cache statistics for the current Redis backend.
+     * @throws {Error} When cache statistics cannot be retrieved.
+     */
+    static getCacheStats(tenantId?: string): Promise<AmbitenCacheStats>;
+    /**
+     * Runs a custom command on the collection.
+     * @param {string} command - The command to run.
+     * @param {...any} args - The arguments for the command.
+     * @returns {Promise<any>} The result of the command.
+     */
+    runCommand(command: string, ...args: any[]): Promise<any>;
+    /**
+     * 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 {@link 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.
+     *
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @returns A promise that resolves when garbage collection completes.
+     */
+    runGC(ctx?: ModelContext): Promise<void>;
+    /**
+     * Starts the automatic garbage collection process.
+     * @param {number} intervalMs - The interval in milliseconds for the garbage collection to run.
+     */
+    startAutoGC(intervalMs?: number): void;
+    /**
+   * Resolves instrumentation context for model operations by combining explicit
+   * model context with the active runtime context.
+   *
+   * This helper is used to provide stable metadata for logging, observers,
+   * tracing, and query instrumentation.
+   *
+   * @param ctx - Optional model execution context.
+   * @returns Resolved instrumentation metadata for the current operation.
+   */
+    private resolveInstrumentationContext;
+    /**
+   * Builds normalized operation metadata by merging existing middleware metadata
+   * with operation-specific overrides.
+   *
+   * @param base - Existing operation metadata.
+   * @param overrides - Additional metadata flags or values to apply.
+   * @returns Normalized operation metadata.
+   */
+    private buildOperationMeta;
+    /**
+   * Builds a normalized hook payload for schema middleware and instrumentation.
+   *
+   * @param operation - Operation name.
+   * @param ctx - Optional model execution context.
+   * @param payload - Additional hook payload fields.
+   * @returns Normalized hook payload.
+   */
+    private buildHookPayload;
+    /**
+   * Resolves a cache adapter for the current query options.
+   *
+   * This helper returns a lightweight Redis-backed cache interface when caching
+   * is enabled in the provided query options. Cache failures are treated as
+   * non-fatal so query execution can continue even when Redis is unavailable or
+   * a cache payload is invalid.
+   *
+   * @param options - Optional query options that may enable caching.
+   * @returns A cache adapter when caching is enabled, otherwise `null`.
+   */
+    private resolveCache;
+    /**
+   * Builds a deterministic cache key for a query operation.
+   *
+   * The cache key is scoped by tenant, database, collection, and operation, and
+   * uses a normalized serialized payload to ensure stable cache identity across
+   * semantically equivalent query inputs.
+   *
+   * @param operation - Query operation name.
+   * @param payload - Cache identity payload for the operation.
+   * @returns A deterministic tenant-aware cache key.
+   */
+    private buildCacheKey;
+    private static trackCacheMiss;
+    private static trackCacheHit;
+    static cacheResult<R>(key: string, data: R, ttl?: number): Promise<void>;
+    /**
+     * Clears a cached result by its key.
+     * @param {string} key - The cache key.
+     * @returns {Promise<void>} Resolves when the cache is cleared.
+     */
+    static clearCache(key: string): Promise<void>;
+    /**
+   * 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.
+   *
+   * @param queries - Optional list of query definitions to warm.
+   * @param defaultTtl - Default TTL in seconds for warmed entries.
+   * @param ctx - Optional model execution context for tenant, database,
+   * collection, session, and related runtime overrides.
+   * @returns A promise that resolves when cache warming completes.
+   * @throws {Error} When cache warming fails.
+   */
+    warmCache(queries?: {
+        filter?: Partial<T>;
+        ttl?: number;
+    }[], defaultTtl?: number, ctx?: ModelContext): Promise<void>;
+    private sortObjectDeep;
+    private toModelResult;
+    private toModelResults;
+    /**
+    * Restores a single soft-deleted document matching the provided filter.
+    *
+    * This operation runs inside the active Ambiten runtime context, is instrumented
+    * through {@link 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
+    * {@link buildRestoreUpdate}.
+    *
+    * @param filter - MongoDB filter used to identify the document to restore.
+    * @param ctx - Optional model execution context for tenant, database,
+    * collection, session, and related runtime overrides.
+    * @returns A promise that resolves when the operation completes.
+    * @throws {Error} When the filter is missing or invalid.
+    */
+    restoreOne(filter: Filter<T>, ctx?: ModelContext): Promise<void>;
+    /**
+     * Restores multiple soft-deleted documents matching the provided filter.
+     *
+     * This operation runs inside the active Ambiten runtime context, is instrumented
+     * through {@link 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
+     * {@link buildRestoreUpdate}.
+     *
+     * @param filter - MongoDB filter used to identify the documents to restore.
+     * @param ctx - Optional model execution context for tenant, database,
+     * collection, session, and related runtime overrides.
+     * @returns A promise that resolves when the operation completes.
+     * @throws {Error} When the filter is missing or invalid.
+     */
+    restoreMany(filter: Filter<T>, ctx?: ModelContext): Promise<void>;
+    private buildRestoreUpdate;
+    private buildMiddlewareContext;
+    setSoftDeleteConfig(config: {
+        deletedAtField: string;
+        isDeletedField: string;
+    }): void;
+    /**
+   * Builds the update document used for soft delete operations.
+   *
+   * The generated update sets the configured deleted timestamp field and
+   * deleted-state flag field to mark the document as logically deleted without
+   * physically removing it from the collection.
+   *
+   * @returns MongoDB update document for soft delete flows.
+   */
+    private buildSoftDeleteUpdate;
+    private runBeforeMiddlewares;
+    private runAfterMiddlewares;
+    before(operation: AmbitenMiddlewareOperation, handler: AmbitenMiddlewareHandler<T>): this;
+    after(operation: AmbitenMiddlewareOperation, handler: AmbitenMiddlewareHandler<T>): this;
+    beforeFind(handler: AmbitenMiddlewareHandler<T>): this;
+    afterFind(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeFindOne(handler: AmbitenMiddlewareHandler<T>): this;
+    afterFindOne(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeSave(handler: AmbitenMiddlewareHandler<T>): this;
+    afterSave(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeUpdateOne(handler: AmbitenMiddlewareHandler<T>): this;
+    afterUpdateOne(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeDeleteOne(handler: AmbitenMiddlewareHandler<T>): this;
+    afterDeleteOne(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeDeleteMany(handler: AmbitenMiddlewareHandler<T>): this;
+    afterDeleteMany(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeBulkInsert(handler: AmbitenMiddlewareHandler<T>): this;
+    afterBulkInsert(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeBulkUpdate(handler: AmbitenMiddlewareHandler<T>): this;
+    afterBulkUpdate(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeAggregate(handler: AmbitenMiddlewareHandler<T>): this;
+    afterAggregate(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeFindOneAndUpdate(handler: AmbitenMiddlewareHandler<T>): this;
+    afterFindOneAndUpdate(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeFindOneAndDelete(handler: AmbitenMiddlewareHandler<T>): this;
+    afterFindOneAndDelete(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeFindOneAndReplace(handler: AmbitenMiddlewareHandler<T>): this;
+    afterFindOneAndReplace(handler: AmbitenMiddlewareHandler<T>): this;
+    beforeFindOneAndUpsert(handler: AmbitenMiddlewareHandler<T>): this;
+    afterFindOneAndUpsert(handler: AmbitenMiddlewareHandler<T>): this;
+}
+//# sourceMappingURL=ambitenModelFactory.d.ts.map