Características y limitaciones de TypeScript

Parámetros de tipo que extienden documento

Las siguientes clases aceptan todos los tipos que implementan la interfaz Document:

• Colección

• ChangeStream

Puedes pasar un parámetro de tipo que extienda la interfaz Document de esta manera:

1
interface Pet {
2
  name: string;
3
  age: number;
4
}
5
6
const database = client.db("<your database>");
7
const collection = database.collection<Pet>("<your collection>");

1
interface User {
2
  email: string;
3
}
4
5
const database = client.db("<your database>");
6
const myColl = db.collection<User>("<your collection>");
7
myColl.find({ age: "Accepts any type!" });

Parámetros de tipo de cualquier tipo

Las siguientes clases aceptan todos los parámetros de tipo:

• FindCursor

• AggregationCursor

Puede encontrar un fragmento de código que muestra cómo especificar un tipo para la clase FindCursor en el find() Ejemplo: Sección Archivo completo de la guía Buscar documentos.

Seguridad de tipos y notación de punto

A partir de la versión 5.0, por defecto, el driver de Node.js no proporciona seguridad de tipos para las operaciones que buscan en campos expresados en notación de puntos. La notación de puntos es una sintaxis que puede utilizar para navegar por objetos JSON anidados. Cuando se construye un filtro para pasar a una query, el driver no generará un error de tipo incluso si especifica un valor con un tipo incorrecto para un campo expresado en notación de puntos.

El siguiente fragmento de código define la interfaz ClassificationPet, que incluye un campo classification que le permite especificar el género y el color de perros y gatos:

interface ClassificationPet {
  name: string;
  age: number;
  classification: { genus: "Canis" | "Felis"; color: string };
}

El controlador no genera un error de tipo para el siguiente ejemplo de código, aunque el valor de classification.color sea un booleano en lugar de un string:

await myColl.findOneAndDelete({ "classification.color": false });

Puede activar la comprobación de tipos construyendo filtros como tipos StrictFilter o StrictUpdateFilter.

En la siguiente muestra de código, se asigna al filtro un tipo StrictFilter. Dado este tipo de filtro, el controlador de Node.js informa de un error de tipo porque el valor de classification.color es un booleano en lugar de un string.

const filterPredicate: StrictFilter<ClassificationPet> = { "classification.color": false };
await myColl.findOneAndDelete(filterPredicate);

El siguiente ejemplo asigna un tipo StrictUpdateFilter a un filtro para actualizar. El controlador de Node.js informa de un error de tipo porque el valor de classification.color es un booleano en lugar de un string.

const updateFilter: StrictUpdateFilter<ClassificationPet> = { $set: { "classification.color": false } }
await pets.updateOne({}, updateFilter);

interface ClassificationPet {
  name: string;
  mealtimes: Mealtime[];
}
interface Mealtime{
  time: string;
  amount: number;
}

const mealCounter = 1;
await myColl.findOneAndUpdate(
  { name: "Lassie" },
  { $set: { [`mealtimes.${mealCounter}.time` as const]: '04:00 PM' } },
);

Operaciones de inserción y el campo _id

La manera en que especificas el campo _id en los parámetros de tipo pasados a su instancia Collection influye en el comportamiento de las operaciones de inserción. La siguiente tabla describe cómo las diferentes especificaciones de campo _id afectan a las operaciones de inserción:

Si se debe especificar el campo _id como requerido en el tipo que define para representar documentos en la colección, pero no se desea especificar valores para el campo _id en las operaciones de inserción, se debe usar el tipo de asistente OptionalId cuando se cree la colección. El tipo OptionalId acepta un parámetro de tipo como argumento y devuelve ese tipo con un campo _id opcional.

El siguiente fragmento de código define la interfaz IdPet, que incluye un tipo para el campo _id:

interface IdPet {
  _id: ObjectId;
  name: string;
  age: number;
}

El siguiente código utiliza la interfaz anterior y el tipo OptionalId para insertar un documento sin especificar un valor para el campo _id:

const database = client.db("<your database>");
const collection = db.collection<OptionalId<IdPet>>("<your collection>");
myColl.insertOne({
  name: "Spot",
  age: 2
});

Para obtener más información sobre el campo _id, consulta The _id campo en el manual de MongoDB.

Para obtener más información sobre los tipos, las interfaces y las clases discutidos en esta sección, consulta los siguientes recursos:

• OptionalId API documentation

• PkFactory Documentación de la API

• ObjectId código fuente

Métodos de búsqueda y el campo _id

Los métodos find y findOne de la clase Collection incluyen el campo _id en su tipo de retorno. El controlador infiere el tipo del campo _id devuelto en función del parámetro de tipo que pasaste a su instancia de Collection.

