如何实现TypeScript环境下MongoDB查询的通用类型安全过滤？

问题背景 #

在TypeScript环境中使用MongoDB v6.6.2，现有如下通用查询函数：

export async function getCollection<T extends Document>(collection_name: string, skip: number, limit: number, filter: Filter<Document>): Promise<T[]> {
    try {
        let database = await connectToDatabase();
        return database.collection<T>(collection_name).find(filter).skip(skip).limit(limit).toArray();
    } catch (error) {
        console.error(error);
        throw error;
    }
}

调用示例：

const deviceDBs = await getCollection<DeviceDB>("devices", 0, 0, { location_id: ObjectId.createFromHexString(locationId) });

当前核心问题是过滤参数filter缺乏类型安全校验：即便传入泛型T（如DeviceDB）中不存在的属性（比如把location_id改为foo），代码依然能正常编译，不符合预期的类型约束要求。

曾尝试将filter类型改为Filter<Partial<T>>，但该类型不匹配MongoDB find方法的类型定义——find期望接收Filter<TSchema>类型参数，其定义如下：

find(): FindCursor<WithId<TSchema>>;
find(filter: Filter<TSchema>, options?: FindOptions): FindCursor<WithId<TSchema>>;
find<T extends Document>(filter: Filter<TSchema>, options?: FindOptions): FindCursor<T>;

解决方案 #

要实现类型安全的过滤，只需将filter的类型从Filter<Document>改为Filter<T>即可。因为泛型T已经约束为extends Document，完全符合find方法对Filter<TSchema>的类型要求。

修改后的函数 #

import { Document, Filter, WithId, Collection } from "mongodb";

export async function getCollection<T extends Document>(
  collection_name: string,
  skip: number,
  limit: number,
  filter: Filter<T> // 替换为Filter<T>实现类型约束
): Promise<WithId<T>[]> { // 修正返回类型：find默认返回带_id的文档
  try {
    const database = await connectToDatabase();
    const collection: Collection<T> = database.collection<T>(collection_name);
    return collection.find(filter).skip(skip).limit(limit).toArray();
  } catch (error) {
    console.error(error);
    throw error;
  }
}

方案说明 #

1. 类型约束生效原理：Filter<T>会基于泛型T的结构生成合法的查询过滤类型，既允许使用T中存在的属性作为过滤条件，也支持MongoDB的查询操作符（如$eq、$in等），同时会拦截不存在的属性。
   示例错误提示：

   // 编译报错：类型“{ foo: ObjectId; }”的参数不能赋给类型“Filter<DeviceDB>”的参数
   const deviceDBs = await getCollection<DeviceDB>("devices", 0, 0, { foo: ObjectId.createFromHexString(locationId) });
   

2. 返回类型优化：原函数返回Promise<T[]>，但MongoDB的find方法默认返回包含_id字段的文档，将返回类型改为Promise<WithId<T>[]>能更准确反映实际返回结构，避免后续处理_id时出现类型错误。

验证效果 #

修改后调用getCollection时：

• 传入T类型存在的属性：编译通过，运行正常。
• 传入T类型不存在的属性：编译阶段直接报错，实现了预期的类型安全校验。

内容的提问来源于stack exchange，提问作者Sean Anderson