monsqlize 3.1.14 → 3.3.0

package/dist/types/aggregation.d.mts

@@ -0,0 +1,58 @@
+/** Meta options for controlling timing/cache info in query results. */
+export interface MetaOptions {
+    /** 'op' = operation-level timing only; 'sub' = include sub-step timings (findPage only) */
+    level?: 'op' | 'sub';
+    /** Include cache hit/miss/ttl info in meta */
+    includeCache?: boolean;
+}
+
+/** v1-compatible aggregate options exported from the root package. */
+export interface AggregateOptions {
+    cache?: number;
+    maxTimeMS?: number;
+    allowDiskUse?: boolean;
+    collation?: any;
+    hint?: string | object;
+    comment?: string;
+    meta?: boolean | MetaOptions;
+}
+
+/**
+ * Options forwarded to the aggregate execution behind `vectorSearch()`.
+ * `meta`, `stream`, and `explain` are intentionally unavailable because
+ * `vectorSearch()` always resolves to a stable array of score envelopes.
+ */
+export interface VectorSearchAggregateOptions extends Omit<AggregateOptions, 'meta'> {
+    meta?: never;
+    stream?: never;
+    explain?: never;
+    [key: string]: unknown;
+}
+
+/** Options for a MongoDB `$vectorSearch` aggregation stage. */
+export interface VectorSearchOptions {
+    /** Name of the MongoDB Vector Search index. */
+    index: string;
+    /** Indexed vector field path. */
+    path: string;
+    /** Query embedding. Every value must be a finite number. */
+    queryVector: number[];
+    /** Maximum number of scored documents to return. */
+    limit: number;
+    /** Required for approximate nearest-neighbor search (`exact !== true`). */
+    numCandidates?: number;
+    /** Set to `true` to request exact nearest-neighbor search. */
+    exact?: boolean;
+    /** Optional MongoDB Vector Search pre-filter. */
+    filter?: Record<string, unknown>;
+    /** Fields to return from each matched document. */
+    projection?: Record<string, unknown> | string[];
+    /** Supported aggregate options; result-shape options are excluded. */
+    aggregateOptions?: VectorSearchAggregateOptions;
+}
+
+/** A vector-search result that preserves the source document and its score. */
+export interface VectorSearchHit<TDocument = unknown> {
+    document: TDocument;
+    score: number;
+}

package/dist/types/aggregation.d.ts

@@ -0,0 +1,58 @@
+/** Meta options for controlling timing/cache info in query results. */
+export interface MetaOptions {
+    /** 'op' = operation-level timing only; 'sub' = include sub-step timings (findPage only) */
+    level?: 'op' | 'sub';
+    /** Include cache hit/miss/ttl info in meta */
+    includeCache?: boolean;
+}
+
+/** v1-compatible aggregate options exported from the root package. */
+export interface AggregateOptions {
+    cache?: number;
+    maxTimeMS?: number;
+    allowDiskUse?: boolean;
+    collation?: any;
+    hint?: string | object;
+    comment?: string;
+    meta?: boolean | MetaOptions;
+}
+
+/**
+ * Options forwarded to the aggregate execution behind `vectorSearch()`.
+ * `meta`, `stream`, and `explain` are intentionally unavailable because
+ * `vectorSearch()` always resolves to a stable array of score envelopes.
+ */
+export interface VectorSearchAggregateOptions extends Omit<AggregateOptions, 'meta'> {
+    meta?: never;
+    stream?: never;
+    explain?: never;
+    [key: string]: unknown;
+}
+
+/** Options for a MongoDB `$vectorSearch` aggregation stage. */
+export interface VectorSearchOptions {
+    /** Name of the MongoDB Vector Search index. */
+    index: string;
+    /** Indexed vector field path. */
+    path: string;
+    /** Query embedding. Every value must be a finite number. */
+    queryVector: number[];
+    /** Maximum number of scored documents to return. */
+    limit: number;
+    /** Required for approximate nearest-neighbor search (`exact !== true`). */
+    numCandidates?: number;
+    /** Set to `true` to request exact nearest-neighbor search. */
+    exact?: boolean;
+    /** Optional MongoDB Vector Search pre-filter. */
+    filter?: Record<string, unknown>;
+    /** Fields to return from each matched document. */
+    projection?: Record<string, unknown> | string[];
+    /** Supported aggregate options; result-shape options are excluded. */
+    aggregateOptions?: VectorSearchAggregateOptions;
+}
+
+/** A vector-search result that preserves the source document and its score. */
+export interface VectorSearchHit<TDocument = unknown> {
+    document: TDocument;
+    score: number;
+}