Si el parámetro de tipo que se ha pasado a la instancia Collection incluye el campo _id en el esquema, el driver infiere que el campo _id devuelto por el método es del tipo especificado en el esquema.

Sin embargo, si el parámetro de tipo que se ha pasado a la instancia Collection no incluye el campo _id en su esquema, el driver infiere que el tipo del campo _id devuelto por el método es ObjectId.

El siguiente código utiliza la interfaz Pet para devolver un documento con un _id inferido como de tipo ObjectId:

const database = client.db("<your database>");
const collection = db.collection<Pet>("<your collection>");
const document = await myColl.findOne({
  name: "Spot",
});
const id : ObjectId = document._id;

El siguiente código utiliza la interfaz IdNumberPet para devolver un documento con un _id inferido como de tipo number:

interface IdNumberPet {
  _id: number;
  name: string;
  age: number;
}
const database = client.db("<your database>");
const collection = db.collection<IdNumberPet>("<your collection>");
const document = await myColl.findOne({
  name: "Spot",
});
const id : number = document._id;

const doc = await myColl.findOne(
  {},
  { projection: { _id: 0, name: 1 } }
);
console.log(doc._id.generationTime);

interface ProjectedDocument {
   name: string
}
const doc = await myColl.findOne<ProjectedDocument>(
  {},
  { projection: { _id: 0, name: 1 } }
);
// Compile time error: Property '_id' does not exist on type 'ProjectedDocument'.
console.log(doc._id.generationTime);

Para aprender más sobre las clases y métodos discutidos en esta sección, consulta la siguiente documentación de la API:

• Colección

• buscar

• findOne

Tipos recursivos y notación de punto

El controlador de Node.js no puede garantizar la seguridad de tipos dentro de instancias anidadas de tipos recursivos referenciadas mediante notación de puntos.

Un tipo recursivo es un tipo que se refiere a sí mismo. Se puede actualizar la interfaz de Pet para que sea recursiva permitiendo que una mascota tenga su propia mascota. La siguiente es la interfaz Pet recursiva:

interface RecursivePet {
   pet?: RecursivePet;
   name: string;
   age: number;
}

El siguiente fragmento de código hace referencia a una instancia anidada de la interfaz RecursivePet con un tipo incorrecto utilizando notación de puntos, pero el compilador de TypeScript no genera un error de tipo:

database
   .collection<RecursivePet>("<your collection>")
   .findOne({ "pet.age": "Spot" });

El siguiente fragmento de código hace referencia a una instancia de nivel superior de la interfaz RecursivePet con un tipo incorrecto y genera un error de tipo:

database
   .collection<RecursivePet>("<your collection>")
   .findOne({ pet: "Spot" });

El error generado por el fragmento de código anterior es el siguiente:

index.ts(19,59): error TS2769: No overload matches this call.
The last overload gave the following error.
Type 'string' is not assignable to type 'Condition<Pet>'.

Si debe tener seguridad de tipos dentro de instancias anidadas de tipos recursivos, debe guardar su query o actualizar sin notación de puntos.

Para obtener más información sobre la notación de puntos, consulta notación de puntos en el manual de MongoDB.

Recursión mutua

Un tipo mutuamente recursivo existe cuando dos tipos contienen una propiedad que es del tipo del otro. Puedes actualizar la interfaz Pet para que sea mutuamente recursiva permitiendo que un Pet tenga un controlador, y definiendo un controlador para que tenga un Pet. Los siguientes ejemplos hacen referencia a las interfaces Pet y Handler que son mutuamente recursivas:

interface Pet {
   handler?: Handler;
   name: string;
   age: number;
}
interface Handler {
   pet: Pet;
   name: string;
}

El controlador de Node.js proporciona seguridad de tipos para tipos mutuamente recursivos referenciados mediante notación de puntos hasta una profundidad de ocho. El siguiente fragmento de código asigna un string a un number y genera un error de tipo porque la propiedad referenciada está a una profundidad de cuatro:

database
   .collection<Pet>("<your collection>")
   .findOne({'handler.pet.handler.pet.age': "four"});

El error generado por el fragmento de código anterior es el siguiente:

index.ts(19,59): error TS2769: No overload matches this call.
The last overload gave the following error.
Type 'string' is not assignable to type 'Condition<number> | undefined'.

A una profundidad mayor o igual a ocho, TypeScript compila el código, pero ya no verifica los tipos. El siguiente código asigna un string a una propiedad number, pero no provoca un error de compilación porque la propiedad referenciada está a una profundidad de 10:

database
   .collection<Pet>("<your collection>")
   .findOne({'handler.pet.handler.pet.handler.pet.handler.pet.handler.pet.age': "four"});