I opted to make this explicit even though it is the default behavior without this line, that way we have a reference to it in code in case someone searches this codebase (see the docs changes for how this is conveyed in docs).

I opted to swap the order of this note and the sentence above as I think it reads a bit better since it now includes an introduction before the side comment.

I don't know if it makes sense to include a note on migrating from codegen's fragment masking feature. I had a difficult time figuring out how to mention it.

The steps to migrate are roughly:

• Migrate to Apollo Client's useFragment hook first
• Disable fragment masking feature in codegen config
• Enable dataMasking on the client

The key thing here is that dataMasking should remain off until fully migrated, otherwise it messes with the fragment masking feature since it needs the full result type.

That said, these 3 things are already sorta listed in this section, just not as a "migrate away from" type way. Do you think there is anything more to say or do you think there is enough here that makes it obvious what needs to be done?

This is the biggest change in the docs for this PR. With the move to mode instead of enabled, it didn't make much sense to talk about this as a "opt into masked types", since really all that was doing was preserving the type and preventing it from being unwrapped. I've oriented this now around the modes and what they do.

I've provided a migration path for 3.12.5 for those that want/need it in the PR description. Is that something we should include in the docs as well, or should we point to the PR for these instructions instead?

Based on my previous comment, perhaps this is enough to satisfy communication on migrating to this new change?

Should I mention this is the default behavior in a followup sentence, or is the header clear enough that this is the default behavior?

There really is no "opt in" anymore after this change so I tried to remove that language everywhere I could.

I would suggest moving the DataMasking tests up:

export type MaybeMasked<TData> =
  DataMasking extends { mode: "unmask" } ?
    // distribute TData - in case of a union, do the next steps for each member
    TData extends any ?
      // prevent "Type instantiation is excessively deep and possibly infinite."
      true extends IsAny<TData> ? TData
      : TData extends { __masked?: true } ? Prettify<RemoveMaskedMarker<TData>>
      : true extends ContainsFragmentsRefs<TData> ? Unmasked<TData>
      : TData
    : never
  : DataMasking extends { mode: "preserveTypes" } ? TData
  : TData;

This way, in cases where mode is not "unmask", the types won't be touched at all.

While that might seem counterintuitive, the benefit is that TData itself will not need to be inspected at all, which enables cases where TData is unknown at the time of invoking MaybeMasked.

Here is a new test that shows the problem:

test("MaybeMasked can be called with a generic if `mode` is not set to `unmask`", (prefix) => {
  function withGenericResult<T extends { [key: string]: string }>(
    arg: TypedDocumentNode<T, {}>
  ) {
    bench(prefix + "Result generic - instantiations", () => {
      const maybeMasked: MaybeMasked<typeof arg> = arg;
      return maybeMasked;
    }).types();

    bench(prefix + "Result generic - functionality", () => {
      const maybeMasked: MaybeMasked<typeof arg> = arg;
      expectTypeOf(maybeMasked).toEqualTypeOf(arg);
    });
  }
  function withGenericDocument<T extends TypedDocumentNode>(arg: T) {
    bench(prefix + "Result generic - instantiations", () => {
      const maybeMasked: MaybeMasked<T> = arg;
      return maybeMasked;
    }).types();

    bench(prefix + "Result generic - functionality", () => {
      const maybeMasked: MaybeMasked<T> = arg;
      // cannot use unresolved generic with `expectTypeOf` here so we just try an assignment the other way round
      const test: T = maybeMasked;
      return test;
    });
  }
  withGenericResult({} as any);
  withGenericDocument({} as any);
});

The drawback is that the Masked marker would not be removed, but if you don't set { mode: "unmask" } I don't think Masked has any use case, right?