[api] Add option to collect timing info (#4512)

Author: andrewbranch

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

@@ -67,6 +67,11 @@ import {
     toUpdateSnapshotRequest,
 } from "../proto.ts";
 import { SourceFileCache } from "../sourceFileCache.ts";
+import type {
+    RequestTiming,
+    TimingAccumulators,
+    TimingInfo,
+} from "../timing.ts";
 import {
     Client,
     type ClientSocketOptions,
@@ -109,10 +114,9 @@ import type {
     UnionType,
 } from "./types.ts";
 
-export { CompletionItemKind, DiagnosticCategory, ElementFlags, ModifierFlags, ModuleKind, NodeBuilderFlags, ObjectFlags, SignatureFlags, SignatureKind, SymbolFlags, TypeFlags, TypePredicateKind };
-export type { APIOptions, ClientSocketOptions, ClientSpawnOptions, CompilerOptions, DocumentIdentifier, DocumentPosition, LSPConnectionOptions, SourceFileMetadata };
-export type { AssertsIdentifierTypePredicate, AssertsThisTypePredicate, BigIntLiteralType, BooleanLiteralType, CompletionEntry, CompletionInfo, CompletionOptions, ConditionalType, Diagnostic, FreshableType, IdentifierTypePredicate, IndexedAccessType, IndexInfo, IndexType, InterfaceType, IntersectionType, IntrinsicType, JSDocTagInfo, LiteralType, NumberLiteralType, ObjectType, StringLiteralType, StringMappingType, SubstitutionType, TemplateLiteralType, ThisTypePredicate, TupleType, Type, TypeParameter, TypePredicate, TypePredicateBase, TypeReference, UnionOrIntersectionType, UnionType };
 export { documentURIToFileName, fileNameToDocumentURI } from "../path.ts";
+export { CompletionItemKind, DiagnosticCategory, ElementFlags, ModifierFlags, ModuleKind, NodeBuilderFlags, ObjectFlags, SignatureFlags, SignatureKind, SymbolFlags, TypeFlags, TypePredicateKind };
+export type { APIOptions, AssertsIdentifierTypePredicate, AssertsThisTypePredicate, BigIntLiteralType, BooleanLiteralType, ClientSocketOptions, ClientSpawnOptions, CompilerOptions, CompletionEntry, CompletionInfo, CompletionOptions, ConditionalType, Diagnostic, DocumentIdentifier, DocumentPosition, FreshableType, IdentifierTypePredicate, IndexedAccessType, IndexInfo, IndexType, InterfaceType, IntersectionType, IntrinsicType, JSDocTagInfo, LiteralType, LSPConnectionOptions, NumberLiteralType, ObjectType, RequestTiming, SourceFileMetadata, StringLiteralType, StringMappingType, SubstitutionType, TemplateLiteralType, ThisTypePredicate, TimingAccumulators, TimingInfo, TupleType, Type, TypeParameter, TypePredicate, TypePredicateBase, TypeReference, UnionOrIntersectionType, UnionType };
 
 export class API<FromLSP extends boolean = false> {
     private client: Client;
@@ -203,6 +207,26 @@ export class API<FromLSP extends boolean = false> {
     clearSourceFileCache(): void {
         this.sourceFileCache.clear();
     }
+
+    /**
+     * Returns a snapshot of collected timing information for requests made
+     * through this API instance: client-measured round-trip latency and bytes
+     * transferred, folded together with the server's own per-request processing
+     * time and an estimated transport overhead (round-trip minus server time).
+     *
+     * Fetching the snapshot issues a lightweight request to the server to
+     * retrieve its timing collection. Collection must be enabled via the
+     * `collectTiming` option; when it is not, the returned snapshot has
+     * `enabled: false` and zeroed totals.
+     */
+    getTimingInfo(): Promise<TimingInfo> {
+        return this.client.getTimingInfo();
+    }
+
+    /** Clears all accumulated timing totals and recent-request history, on both the client and the server. */
+    resetTimingInfo(): Promise<void> {
+        return this.client.resetTimingInfo();
+    }
 }
 
 export class InternalAPI {
@@ -612,7 +636,7 @@ export class Program {
         const parseOptionsKey = readParseOptionsKey(view);
 
         // Create a new RemoteSourceFile and cache it (set returns existing if hash matches)
-        const sourceFile = new RemoteSourceFile(binaryData, this.decoder) as unknown as SourceFile;
+        const sourceFile = new RemoteSourceFile(binaryData, this.decoder, this.client.getTimingCollector()) as unknown as SourceFile;
         return this.sourceFileCache.set(path, sourceFile, parseOptionsKey, contentHash, this.snapshotId, this.project.id);
     }
 

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

@@ -20,6 +20,14 @@ import {
     isSpawnOptions,
     resolveExePath,
 } from "../options.ts";
+import {
+    combineTimingInfo,
+    disabledServerTimingInfo,
+    disabledTimingInfo,
+    type ServerTimingInfo,
+    TimingCollector,
+    type TimingInfo,
+} from "../timing.ts";
 
 export type { ClientOptions, ClientSocketOptions, ClientSpawnOptions };
 
@@ -33,9 +41,13 @@ export class Client {
     private connection: MessageConnection | undefined;
     private options: ClientOptions;
     private connected = false;
+    private timing: TimingCollector | undefined;
 
     constructor(options: ClientOptions) {
         this.options = options;
+        if (isSpawnOptions(options) && options.collectTiming) {
+            this.timing = new TimingCollector();
+        }
     }
 
     async connect(): Promise<void> {
@@ -60,6 +72,10 @@ export class Client {
                 options.cwd ?? process.cwd(),
             ];
 
+            if (options.collectTiming) {
+                args.push("--timing");
+            }
+
             // Enable virtual FS callbacks for each provided FS function
             const enabledCallbacks: string[] = [];
             if (options.fs) {
@@ -142,7 +158,27 @@ export class Client {
         }
 
         const requestType = new RequestType<unknown, T, void>(method);
-        return this.connection.sendRequest(requestType, params);
+        if (!this.timing) {
+            return this.connection.sendRequest(requestType, params);
+        }
+
+        // Round-trip latency is measured here; byte counts approximate the wire
+        // payload via the serialized JSON. Server-side processing time is not
+        // carried on the response; it is retrieved separately (via a
+        // getServerTiming request) and folded in by getTimingInfo().
+        const bytesSent = params === undefined ? 0 : Buffer.byteLength(JSON.stringify(params), "utf-8");
+        const start = performance.now();
+        const result = await this.connection.sendRequest(requestType, params);
+        const roundTripMs = performance.now() - start;
+        this.timing.record({
+            method,
+            roundTripMs,
+            bytesSent,
+            bytesReceived: result === undefined || result === null
+                ? 0
+                : Buffer.byteLength(JSON.stringify(result), "utf-8"),
+        });
+        return result;
     }
 
     async apiRequestBinary(method: string, params?: unknown): Promise<Uint8Array | undefined> {
@@ -152,6 +188,53 @@ export class Client {
         return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
     }
 
+    /**
+     * Returns the timing collector that per-node materialization is reported
+     * into, or undefined when timing collection is disabled. The returned
+     * collector is the same one folded into {@link getTimingInfo}, so
+     * materialization totals surface alongside request timings.
+     */
+    getTimingCollector(): TimingCollector | undefined {
+        return this.timing;
+    }
+
+    /**
+     * Returns a combined timing snapshot: client-measured round-trip and byte
+     * counts folded together with the server's own per-request processing time
+     * (fetched via a getServerTiming request) and estimated transport overhead.
+     */
+    async getTimingInfo(): Promise<TimingInfo> {
+        if (!this.timing) {
+            return disabledTimingInfo();
+        }
+        const local = this.timing.getInfo();
+        // No requests have been sent yet: nothing to fetch from the server.
+        if (!this.connected || !this.connection) {
+            return local;
+        }
+        return combineTimingInfo(local, await this.fetchServerTiming());
+    }
+
+    async resetTimingInfo(): Promise<void> {
+        if (!this.timing) return;
+        this.timing.reset();
+        if (this.connected && this.connection) {
+            // Keep the server's collection in sync so combined totals stay meaningful.
+            const requestType = new RequestType<unknown, void, void>("resetServerTiming");
+            await this.connection.sendRequest(requestType, undefined);
+        }
+    }
+
+    private async fetchServerTiming(): Promise<ServerTimingInfo> {
+        if (!this.connection) {
+            return disabledServerTimingInfo();
+        }
+        // Fetch the server's own timing collection via a dedicated request. This
+        // bypasses the client-side collector so the query does not pollute it.
+        const requestType = new RequestType<unknown, ServerTimingInfo, void>("getServerTiming");
+        return this.connection.sendRequest(requestType, undefined);
+    }
+
     async close(): Promise<void> {
         if (this.connection) {
             this.connection.dispose();

_packages/native-preview/src/api/node/node.generated.ts

@@ -180,8 +180,10 @@ export class RemoteNodeList extends Array<RemoteNode> implements NodeArray<Remot
             if (kind === KIND_NODE_LIST) {
                 throw new Error("NodeList cannot directly contain another NodeList");
             }
-            child = new RemoteNode(this.view, index, this.parent, this.sourceFile, this.sourceFile._offsetNodes);
-            this.sourceFile.nodes[index] = child;
+            const sf = this.sourceFile;
+            child = new RemoteNode(this.view, index, this.parent, sf, sf._offsetNodes);
+            sf.nodes[index] = child;
+            sf._timing?.recordMaterialization();
         }
         return child;
     }
@@ -308,13 +310,14 @@ export class RemoteNode extends RemoteNodeBase implements Node {
     private getOrCreateChildAtNodeIndex(index: number): RemoteNode | RemoteNodeList {
         let child = this.sourceFile.nodes[index];
         if (!child) {
-            const offsetNodes = this.sourceFile._offsetNodes;
-            const kind = this.view.getUint32(offsetNodes + index * NODE_LEN + NODE_OFFSET_KIND, true);
             const sf = this.sourceFile;
+            const offsetNodes = sf._offsetNodes;
+            const kind = this.view.getUint32(offsetNodes + index * NODE_LEN + NODE_OFFSET_KIND, true);
             child = kind === KIND_NODE_LIST
                 ? new RemoteNodeList(this.view, index, this, sf, offsetNodes)
                 : new RemoteNode(this.view, index, this, sf, offsetNodes);
             sf.nodes[index] = child;
+            sf._timing?.recordMaterialization();
         }
         return child;
     }

_packages/native-preview/src/api/node/node.infrastructure.ts

@@ -4,6 +4,7 @@ import {
     type Node,
     SyntaxKind,
 } from "../../ast/index.ts";
+import type { TimingCollector } from "../timing.ts";
 import {
     HEADER_OFFSET_HASH_HI0,
     HEADER_OFFSET_HASH_HI1,
@@ -52,6 +53,13 @@ export interface SourceFileInfo {
     readonly _decoder: TextDecoder;
     nodes: any[];
     readonly path?: string;
+    /**
+     * The timing collector that per-node materialization is reported into, and
+     * that this source file registered itself with when fetched. Present only
+     * when timing collection is enabled; when undefined, materialization is not
+     * timed and no clock is read.
+     */
+    readonly _timing?: TimingCollector | undefined;
     readFileReferences(offset: number): readonly FileReference[];
     readNodeIndexArray(offset: number): readonly Node[];
     readStringArray(offset: number): readonly string[];

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

@@ -6,6 +6,7 @@ import {
     SyntaxKind,
     TokenFlags,
 } from "../../ast/index.ts";
+import type { TimingCollector } from "../timing.ts";
 import { MsgpackReader } from "./msgpack.ts";
 import {
     RemoteNode,
@@ -47,6 +48,7 @@ export class RemoteSourceFile extends RemoteNode implements SourceFileInfo {
     readonly _offsetExtendedData: number;
     readonly _offsetStructuredData: number;
     readonly _decoder: TextDecoder;
+    readonly _timing: TimingCollector | undefined;
     private _cachedText: string | undefined;
     private _cachedReferencedFiles: readonly FileReference[] | undefined;
     private _cachedTypeReferenceDirectives: readonly FileReference[] | undefined;
@@ -55,7 +57,7 @@ export class RemoteSourceFile extends RemoteNode implements SourceFileInfo {
     private _cachedModuleAugmentations: readonly Node[] | undefined;
     private _cachedAmbientModuleNames: readonly string[] | undefined;
 
-    constructor(data: Uint8Array, decoder: TextDecoder) {
+    constructor(data: Uint8Array, decoder: TextDecoder, timing?: TimingCollector) {
         const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
         const offsetNodes = view.getUint32(HEADER_OFFSET_NODES, true);
         super(view, 1, undefined!, undefined!, offsetNodes);
@@ -66,8 +68,12 @@ export class RemoteSourceFile extends RemoteNode implements SourceFileInfo {
         this._offsetExtendedData = view.getUint32(HEADER_OFFSET_EXTENDED_DATA, true);
         this._offsetStructuredData = view.getUint32(HEADER_OFFSET_STRUCTURED_DATA, true);
         this._decoder = decoder;
+        this._timing = timing;
         this.nodes = Array((view.byteLength - offsetNodes) / NODE_LEN);
         this.nodes[1] = this;
+        // Every node slot is materializable on demand except the nil sentinel at
+        // index 0 and the source-file node at index 1, which is pre-materialized.
+        timing?.recordSourceFileFetched(Math.max(0, this.nodes.length - 2));
     }
 
     readFileReferences(structuredDataOffset: number): readonly FileReference[] {
@@ -139,6 +145,7 @@ export class RemoteSourceFile extends RemoteNode implements SourceFileInfo {
             const parent = parentIndex === index ? this : this.getOrCreateNodeAtIndex(parentIndex) as RemoteNode;
             node = new RemoteNode(this.view, index, parent, this, this._offsetNodes);
             this.nodes[index] = node;
+            this._timing?.recordMaterialization();
         }
         return node as Node;
     }

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

@@ -17,6 +17,14 @@ export interface ClientSpawnOptions {
     cwd?: string;
     /** Virtual filesystem callbacks */
     fs?: FileSystem;
+    /**
+     * When true, collect timing information for each request. The client
+     * measures round-trip latency and bytes sent/received, and the server
+     * measures its own per-request processing time; both are combined (along
+     * with an estimated transport overhead) in the snapshot returned by
+     * {@link API.getTimingInfo}.
+     */
+    collectTiming?: boolean;
 }
 
 export type ClientOptions = ClientSocketOptions | ClientSpawnOptions;

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

@@ -75,6 +75,11 @@ import {
     toUpdateSnapshotRequest,
 } from "../proto.ts";
 import { SourceFileCache } from "../sourceFileCache.ts";
+import type {
+    RequestTiming,
+    TimingAccumulators,
+    TimingInfo,
+} from "../timing.ts";
 import {
     Client,
     type ClientSocketOptions,
@@ -117,10 +122,9 @@ import type {
     UnionType,
 } from "./types.ts";
 
-export { CompletionItemKind, DiagnosticCategory, ElementFlags, ModifierFlags, ModuleKind, NodeBuilderFlags, ObjectFlags, SignatureFlags, SignatureKind, SymbolFlags, TypeFlags, TypePredicateKind };
-export type { APIOptions, ClientSocketOptions, ClientSpawnOptions, CompilerOptions, DocumentIdentifier, DocumentPosition, LSPConnectionOptions, SourceFileMetadata };
-export type { AssertsIdentifierTypePredicate, AssertsThisTypePredicate, BigIntLiteralType, BooleanLiteralType, CompletionEntry, CompletionInfo, CompletionOptions, ConditionalType, Diagnostic, FreshableType, IdentifierTypePredicate, IndexedAccessType, IndexInfo, IndexType, InterfaceType, IntersectionType, IntrinsicType, JSDocTagInfo, LiteralType, NumberLiteralType, ObjectType, StringLiteralType, StringMappingType, SubstitutionType, TemplateLiteralType, ThisTypePredicate, TupleType, Type, TypeParameter, TypePredicate, TypePredicateBase, TypeReference, UnionOrIntersectionType, UnionType };
 export { documentURIToFileName, fileNameToDocumentURI } from "../path.ts";
+export { CompletionItemKind, DiagnosticCategory, ElementFlags, ModifierFlags, ModuleKind, NodeBuilderFlags, ObjectFlags, SignatureFlags, SignatureKind, SymbolFlags, TypeFlags, TypePredicateKind };
+export type { APIOptions, AssertsIdentifierTypePredicate, AssertsThisTypePredicate, BigIntLiteralType, BooleanLiteralType, ClientSocketOptions, ClientSpawnOptions, CompilerOptions, CompletionEntry, CompletionInfo, CompletionOptions, ConditionalType, Diagnostic, DocumentIdentifier, DocumentPosition, FreshableType, IdentifierTypePredicate, IndexedAccessType, IndexInfo, IndexType, InterfaceType, IntersectionType, IntrinsicType, JSDocTagInfo, LiteralType, LSPConnectionOptions, NumberLiteralType, ObjectType, RequestTiming, SourceFileMetadata, StringLiteralType, StringMappingType, SubstitutionType, TemplateLiteralType, ThisTypePredicate, TimingAccumulators, TimingInfo, TupleType, Type, TypeParameter, TypePredicate, TypePredicateBase, TypeReference, UnionOrIntersectionType, UnionType };
 
 export class API<FromLSP extends boolean = false> {
     private client: Client;
@@ -211,6 +215,26 @@ export class API<FromLSP extends boolean = false> {
     clearSourceFileCache(): void {
         this.sourceFileCache.clear();
     }
+
+    /**
+     * Returns a snapshot of collected timing information for requests made
+     * through this API instance: client-measured round-trip latency and bytes
+     * transferred, folded together with the server's own per-request processing
+     * time and an estimated transport overhead (round-trip minus server time).
+     *
+     * Fetching the snapshot issues a lightweight request to the server to
+     * retrieve its timing collection. Collection must be enabled via the
+     * `collectTiming` option; when it is not, the returned snapshot has
+     * `enabled: false` and zeroed totals.
+     */
+    getTimingInfo(): TimingInfo {
+        return this.client.getTimingInfo();
+    }
+
+    /** Clears all accumulated timing totals and recent-request history, on both the client and the server. */
+    resetTimingInfo(): void {
+        return this.client.resetTimingInfo();
+    }
 }
 
 export class InternalAPI {
@@ -620,7 +644,7 @@ export class Program {
         const parseOptionsKey = readParseOptionsKey(view);
 
         // Create a new RemoteSourceFile and cache it (set returns existing if hash matches)
-        const sourceFile = new RemoteSourceFile(binaryData, this.decoder) as unknown as SourceFile;
+        const sourceFile = new RemoteSourceFile(binaryData, this.decoder, this.client.getTimingCollector()) as unknown as SourceFile;
         return this.sourceFileCache.set(path, sourceFile, parseOptionsKey, contentHash, this.snapshotId, this.project.id);
     }