package/dist/types/base.d.mts

@@ -36,6 +36,10 @@ export declare const enum ErrorCodes {
     INVALID_EXPRESSION = 'INVALID_EXPRESSION',
     INVALID_PAGINATION = 'INVALID_PAGINATION',
     INVALID_OPERATION = 'INVALID_OPERATION',
+    INVALID_VECTOR_SEARCH = 'INVALID_VECTOR_SEARCH',
+    INVALID_RELATION_SELECT = 'INVALID_RELATION_SELECT',
+    RELATION_IN_USE = 'RELATION_IN_USE',
+    RELATION_USAGE_UNAVAILABLE = 'RELATION_USAGE_UNAVAILABLE',
     INVALID_CURSOR = 'INVALID_CURSOR',
     INVALID_CONFIG = 'INVALID_CONFIG',
     INVALID_MODEL_DEFINITION = 'INVALID_MODEL_DEFINITION',

package/dist/types/base.d.ts

@@ -36,6 +36,10 @@ export declare const enum ErrorCodes {
     INVALID_EXPRESSION = 'INVALID_EXPRESSION',
     INVALID_PAGINATION = 'INVALID_PAGINATION',
     INVALID_OPERATION = 'INVALID_OPERATION',
+    INVALID_VECTOR_SEARCH = 'INVALID_VECTOR_SEARCH',
+    INVALID_RELATION_SELECT = 'INVALID_RELATION_SELECT',
+    RELATION_IN_USE = 'RELATION_IN_USE',
+    RELATION_USAGE_UNAVAILABLE = 'RELATION_USAGE_UNAVAILABLE',
     INVALID_CURSOR = 'INVALID_CURSOR',
     INVALID_CONFIG = 'INVALID_CONFIG',
     INVALID_MODEL_DEFINITION = 'INVALID_MODEL_DEFINITION',

package/dist/types/collection.d.mts

@@ -1,12 +1,18 @@
 import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb';
-
-/** Meta options for controlling timing/cache info in query results. */
-export interface MetaOptions {
-    /** 'op' = operation-level timing only; 'sub' = include sub-step timings (findPage only) */
-    level?: 'op' | 'sub';
-    /** Include cache hit/miss/ttl info in meta */
-    includeCache?: boolean;
-}
+import type {
+    AggregateOptions,
+    MetaOptions,
+    VectorSearchHit,
+    VectorSearchOptions,
+} from './aggregation.mjs';
+
+export type {
+    AggregateOptions,
+    MetaOptions,
+    VectorSearchAggregateOptions,
+    VectorSearchHit,
+    VectorSearchOptions,
+} from './aggregation.mjs';
 
 export type CacheInvalidationOperation =
     | 'find'
@@ -87,17 +93,6 @@ export interface CountOptions {
     meta?: boolean | MetaOptions;
 }
 
-/** v1-compatible aggregate options exported from the root package. */
-export interface AggregateOptions {
-    cache?: number;
-    maxTimeMS?: number;
-    allowDiskUse?: boolean;
-    collation?: any;
-    hint?: string | object;
-    comment?: string;
-    meta?: boolean | MetaOptions;
-}
-
 /** v1-compatible distinct options exported from the root package. */
 export interface DistinctOptions {
     cache?: number;
@@ -933,9 +928,14 @@ export interface Collection<TSchema = any> {
      * @param pipeline - Array of aggregation stage documents.
      * @param options - MongoDB AggregateOptions.
      * @returns AggregateChain that resolves to the result array.
-     */
+    */
     aggregate<TResult = unknown>(pipeline: unknown[] | undefined, options: QueryMetaOption): AggregateChain<TResult, ResultWithMeta<TResult[]>>;
     aggregate<TResult = unknown>(pipeline?: unknown[], options?: unknown): AggregateChain<TResult>;
+    /**
+     * Searches a MongoDB Vector Search index and returns each document with its score.
+     * Requires a compatible MongoDB deployment and a pre-created Vector Search index.
+     */
+    vectorSearch<TDocument = TSchema>(options: VectorSearchOptions): Promise<Array<VectorSearchHit<TDocument>>>;
     /** Stream mode: returns a readable stream of page documents when `stream: true`. */
     findPage(options: FindPageOptions<TSchema> & { stream: true }): NodeJS.ReadableStream;
     /** Sync totals mode guarantees `totals.total` and `totals.totalPages` are immediately available. */

package/dist/types/collection.d.ts

@@ -1,12 +1,18 @@
 import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb';
-
-/** Meta options for controlling timing/cache info in query results. */
-export interface MetaOptions {
-    /** 'op' = operation-level timing only; 'sub' = include sub-step timings (findPage only) */
-    level?: 'op' | 'sub';
-    /** Include cache hit/miss/ttl info in meta */
-    includeCache?: boolean;
-}
+import type {
+    AggregateOptions,
+    MetaOptions,
+    VectorSearchHit,
+    VectorSearchOptions,
+} from './aggregation';
+
+export type {
+    AggregateOptions,
+    MetaOptions,
+    VectorSearchAggregateOptions,
+    VectorSearchHit,
+    VectorSearchOptions,
+} from './aggregation';
 
 export type CacheInvalidationOperation =
     | 'find'
@@ -87,17 +93,6 @@ export interface CountOptions {
     meta?: boolean | MetaOptions;
 }
 
-/** v1-compatible aggregate options exported from the root package. */
-export interface AggregateOptions {
-    cache?: number;
-    maxTimeMS?: number;
-    allowDiskUse?: boolean;
-    collation?: any;
-    hint?: string | object;
-    comment?: string;
-    meta?: boolean | MetaOptions;
-}
-
 /** v1-compatible distinct options exported from the root package. */
 export interface DistinctOptions {
     cache?: number;
@@ -933,9 +928,14 @@ export interface Collection<TSchema = any> {
      * @param pipeline - Array of aggregation stage documents.
      * @param options - MongoDB AggregateOptions.
      * @returns AggregateChain that resolves to the result array.
-     */
+    */
     aggregate<TResult = unknown>(pipeline: unknown[] | undefined, options: QueryMetaOption): AggregateChain<TResult, ResultWithMeta<TResult[]>>;
     aggregate<TResult = unknown>(pipeline?: unknown[], options?: unknown): AggregateChain<TResult>;
+    /**
+     * Searches a MongoDB Vector Search index and returns each document with its score.
+     * Requires a compatible MongoDB deployment and a pre-created Vector Search index.
+     */
+    vectorSearch<TDocument = TSchema>(options: VectorSearchOptions): Promise<Array<VectorSearchHit<TDocument>>>;
     /** Stream mode: returns a readable stream of page documents when `stream: true`. */
     findPage(options: FindPageOptions<TSchema> & { stream: true }): NodeJS.ReadableStream;
     /** Sync totals mode guarantees `totals.total` and `totals.totalPages` are immediately available. */

package/dist/types/model.d.mts

@@ -1,4 +1,5 @@
-import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, InsertOneResult, UpdateBatchResult, UpdateResult } from './collection.mjs';
+import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, InsertOneResult, UpdateBatchResult, UpdateResult, VectorSearchHit, VectorSearchOptions } from './collection.mjs';
+import type { InferSchema } from 'schema-dsl';
 import type { SchemaDslRuntime } from 'schema-dsl/runtime';
 
 /**
@@ -12,6 +13,42 @@ export type ModelSchemaDsl = SchemaDslRuntime['s'];
  */
 export type SchemaDSL = (s: ModelSchemaDsl) => unknown;
 
+/**
+ * A statically typed Model registration descriptor.
+ *
+ * The descriptor preserves the document type inferred from an object-literal
+ * schema while keeping Model registration explicit at runtime.
+ * @since v3.3.0
+ */
+export interface ModelDescriptor<TName extends string = string, TDocument = Record<string, unknown>> {
+    readonly collectionName: TName;
+    readonly definition: ModelDefinition<TDocument>;
+    readonly __document?: TDocument;
+}
+
+/**
+ * Extract the document type carried by a Model descriptor.
+ * @since v3.3.0
+ */
+export type InferModelDocument<TDescriptor> = TDescriptor extends ModelDescriptor<string, infer TDocument>
+    ? TDocument
+    : never;
+
+/**
+ * Create a typed Model descriptor from a static object-literal schema.
+ *
+ * Register the returned descriptor with `Model.define(descriptor)` before
+ * binding it through a MonSQLize runtime. Callback schemas continue to use
+ * the existing explicit generic APIs because their static shape is not stable.
+ * @since v3.3.0
+ */
+export declare function defineModel<
+    const TName extends string,
+    const TSchema extends Record<string, unknown>,
+>(collectionName: TName, definition: Omit<ModelDefinition<InferSchema<TSchema>>, 'schema'> & {
+    schema: TSchema;
+}): ModelDescriptor<TName, InferSchema<TSchema>>;
+
 /**
  * Default value for a model field — either a static value or a factory function.
  * @template T Field value type
@@ -50,6 +87,8 @@ export interface RelationConfig {
     localField: string;
     foreignField: string;
     single?: boolean;
+    /** Default inclusion projection for this relation. Call-site `populate().select` takes precedence. */
+    select?: string | string[];
 }
 
 export interface PopulateConfig {
@@ -64,6 +103,71 @@ export interface PopulateConfig {
     populate?: string | PopulateConfig | Array<string | PopulateConfig>;
 }
 
+/** Vector search options at the Model layer, including Model soft-delete visibility. */
+export interface ModelVectorSearchOptions extends VectorSearchOptions {
+    withDeleted?: boolean;
+    onlyDeleted?: boolean;
+}
+
+/** Bounds and filters for inspecting registered, declared inbound Model relations. */
+export interface RelationUsageOptions {
+    session?: unknown;
+    maxTargets?: number;
+    maxSamples?: number;
+    includeRelations?: string[];
+    excludeRelations?: string[];
+    /** Defaults to true so soft-deleted source documents still protect a target. */
+    includeSoftDeletedReferences?: boolean;
+}
+
+export interface RelationUsageEntry {
+    sourceModel: string;
+    sourceCollection: string;
+    relation: string;
+    localField: string;
+    foreignField: string;
+    count: number;
+    sampleIds: unknown[];
+}
+
+export interface RelationUsageCoverage {
+    mode: 'registered-declared';
+    complete: boolean;
+    registryModels: string[];
+    checkedModels: string[];
+    skipped: Array<{
+        sourceModel: string;
+        reason: string;
+    }>;
+}
+
+export interface RelationUsageReport {
+    used: boolean;
+    target: {
+        matchedCount: number;
+        truncated: boolean;
+        sampleIds: unknown[];
+    };
+    checkedRelations: number;
+    usages: RelationUsageEntry[];
+    coverage: RelationUsageCoverage;
+}
+
+/** Result from a protected single-document delete after a relation usage check. */
+export interface RelationProtectedDeleteResult<TResult = unknown> {
+    result: TResult;
+    usage: RelationUsageReport;
+}
+
+/** Driver delete options plus bounds for the protected relation preflight. */
+export type RelationProtectedDeleteOptions = Omit<RelationUsageOptions, 'includeRelations' | 'excludeRelations'> & {
+    /** Protected deletion never permits narrowing the declared-relation scan. */
+    includeRelations?: never;
+    /** Protected deletion never permits narrowing the declared-relation scan. */
+    excludeRelations?: never;
+    [key: string]: unknown;
+};
+
 export interface VirtualConfig {
     get: (this: Record<string, unknown>) => unknown;
     set?: (this: Record<string, unknown>, value: unknown) => void;
@@ -385,6 +489,11 @@ export interface ModelInstance<TDocument = any> {
         data: Array<ModelDocument<TDocument>>;
         total: number;
     }>;
+    /**
+     * Runs Vector Search while applying Model soft-delete visibility and hydrating hit documents.
+     * The returned order and score are produced by MongoDB Vector Search.
+     */
+    vectorSearch(options: ModelVectorSearchOptions): Promise<Array<VectorSearchHit<ModelDocument<TDocument>>>>;
     /**
      * Counts documents matching the query.
      * @param query Optional filter.
@@ -479,6 +588,20 @@ export interface ModelInstance<TDocument = any> {
      * @returns Standard `DeleteResult` object.
      */
     deleteMany(filter?: unknown, options?: unknown): Promise<DeleteResult>;
+    /**
+     * Reports declared, registered Model relations currently using matching target documents.
+     * This is a read-only best-effort scan; inspect `coverage.complete` before relying on it.
+     */
+    checkRelationUsage(filter?: unknown, options?: RelationUsageOptions): Promise<RelationUsageReport>;
+    /**
+     * Deletes one visible target only after a complete declared-relation usage scan finds no references.
+     * Existing `deleteOne` behavior is otherwise preserved.
+     */
+    deleteOneWithRelations(filter: unknown, options?: RelationProtectedDeleteOptions): Promise<RelationProtectedDeleteResult>;
+    /**
+     * Physically deletes one target, including soft-deleted documents, only after the same protected scan.
+     */
+    forceDeleteWithRelations(filter: unknown, options?: RelationProtectedDeleteOptions): Promise<RelationProtectedDeleteResult>;
     // soft-delete extended methods
     /**
      * Finds matching documents, including soft-deleted documents.
@@ -653,6 +776,8 @@ export interface ModelInstance<TDocument = any> {
 }
 
 export declare class Model {
+    /** @since v3.3.0 */
+    static define<TName extends string, TDocument>(descriptor: ModelDescriptor<TName, TDocument>): void;
     static define<TDocument = Record<string, unknown>>(collectionName: string, definition: ModelDefinition<TDocument>): void;
     static get<TDocument = Record<string, unknown>>(collectionName: string): RegisteredModel<TDocument> | undefined;
     static has(collectionName: string): boolean;

package/dist/types/model.d.ts

@@ -1,4 +1,5 @@
-import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, InsertOneResult, UpdateBatchResult, UpdateResult } from './collection';
+import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, InsertOneResult, UpdateBatchResult, UpdateResult, VectorSearchHit, VectorSearchOptions } from './collection';
+import type { InferSchema } from 'schema-dsl';
 import type { SchemaDslRuntime } from 'schema-dsl/runtime';
 
 /**
@@ -12,6 +13,42 @@ export type ModelSchemaDsl = SchemaDslRuntime['s'];
  */
 export type SchemaDSL = (s: ModelSchemaDsl) => unknown;
 
+/**
+ * A statically typed Model registration descriptor.
+ *
+ * The descriptor preserves the document type inferred from an object-literal
+ * schema while keeping Model registration explicit at runtime.
+ * @since v3.3.0
+ */
+export interface ModelDescriptor<TName extends string = string, TDocument = Record<string, unknown>> {
+    readonly collectionName: TName;
+    readonly definition: ModelDefinition<TDocument>;
+    readonly __document?: TDocument;
+}
+
+/**
+ * Extract the document type carried by a Model descriptor.
+ * @since v3.3.0
+ */
+export type InferModelDocument<TDescriptor> = TDescriptor extends ModelDescriptor<string, infer TDocument>
+    ? TDocument
+    : never;
+
+/**
+ * Create a typed Model descriptor from a static object-literal schema.
+ *
+ * Register the returned descriptor with `Model.define(descriptor)` before
+ * binding it through a MonSQLize runtime. Callback schemas continue to use
+ * the existing explicit generic APIs because their static shape is not stable.
+ * @since v3.3.0
+ */
+export declare function defineModel<
+    const TName extends string,
+    const TSchema extends Record<string, unknown>,
+>(collectionName: TName, definition: Omit<ModelDefinition<InferSchema<TSchema>>, 'schema'> & {
+    schema: TSchema;
+}): ModelDescriptor<TName, InferSchema<TSchema>>;
+
 /**
  * Default value for a model field — either a static value or a factory function.
  * @template T Field value type
@@ -50,6 +87,8 @@ export interface RelationConfig {
     localField: string;
     foreignField: string;
     single?: boolean;
+    /** Default inclusion projection for this relation. Call-site `populate().select` takes precedence. */
+    select?: string | string[];
 }
 
 export interface PopulateConfig {
@@ -64,6 +103,71 @@ export interface PopulateConfig {
     populate?: string | PopulateConfig | Array<string | PopulateConfig>;
 }
 
+/** Vector search options at the Model layer, including Model soft-delete visibility. */
+export interface ModelVectorSearchOptions extends VectorSearchOptions {
+    withDeleted?: boolean;
+    onlyDeleted?: boolean;
+}
+
+/** Bounds and filters for inspecting registered, declared inbound Model relations. */
+export interface RelationUsageOptions {
+    session?: unknown;
+    maxTargets?: number;
+    maxSamples?: number;
+    includeRelations?: string[];
+    excludeRelations?: string[];
+    /** Defaults to true so soft-deleted source documents still protect a target. */
+    includeSoftDeletedReferences?: boolean;
+}
+
+export interface RelationUsageEntry {
+    sourceModel: string;
+    sourceCollection: string;
+    relation: string;
+    localField: string;
+    foreignField: string;
+    count: number;
+    sampleIds: unknown[];
+}
+
+export interface RelationUsageCoverage {
+    mode: 'registered-declared';
+    complete: boolean;
+    registryModels: string[];
+    checkedModels: string[];
+    skipped: Array<{
+        sourceModel: string;
+        reason: string;
+    }>;
+}
+
+export interface RelationUsageReport {
+    used: boolean;
+    target: {
+        matchedCount: number;
+        truncated: boolean;
+        sampleIds: unknown[];
+    };
+    checkedRelations: number;
+    usages: RelationUsageEntry[];
+    coverage: RelationUsageCoverage;
+}
+
+/** Result from a protected single-document delete after a relation usage check. */
+export interface RelationProtectedDeleteResult<TResult = unknown> {
+    result: TResult;
+    usage: RelationUsageReport;
+}
+
+/** Driver delete options plus bounds for the protected relation preflight. */
+export type RelationProtectedDeleteOptions = Omit<RelationUsageOptions, 'includeRelations' | 'excludeRelations'> & {
+    /** Protected deletion never permits narrowing the declared-relation scan. */
+    includeRelations?: never;
+    /** Protected deletion never permits narrowing the declared-relation scan. */
+    excludeRelations?: never;
+    [key: string]: unknown;
+};
+
 export interface VirtualConfig {
     get: (this: Record<string, unknown>) => unknown;
     set?: (this: Record<string, unknown>, value: unknown) => void;
@@ -385,6 +489,11 @@ export interface ModelInstance<TDocument = any> {
         data: Array<ModelDocument<TDocument>>;
         total: number;
     }>;
+    /**
+     * Runs Vector Search while applying Model soft-delete visibility and hydrating hit documents.
+     * The returned order and score are produced by MongoDB Vector Search.
+     */
+    vectorSearch(options: ModelVectorSearchOptions): Promise<Array<VectorSearchHit<ModelDocument<TDocument>>>>;
     /**
      * Counts documents matching the query.
      * @param query Optional filter.
@@ -479,6 +588,20 @@ export interface ModelInstance<TDocument = any> {
      * @returns Standard `DeleteResult` object.
      */
     deleteMany(filter?: unknown, options?: unknown): Promise<DeleteResult>;
+    /**
+     * Reports declared, registered Model relations currently using matching target documents.
+     * This is a read-only best-effort scan; inspect `coverage.complete` before relying on it.
+     */
+    checkRelationUsage(filter?: unknown, options?: RelationUsageOptions): Promise<RelationUsageReport>;
+    /**
+     * Deletes one visible target only after a complete declared-relation usage scan finds no references.
+     * Existing `deleteOne` behavior is otherwise preserved.
+     */
+    deleteOneWithRelations(filter: unknown, options?: RelationProtectedDeleteOptions): Promise<RelationProtectedDeleteResult>;
+    /**
+     * Physically deletes one target, including soft-deleted documents, only after the same protected scan.
+     */
+    forceDeleteWithRelations(filter: unknown, options?: RelationProtectedDeleteOptions): Promise<RelationProtectedDeleteResult>;
     // soft-delete extended methods
     /**
      * Finds matching documents, including soft-deleted documents.
@@ -653,6 +776,8 @@ export interface ModelInstance<TDocument = any> {
 }
 
 export declare class Model {
+    /** @since v3.3.0 */
+    static define<TName extends string, TDocument>(descriptor: ModelDescriptor<TName, TDocument>): void;
     static define<TDocument = Record<string, unknown>>(collectionName: string, definition: ModelDefinition<TDocument>): void;
     static get<TDocument = Record<string, unknown>>(collectionName: string): RegisteredModel<TDocument> | undefined;
     static has(collectionName: string): boolean;