diff --git a/.changeset/restore-flow-unchecked-node-type-arguments.md b/.changeset/restore-flow-unchecked-node-type-arguments.md new file mode 100644 index 00000000000..ddb78f9a483 --- /dev/null +++ b/.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. diff --git a/packages/lexical/flow/Lexical.js.flow b/packages/lexical/flow/Lexical.js.flow index f9519bbace9..797b63b18d7 100644 --- a/packages/lexical/flow/Lexical.js.flow +++ b/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 | 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; getTopLevelElement(): DecoratorNode | ElementNode | null; getTopLevelElementOrThrow(): DecoratorNode | 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[]; 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 | 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[]; 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 | 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[]; 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[]; + /** + * @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; 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(): 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(): 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(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(): 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; 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(): 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; 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(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(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(key: NodeKey): N; declare export function $getRoot(): RootNode; declare export function $isLeafNode( node: ?LexicalNode,