Why define an optional property as type of null | undefined?

[qiulang]

For example, one of fs.readFileSync definition is

    export function readFileSync(
        path: PathOrFileDescriptor,
        options?: {
            encoding?: null | undefined;
            flag?: string | undefined;
        } | null
    ): Buffer;

Why define the optional property encoding as type of null | undefined ?

What could the use case of that ?

Thanks.

[agammann]

That overload describes binary reads, where the return value is a Buffer. Omitting encoding, passing null, and passing undefined all select that behavior:

import { readFileSync } from 'node:fs';

const a: Buffer = readFileSync('sample.txt');
const b: Buffer = readFileSync('sample.txt', { encoding: null });
const c: Buffer = readFileSync('sample.txt', { encoding: undefined });
const d: string = readFileSync('sample.txt', { encoding: 'utf8' });

console.log(Buffer.isBuffer(a), Buffer.isBuffer(b), Buffer.isBuffer(c), typeof d);

With a sample.txt file present, this prints true true true string (tested with ts-node 10.9.2 and @types/node 24.0.0).

The ? allows the property to be absent. The explicit | undefined also allows { encoding: undefined } when exactOptionalPropertyTypes is enabled; in that mode, an optional property does not automatically accept an explicitly supplied undefined. null is another value accepted by Node's API. A string encoding such as 'utf8' selects a separate overload returning string.

Sources: Node's readFileSync API, TypeScript's exact optional property setting.