Skip to content

Mistake in the docs #57005

Closed
Closed
Mistake in the docs#57005
Labels
DocsThe issue relates to how you learn TypeScriptHelp WantedYou can do this
Milestone
Backlog

Description

@m-Pawlowicz
Michal Pawlowicz (m-Pawlowicz)
opened on Jan 10, 2024

Acknowledgement

  • I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

Comment

Hi guys, correct me if im wrong, but i believe the docs for satisfies keyword have an error

type Colors = "red" | "green" | "blue";
type RGB = [red: number, green: number, blue: number];
const palette: Record<Colors, string | RGB> = {
    red: [255, 0, 0],
    green: "#00ff00",
    bleu: [0, 0, 255]
//  ~~~~ The typo is now correctly detected
};
// But we now have an undesirable error here - 'palette.red' "could" be a string.
const redComponent = palette.red.at(0);

since values are unions of string and array, palette.red.at(0) will not throw an error, because at method is a method that exists for both types.
Cheers :).

image

Activity

  1. MartinJohns commented on Jan 10, 2024

    @MartinJohns
    Martin Johns (MartinJohns)
    on Jan 10, 2024
    Contributor

    The point is not a missing at() method, but that it may return a string. There's no error her, just a misunderstanding.

  2. sivharinair2001 commented on Jan 10, 2024

    @sivharinair2001
    SIV HARI NAIR (sivharinair2001)
    on Jan 10, 2024

    There will be no error in palette.red.at(0) as TypeScript should be able to correctly infer the type based on the property access.

  3. jcalz commented on Jan 10, 2024

    @jcalz
    Joe Calzaretta (jcalz)
    on Jan 10, 2024
    Contributor

    I think OP's point is that the docs say that there is an "undesirable error" on palette.red.at(0), but there's no error. Maybe the word "error" is wrong, or maybe the docs should use an array-only method like map() or something like it instead of at().

    Anyway I think doc errors tend to belong at https://github.com/microsoft/TypeScript-Website/issues

  4. MartinJohns commented on Jan 10, 2024

    @MartinJohns
    Martin Johns (MartinJohns)
    on Jan 10, 2024
    Contributor

    There's no error in the docs, just poor wording when it mentions an "error". Using map wouldn't showcase the example they're making. With a type annotation the return type of at() is string | number, but when using satisfies the return type is number.

  5. RyanCavanaugh commented on Jan 11, 2024

    @RyanCavanaugh
    Ryan Cavanaugh (RyanCavanaugh)
    on Jan 11, 2024
    Member

    I think the example was unintentionally written against a pre-String#at target

  6. Ryan Cavanaugh (RyanCavanaugh)
    added
    Help WantedYou can do this
    DocsThe issue relates to how you learn TypeScript
    on Jan 11, 2024
  7. Ryan Cavanaugh (RyanCavanaugh)
    added this to the Backlog milestone on Jan 11, 2024

  8. mariusgau commented on Mar 27, 2024

    @mariusgau
    Marius (mariusgau)
    on Mar 27, 2024

    I believe the documentation is incorrect or misleading. I can send a PR to https://github.com/microsoft/TypeScript-Website if wanted.
    https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator should look like:

    The satisfies Operator

    TypeScript developers are often faced with a dilemma: we want to ensure that some expression matches some type, but also want to keep the most specific type of that expression for inference purposes.

    For example:

    // Each property can be a string or an RGB tuple.
const palette = {
    red: [255, 0, 0],
    green: "#00ff00",
    bleu: [0, 0, 255]
//  ^^^^ sacrebleu - we've made a typo!
};

// We want to be able to use string methods on 'green'...
const greenNormalized = palette.green.toUpperCase();

    Notice that we've written bleu, whereas we probably should have written blue.
    We could try to catch that bleu typo by using a type annotation on palette, but we'd lose the information about each property.

    type Colors = "red" | "green" | "blue";

type RGB = [red: number, green: number, blue: number];

const palette: Record<Colors, string | RGB> = {
    red: [255, 0, 0],
    green: "#00ff00",
    bleu: [0, 0, 255]
//  ~~~~ The typo is now correctly detected
};

// But we now have an undesirable error here - 'palette.greed' "could" be of type RGB and
// property 'toUpperCase' does not exist on type 'string | RGB'.
const greenNormalized = palette.green.toUpperCase();

    The new satisfies operator lets us validate that the type of an expression matches some type, without changing the resulting type of that expression.
    As an example, we could use satisfies to validate that all the properties of palette are compatible with string | number[]:

    type Colors = "red" | "green" | "blue";

type RGB = [red: number, green: number, blue: number];

const palette = {
    red: [255, 0, 0],
    green: "#00ff00",
    bleu: [0, 0, 255]
//  ~~~~ The typo is now caught!
} satisfies Record<Colors, string | RGB>;

// toUpperCase() methode is still accessible!
const greenNormalized = palette.green.toUpperCase();

    satisfies can be used to catch lots of possible errors.
    For example...

  9. RyanCavanaugh commented on Mar 27, 2024

    @RyanCavanaugh
    Ryan Cavanaugh (RyanCavanaugh)
    on Mar 27, 2024
    Member

    Looks nice, please go ahead with the PR. Thanks!

  10. pieterocp commented on Mar 12, 2025

    @pieterocp
    Pieter Oliver (pieterocp)
    on Mar 12, 2025

    This looks to have been merged into the typescript docs so can probably be closed?

  11. Ryan Cavanaugh (RyanCavanaugh)
    closed this as completedon Mar 12, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    DocsThe issue relates to how you learn TypeScriptHelp WantedYou can do this

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions