Annotation or satisfies for a config object

One more difference, on optional properties. With the annotation, a timeout?: number you left out still reads as number | undefined, and every reader has to decide what undefined means. With satisfies, the property isn't in the inferred type at all, so config.timeout fails with TS2339, property does not exist.

That is a sharper answer and a different one. Add timeout to the literal later and every reader that was rejected starts compiling. Pick by whether callers should handle a missing value or never see one.

For anything exported I'd go the other way. A satisfies object exports its literal type too, so every module importing config now depends on the values inside it. Change 'dark' to 'light' and a comparison three files away stops compiling. That code was relying on a value, not on a type, and nobody decided it should. For application config I still prefer the annotation. Config says what the code may rely on, nothing more.

The root makes this sound simpler than it is. satisfies doesn't keep every literal you write.

type Config = { mode: 'light' | 'dark'; port: number };

const config = { mode: 'dark', port: 8080 } satisfies Config;

const m: 'dark' = config.mode;  // ok
const p: 8080 = config.port;    // error, port is number

port widens to number because Config gives it number as the contextual type. mode stays 'dark' only because Config declares a union of string literals. So it keeps the more specific inferred type, and how specific depends on Config. The worry about importers leaning on values applies to mode and mostly not to port.

So the user opens settings, picks the dark theme, and that choice gets written to a JSON file. Next launch the app reads that file back, and satisfies was never anywhere near it (it only ever looked at the literal in the source). The literal config says 'dark', the saved file might say 'Dark' or nothing at all. Do people keep the satisfies object as the defaults and parse the saved file into Config with a runtime check, or is there a way to keep the two from drifting that I'm missing?

Answering my own question after trying it. The satisfies literal became defaults, the saved file goes through a small parseSettings(raw: unknown): Partial<Config>, and the app runs on const config: Config = { ...defaults, ...saved }. The annotation on the merged value also takes care of selim70's worry, since importers only see Config.

The part that bit me was the parser. My first version copied every known key and set it to undefined when the value was junk. Spreading an explicit undefined wipes the default, and the types didn't object (no exactOptionalPropertyTypes in that project). So a user who typed "Dark" by hand got neither dark nor light, just a theme picker with nothing selected. Now the parser leaves a bad key out entirely, and the settings screen shows a small note that one saved value was ignored.

Can confirm the TS2339 part, that's how it showed up for me. A tooltip helper read defaults.timeout straight off the satisfies object and failed to compile, because the literal never had a timeout. Pointing it at the merged config gave number | undefined, which is the honest type there anyway, since a saved file can leave it out too.