Umgang mit null- und undefined-Werten in WHERE-Bedingungen

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

In 'WHERE'-Bedingungen sind die Werte null und undefined in TypeORM nicht als strikt gültige Werte definiert.

Das Übergeben eines bekannten null-Werts wird von TypeScript zur Kompilierzeit verhindert (wenn strictNullChecks in tsconfig.json aktiviert ist). Standardmäßig werden jedoch zur Laufzeit auftretende null-Werte ignoriert. Ebenso werden undefined-Werte von TypeScript zugelassen und zur Laufzeit ignoriert.

Die Akzeptanz von null und undefined kann unerwartete Ergebnisse verursachen und erfordert Vorsicht. Dies ist besonders relevant, wenn Werte aus Benutzereingaben ohne ausreichende Validierung übernommen werden.

Beispielsweise gibt Repository.findOneBy({ id: undefined }) die erste Zeile der Tabelle zurück, und Repository.findBy({ userId: null }) liefert ungefiltert alle Zeilen.

Das Verhalten gegenüber null und undefined kann über die Konfigurationsoption invalidWhereValuesBehavior in den Data-Source-Optionen angepasst werden. Dies gilt für alle Operationen mit 'WHERE'-Bedingungen, einschließlich Find-Operationen, Query Builder und Repository-Methoden.

Hinweis

Das aktuelle Verhalten wird sich in zukünftigen TypeORM-Versionen ändern. Wir empfehlen, sowohl für null als auch undefined das Verhalten auf 'throw' zu setzen, um auf diese Änderungen vorbereitet zu sein.

Standardverhalten

Standardmäßig überspringt TypeORM sowohl null als auch undefined in WHERE-Bedingungen. Das bedeutet, dass Eigenschaften mit null oder undefined in der WHERE-Klausel ignoriert werden:

// Both queries will return all posts, ignoring the text property
const posts1 = await repository.find({
    where: {
        text: null,
    },
})

const posts2 = await repository.find({
    where: {
        text: undefined,
    },
})

Der korrekte Weg, um nach NULL-Werten zu suchen, ist der IsNull-Operator (Details unter Find-Optionen):

const posts = await repository.find({
    where: {
        text: IsNull(),
    },
})

Konfiguration

Das Verhalten gegenüber null und undefined kann über die Option invalidWhereValuesBehavior in der Verbindungskonfiguration angepasst werden:

const dataSource = new DataSource({
    // ... other options
    invalidWhereValuesBehavior: {
        null: "ignore" | "sql-null" | "throw",
        undefined: "ignore" | "throw",
    },
})

Optionen für Null-Verhalten

Das null-Verhalten kann auf einen von drei Werten gesetzt werden:

'ignore' (Standard)

JavaScript-null-Werte in WHERE-Bedingungen werden ignoriert und die Eigenschaft übersprungen:

const dataSource = new DataSource({
    // ... other options
    invalidWhereValuesBehavior: {
        null: "ignore",
    },
})

// This will return all posts, ignoring the text property
const posts = await repository.find({
    where: {
        text: null,
    },
})

'sql-null'

JavaScript-null-Werte werden in SQL-NULL-Bedingungen umgewandelt:

const dataSource = new DataSource({
    // ... other options
    invalidWhereValuesBehavior: {
        null: "sql-null",
    },
})

// This will only return posts where the text column is NULL in the database
const posts = await repository.find({
    where: {
        text: null,
    },
})

'throw'

JavaScript-null-Werte lösen einen TypeORMError aus:

const dataSource = new DataSource({
    // ... other options
    invalidWhereValuesBehavior: {
        null: "throw",
    },
})

// This will throw an error
const posts = await repository.find({
    where: {
        text: null,
    },
})
// Error: Null value encountered in property 'text' of a where condition.
// To match with SQL NULL, the IsNull() operator must be used.
// Set 'invalidWhereValuesBehavior.null' to 'ignore' or 'sql-null' in connection options to skip or handle null values.

Optionen für Undefined-Verhalten

Das undefined-Verhalten kann auf einen von zwei Werten gesetzt werden:

'ignore' (Standard)

JavaScript-undefined-Werte in WHERE-Bedingungen werden ignoriert und die Eigenschaft übersprungen:

const dataSource = new DataSource({
    // ... other options
    invalidWhereValuesBehavior: {
        undefined: "ignore",
    },
})

// This will return all posts, ignoring the text property
const posts = await repository.find({
    where: {
        text: undefined,
    },
})

'throw'

JavaScript-undefined-Werte lösen einen TypeORMError aus:

const dataSource = new DataSource({
    // ... other options
    invalidWhereValuesBehavior: {
        undefined: "throw",
    },
})

// This will throw an error
const posts = await repository.find({
    where: {
        text: undefined,
    },
})
// Error: Undefined value encountered in property 'text' of a where condition.
// Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.

Hinweis: Dies gilt nur für explizit gesetzte undefined-Werte, nicht für weggelassene Eigenschaften.

Kombinierte Verwendung beider Optionen

Beide Verhaltensweisen können unabhängig konfiguriert werden, um maximale Kontrolle zu erreichen:

const dataSource = new DataSource({
    // ... other options
    invalidWhereValuesBehavior: {
        null: "sql-null",
        undefined: "throw",
    },
})

Diese Konfiguration bewirkt:

1. Umwandlung von JavaScript-null in SQL-NULL in WHERE-Bedingungen

2. Auslösen eines Fehlers bei Auftreten von undefined-Werten

3. Weiterhin Ignorieren nicht angegebener Eigenschaften in der WHERE-Klausel

Diese Kombination ist nützlich, wenn Sie:

• Explizit nach NULL-Werten in der Datenbank suchen

• Potenzielle Programmierfehler abfangen, bei denen undefined-Werte in Ihre Abfragen gelangen könnten

Gilt für alle WHERE-Operationen

Die invalidWhereValuesBehavior-Konfiguration gilt für alle TypeORM-Operationen mit WHERE-Bedingungen, nicht nur für Repository-Find-Methoden:

Query-Builder

// UpdateQueryBuilder
await dataSource
    .createQueryBuilder()
    .update(Post)
    .set({ title: "Updated" })
    .where({ text: null }) // Respects invalidWhereValuesBehavior
    .execute()

// DeleteQueryBuilder
await dataSource
    .createQueryBuilder()
    .delete()
    .from(Post)
    .where({ text: null }) // Respects invalidWhereValuesBehavior
    .execute()

// SoftDeleteQueryBuilder
await dataSource
    .createQueryBuilder()
    .softDelete()
    .from(Post)
    .where({ text: null }) // Respects invalidWhereValuesBehavior
    .execute()

Repository-Methoden

// Repository.update()
await repository.update({ text: null }, { title: "Updated" }) // Respects invalidWhereValuesBehavior

// Repository.delete()
await repository.delete({ text: null }) // Respects invalidWhereValuesBehavior

// EntityManager.update()
await manager.update(Post, { text: null }, { title: "Updated" }) // Respects invalidWhereValuesBehavior

// EntityManager.delete()
await manager.delete(Post, { text: null }) // Respects invalidWhereValuesBehavior

// EntityManager.softDelete()
await manager.softDelete(Post, { text: null }) // Respects invalidWhereValuesBehavior

Alle diese Operationen wenden Ihre konfigurierten invalidWhereValuesBehavior-Einstellungen konsistent an.