Make NodeHandle generic and generate .Handle members of is-guards for guarding node handles (sync and async)

_packages/native-preview/src/api/async/api.ts

@@ -13,8 +13,10 @@ import { TypeFlags } from "#enums/typeFlags";
 import { TypePredicateKind } from "#enums/typePredicateKind";
 import {
     type __String,
+    type Declaration,
     type Expression,
     type Identifier,
+    type IndexSignatureDeclaration,
     ModifierFlags,
     type Node,
     type Path,
@@ -696,7 +698,7 @@ class ProjectObjectRegistry {
             keyType: this.getOrCreateType(info.keyType),
             valueType: this.getOrCreateType(info.valueType),
             isReadonly: info.isReadonly ?? false,
-            declaration: info.declaration ? new NodeHandle(info.declaration, this.project) : undefined,
+            declaration: info.declaration ? new NodeHandle<IndexSignatureDeclaration>(info.declaration, this.project) : undefined,
         }));
     }
 
@@ -1876,7 +1878,7 @@ export class Emitter {
     }
 }
 
-export class NodeHandle {
+export class NodeHandle<out T extends Node = Node> {
     /**
      * The project this handle was produced in, used as the default for {@link resolve}.
      * Node handles are only meaningful within a project's program, so the producing project
@@ -1900,12 +1902,12 @@ export class NodeHandle {
      * and looking up the node by index. If no project is passed, the project that produced
      * the handle is used.
      */
-    async resolve(project: Project = this.canonicalProject): Promise<Node | undefined> {
+    async resolve(project: Project = this.canonicalProject): Promise<T | undefined> {
         const sourceFile = await project.program.getSourceFile(this.path);
         if (!sourceFile) {
             return undefined;
         }
-        return (sourceFile as unknown as RemoteSourceFile).getOrCreateNodeAtIndex(this.index);
+        return (sourceFile as unknown as RemoteSourceFile).getOrCreateNodeAtIndex(this.index) as T | undefined;
     }
 }
 
@@ -1943,8 +1945,8 @@ export class Symbol {
     readonly name: string;
     readonly flags: SymbolFlags;
     readonly checkFlags: CheckFlags;
-    readonly declarations: readonly NodeHandle[];
-    readonly valueDeclaration: NodeHandle | undefined;
+    readonly declarations: readonly NodeHandle<Declaration>[];
+    readonly valueDeclaration: NodeHandle<Declaration> | undefined;
     private readonly parent!: number;
     private readonly exportSymbol!: number;
     private membersCache: Promise<ReadonlyMap<__String, Symbol>> | undefined;
@@ -1963,8 +1965,8 @@ export class Symbol {
             throw new Error(`Symbol ${data.id} references unknown canonical project '${data.project}'`);
         }
         this.canonicalProject = canonicalProject;
-        this.declarations = (data.declarations ?? []).map(d => new NodeHandle(d, canonicalProject));
-        this.valueDeclaration = data.valueDeclaration ? new NodeHandle(data.valueDeclaration, canonicalProject) : undefined;
+        this.declarations = (data.declarations ?? []).map(d => new NodeHandle<Declaration>(d, canonicalProject));
+        this.valueDeclaration = data.valueDeclaration ? new NodeHandle<Declaration>(data.valueDeclaration, canonicalProject) : undefined;
 
         if (data.parent !== undefined) this.parent = data.parent;
         if (data.exportSymbol !== undefined) this.exportSymbol = data.exportSymbol;
@@ -2469,7 +2471,7 @@ export class Signature {
     private objectRegistry: ProjectObjectRegistry;
 
     readonly id: number;
-    readonly declaration?: NodeHandle | undefined;
+    readonly declaration?: NodeHandle<Declaration> | undefined;
     readonly typeParameters?: readonly number[] | undefined;
     readonly parameters: readonly number[];
     readonly thisParameter?: number | undefined;
@@ -2480,7 +2482,7 @@ export class Signature {
         this.id = data.id;
         this.flags = data.flags;
         this.objectRegistry = objectRegistry;
-        this.declaration = data.declaration ? new NodeHandle(data.declaration, project) : undefined;
+        this.declaration = data.declaration ? new NodeHandle<Declaration>(data.declaration, project) : undefined;
         this.typeParameters = data.typeParameters ?? [];
         this.parameters = data.parameters ?? [];
         this.thisParameter = data.thisParameter;

_packages/native-preview/src/api/async/types.ts

@@ -3,6 +3,7 @@ import type { ElementFlags } from "#enums/elementFlags";
 import type { ObjectFlags } from "#enums/objectFlags";
 import type { TypeFlags } from "#enums/typeFlags";
 import type { TypePredicateKind } from "#enums/typePredicateKind";
+import type { IndexSignatureDeclaration } from "../../ast/ast.ts";
 import type { Diagnostic } from "../proto.ts";
 import type {
     NodeHandle,
@@ -319,7 +320,7 @@ export interface IndexInfo {
     /** Whether the index signature is readonly */
     readonly isReadonly: boolean;
     /** The index signature declaration, if any */
-    readonly declaration?: NodeHandle | undefined;
+    readonly declaration?: NodeHandle<IndexSignatureDeclaration> | undefined;
 }
 
 /**

_packages/native-preview/src/api/sync/api.ts

@@ -21,8 +21,10 @@ import { TypeFlags } from "#enums/typeFlags";
 import { TypePredicateKind } from "#enums/typePredicateKind";
 import {
     type __String,
+    type Declaration,
     type Expression,
     type Identifier,
+    type IndexSignatureDeclaration,
     ModifierFlags,
     type Node,
     type Path,
@@ -704,7 +706,7 @@ class ProjectObjectRegistry {
             keyType: this.getOrCreateType(info.keyType),
             valueType: this.getOrCreateType(info.valueType),
             isReadonly: info.isReadonly ?? false,
-            declaration: info.declaration ? new NodeHandle(info.declaration, this.project) : undefined,
+            declaration: info.declaration ? new NodeHandle<IndexSignatureDeclaration>(info.declaration, this.project) : undefined,
         }));
     }
 
@@ -1884,7 +1886,7 @@ export class Emitter {
     }
 }
 
-export class NodeHandle {
+export class NodeHandle<out T extends Node = Node> {
     /**
      * The project this handle was produced in, used as the default for {@link resolve}.
      * Node handles are only meaningful within a project's program, so the producing project
@@ -1908,12 +1910,12 @@ export class NodeHandle {
      * and looking up the node by index. If no project is passed, the project that produced
      * the handle is used.
      */
-    resolve(project: Project = this.canonicalProject): Node | undefined {
+    resolve(project: Project = this.canonicalProject): T | undefined {
         const sourceFile = project.program.getSourceFile(this.path);
         if (!sourceFile) {
             return undefined;
         }
-        return (sourceFile as unknown as RemoteSourceFile).getOrCreateNodeAtIndex(this.index);
+        return (sourceFile as unknown as RemoteSourceFile).getOrCreateNodeAtIndex(this.index) as T | undefined;
     }
 }
 
@@ -1951,8 +1953,8 @@ export class Symbol {
     readonly name: string;
     readonly flags: SymbolFlags;
     readonly checkFlags: CheckFlags;
-    readonly declarations: readonly NodeHandle[];
-    readonly valueDeclaration: NodeHandle | undefined;
+    readonly declarations: readonly NodeHandle<Declaration>[];
+    readonly valueDeclaration: NodeHandle<Declaration> | undefined;
     private readonly parent!: number;
     private readonly exportSymbol!: number;
     private membersCache: ReadonlyMap<__String, Symbol> | undefined;
@@ -1971,8 +1973,8 @@ export class Symbol {
             throw new Error(`Symbol ${data.id} references unknown canonical project '${data.project}'`);
         }
         this.canonicalProject = canonicalProject;
-        this.declarations = (data.declarations ?? []).map(d => new NodeHandle(d, canonicalProject));
-        this.valueDeclaration = data.valueDeclaration ? new NodeHandle(data.valueDeclaration, canonicalProject) : undefined;
+        this.declarations = (data.declarations ?? []).map(d => new NodeHandle<Declaration>(d, canonicalProject));
+        this.valueDeclaration = data.valueDeclaration ? new NodeHandle<Declaration>(data.valueDeclaration, canonicalProject) : undefined;
 
         if (data.parent !== undefined) this.parent = data.parent;
         if (data.exportSymbol !== undefined) this.exportSymbol = data.exportSymbol;
@@ -2477,7 +2479,7 @@ export class Signature {
     private objectRegistry: ProjectObjectRegistry;
 
     readonly id: number;
-    readonly declaration?: NodeHandle | undefined;
+    readonly declaration?: NodeHandle<Declaration> | undefined;
     readonly typeParameters?: readonly number[] | undefined;
     readonly parameters: readonly number[];
     readonly thisParameter?: number | undefined;
@@ -2488,7 +2490,7 @@ export class Signature {
         this.id = data.id;
         this.flags = data.flags;
         this.objectRegistry = objectRegistry;
-        this.declaration = data.declaration ? new NodeHandle(data.declaration, project) : undefined;
+        this.declaration = data.declaration ? new NodeHandle<Declaration>(data.declaration, project) : undefined;
         this.typeParameters = data.typeParameters ?? [];
         this.parameters = data.parameters ?? [];
         this.thisParameter = data.thisParameter;

_packages/native-preview/src/api/sync/types.ts

@@ -11,6 +11,7 @@ import type { ElementFlags } from "#enums/elementFlags";
 import type { ObjectFlags } from "#enums/objectFlags";
 import type { TypeFlags } from "#enums/typeFlags";
 import type { TypePredicateKind } from "#enums/typePredicateKind";
+import type { IndexSignatureDeclaration } from "../../ast/ast.ts";
 import type { Diagnostic } from "../proto.ts";
 import type {
     NodeHandle,
@@ -327,7 +328,7 @@ export interface IndexInfo {
     /** Whether the index signature is readonly */
     readonly isReadonly: boolean;
     /** The index signature declaration, if any */
-    readonly declaration?: NodeHandle | undefined;
+    readonly declaration?: NodeHandle<IndexSignatureDeclaration> | undefined;
 }
 
 /**