[lexical] Bug Fix: Keep the deprecated unchecked node type arguments in the Flow declarations

.changeset/restore-flow-unchecked-node-type-arguments.md

@@ -0,0 +1,28 @@
+---
+'lexical': patch
+---
+
+[fix] Keep the deprecated unchecked node type arguments in the Flow declarations
+
+v0.53.0 removed the unchecked type-argument overloads of `getParent`,
+`getParentOrThrow`, `getParents`, `getPreviousSibling`, `getPreviousSiblings`,
+`getNextSibling`, `getNextSiblings`, `getChildren`, `getFirstChild`,
+`getFirstChildOrThrow`, `getLastChild`, `getLastChildOrThrow`,
+`getChildAtIndex`, `getFirstDescendant`, `getLastDescendant`,
+`getDescendantByIndex`, `$getNodeByKey` and `$getNodeByKeyOrThrow` from the
+TypeScript declarations and from the hand-maintained Flow declarations in the
+same release. TypeScript had shown them as `@deprecated` for several releases
+before that; Flow has no deprecation signal, so a Flow codebase saw no warning
+at all and every call site that passes a type argument stopped checking at
+once, with `nonpolymorphic-type-arg` and the `prop-missing` errors that follow
+it.
+
+The overloads are back in the Flow declarations only, still `@deprecated` and
+still unchecked casts. TypeScript is unchanged: it has no such overloads, and
+new code in either language should call these methods without a type argument
+and narrow the result with a node guard, as
+[Narrowing traversal results](https://lexical.dev/docs/concepts/traversals#narrowing-traversal-results)
+describes.
+
+Removal: not scheduled; it needs the remaining Flow call sites to be migrated
+first.

packages/lexical/flow/Lexical.js.flow

@@ -546,15 +546,71 @@ declare export class LexicalNode {
   getKey(): NodeKey;
   getIndexWithinParent(): number;
   getParent(): ElementNode | null;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getParent<T extends ElementNode>(): T | null;
   getParentOrThrow(): ElementNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getParentOrThrow<T extends ElementNode>(): T;
   getTopLevelElement(): DecoratorNode<unknown> | ElementNode | null;
   getTopLevelElementOrThrow(): DecoratorNode<unknown> | ElementNode;
   getParents(): ElementNode[];
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getParents<T extends ElementNode>(): T[];
   getParentKeys(): NodeKey[];
   getPreviousSibling(): LexicalNode | null;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getPreviousSibling<T extends LexicalNode>(): T | null;
   getPreviousSiblings(): LexicalNode[];
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getPreviousSiblings<T extends LexicalNode>(): T[];
   getNextSibling(): LexicalNode | null;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getNextSibling<T extends LexicalNode>(): T | null;
   getNextSiblings(): LexicalNode[];
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getNextSiblings<T extends LexicalNode>(): T[];
   is(object: ?LexicalNode): boolean;
   isBefore(targetNode: LexicalNode): boolean;
   isParentOf(targetNode: LexicalNode): boolean;
@@ -950,19 +1006,99 @@ declare export class ElementNode extends LexicalNode {
   getFormatType(): ElementFormatType;
   getIndent(): number;
   getChildren(): LexicalNode[];
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getChildren<T extends LexicalNode>(): T[];
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getChildren<T extends LexicalNode[]>(): T;
   getChildrenKeys(): NodeKey[];
   getChildrenSize(): number;
   isEmpty(): boolean;
   isDirty(): boolean;
   getAllTextNodes(): TextNode[];
   getFirstDescendant(): null | LexicalNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getFirstDescendant<T extends LexicalNode>(): null | T;
   getLastDescendant(): null | LexicalNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getLastDescendant<T extends LexicalNode>(): null | T;
   getDescendantByIndex(index: number): null | LexicalNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getDescendantByIndex<T extends LexicalNode>(index: number): null | T;
   getFirstChild(): null | LexicalNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getFirstChild<T extends LexicalNode>(): null | T;
   getFirstChildOrThrow(): LexicalNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getFirstChildOrThrow<T extends LexicalNode>(): T;
   getLastChild(): null | LexicalNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getLastChild<T extends LexicalNode>(): null | T;
   getLastChildOrThrow(): LexicalNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getLastChildOrThrow<T extends LexicalNode>(): T;
   getChildAtIndex(index: number): null | LexicalNode;
+  /**
+   * @deprecated The type parameter is an unchecked and unsafe cast. The
+   * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+   * until the Flow call sites that pass a type argument are migrated. Call
+   * this method without a type argument and narrow the result with a type
+   * guard instead.
+   */
+  getChildAtIndex<T extends LexicalNode>(index: number): null | T;
   getTextContent(): string;
   getDirection(): 'ltr' | 'rtl' | null;
   hasFormat(type: ElementFormatType): boolean;
@@ -1129,7 +1265,23 @@ declare export function $getNodeByKey(
   key: NodeKey,
   _editorState?: EditorState,
 ): LexicalNode | null;
+/**
+ * @deprecated The type parameter is an unchecked and unsafe cast. The
+ * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+ * until the Flow call sites that pass a type argument are migrated. Call
+ * this function without a type argument and narrow the result with a type
+ * guard instead.
+ */
+declare export function $getNodeByKey<N extends LexicalNode>(key: NodeKey): N | null;
 declare export function $getNodeByKeyOrThrow(key: NodeKey): LexicalNode;
+/**
+ * @deprecated The type parameter is an unchecked and unsafe cast. The
+ * TypeScript overload was removed in v0.53.0; this Flow overload is kept
+ * until the Flow call sites that pass a type argument are migrated. Call
+ * this function without a type argument and narrow the result with a type
+ * guard instead.
+ */
+declare export function $getNodeByKeyOrThrow<N extends LexicalNode>(key: NodeKey): N;
 declare export function $getRoot(): RootNode;
 declare export function $isLeafNode<T = unknown>(
   node: ?LexicalNode,