Add a guide for "satsifies" in TypeScript

[akkadaya]

I wonder if Google has a guide for "satisfies" in TypeScript? It would be nice to have!

[MOHD-TAHA-KHAN]

Proposed Guidance for satisfies Operator in TypeScript

Since the introduction of the satisfies operator in TypeScript 4.9, it has become a crucial tool for balancing strict type safety with precise type inference. Adding clear guidance to the Google TypeScript Style Guide would help teams avoid over-generalized type annotations while steering clear of dangerous type assertions (as).

Here is a proposed structure and wording for the guide:

---

1. When to Use satisfies

Use satisfies when you need to validate that an expression conforms to a specific type or interface, but you want to retain the narrowest possible inferred type for downstream code.

• Example (Validating shapes without losing literal types):

type Colors = 'red' | 'green' | 'blue';
type RGB = [number, number, number];

// GOOD: TypeScript knows palette.green is specifically a string
const palette = {
  red: [255, 0, 0],
  green: '#00ff00',
  blue: [0, 0, 255],
} satisfies Record<Colors, string | RGB>;

// Safe to call string methods without explicit casting
palette.green.toUpperCase(); 

2. When to Prefer Explicit Type Annotations

Do not use satisfies for variables or exported constants where you want to enforce the broader contract type on the variable itself, such as public API boundaries, module exports, or when establishing a strict structural definition that downstream consumers should not bypass.

• Example:

interface AppConfig {
  port: number;
  host: string;
}

// GOOD: Ensures the exported object matches the rigid public contract exactly.
export const config: AppConfig = {
  port: 8080,
  host: 'localhost',
};

3. satisfies vs. Type Assertions (as)

satisfies should replace type assertions (as Type) in scenarios where developers are trying to satisfy the compiler but want type-checking to remain active. Unlike as, which bypasses safety checks, satisfies throws a compiler error if the shape is incorrect.

• Example:

// BAD: Silently fails type safety if 'port' is misspelled as 'prt'
const config = { prt: 8080 } as AppConfig; 

// GOOD: Fails at compile time because 'prt' doesn't match 'AppConfig'
const config = { prt: 8080 } satisfies AppConfig; 

4. Interaction with Immutability (as const satisfies)

Be aware that satisfies only validates the shape; it does not make the object deeply read-only. For strict configuration objects or lookups that must not be mutated at runtime, combine satisfies with as const.

• Example:

// BAD: Object shape is validated, but elements can still be mutated
const routes = { home: '/' } satisfies Record<string, string>;
routes.home = '/dashboard'; // Allowed by compiler

// GOOD: Deeply immutable and structurally validated
const routes = { home: '/' } as const satisfies Record<string, string>;
// routes.home = '/dashboard'; // Error: Cannot assign to read-only property

5. Automated Enforcements (Linting)

To scale this convention seamlessly across large codebases, we can leverage @typescript-eslint/eslint-plugin. Specifically, the rule consistent-type-assertions can be configured to restrict loose as assertions, encouraging engineers to use satisfies or proper type annotations instead:

JSON
{
  "rules": {
    "@typescript-eslint/consistent-type-assertions": [
      "error",
      {
        "assertionStyle": "never", 
        "objectLiteralTypeAssertions": "never"
      }
    ]
  }
}

---

I'd love to hear the maintainers' thoughts on this structure, and I am happy to help refine the wording or add more edge cases if needed!