[core-tracing] Fix the return type of withSpan

sdk/core/core-tracing/review/core-tracing.api.md

@@ -4,6 +4,11 @@
 
 ```ts
 
+// @public
+export type AwaitedLike<T> = T extends object & {
+    then(onfulfilled: infer F): any;
+} ? F extends (value: infer V) => any ? AwaitedLike<V> : never : T;
+
 // @public
 export function createTracingClient(options: TracingClientOptions): TracingClient;
 
@@ -57,7 +62,7 @@ export interface TracingClient {
     withContext<CallbackArgs extends unknown[], Callback extends (...args: CallbackArgs) => ReturnType<Callback>>(context: TracingContext, callback: Callback, ...callbackArgs: CallbackArgs): ReturnType<Callback>;
     withSpan<Options extends {
         tracingOptions?: OperationTracingOptions;
-    }, Callback extends (updatedOptions: Options, span: Omit<TracingSpan, "end">) => ReturnType<Callback>>(name: string, operationOptions: Options, callback: Callback, spanOptions?: TracingSpanOptions): Promise<ReturnType<Callback>>;
+    }, Callback extends (updatedOptions: Options, span: Omit<TracingSpan, "end">) => ReturnType<Callback>>(name: string, operationOptions: Options, callback: Callback, spanOptions?: TracingSpanOptions): Promise<AwaitedLike<ReturnType<Callback>>>;
 }
 
 // @public

sdk/core/core-tracing/src/index.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license.
 
 export {
+  AwaitedLike,
   Instrumenter,
   InstrumenterSpanOptions,
   OperationTracingOptions,

sdk/core/core-tracing/src/interfaces.ts

@@ -1,6 +1,17 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+/**
+ * A narrower version of TypeScript 4.5's Awaited type which Recursively
+ * unwraps the "awaited type", emulating the behavior of `await`.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types -- I want to stay consistent with TypeScript 4.5's Awaited type
+export type AwaitedLike<T> = T extends object & { then(onfulfilled: infer F): any } // `await` only unwraps object types with a callable `then`. Non-object types are not unwrapped
+  ? F extends (value: infer V) => any // if the argument to `then` is callable, extracts the first argument
+    ? AwaitedLike<V> // recursively unwrap the value
+    : never // the argument to `then` was not callable
+  : T; // non-object or non-thenable
+
 /**
  * Represents a client that can integrate with the currently configured {@link Instrumenter}.
  *
@@ -12,6 +23,8 @@ export interface TracingClient {
    *
    * This is the primary interface for using Tracing and will handle error recording as well as setting the status on the span.
    *
+   * Both synchronous and asynchronous functions will be awaited in order to reflect the result of the callback on the span.
+   *
    * Example:
    *
    * ```ts
@@ -32,7 +45,7 @@ export interface TracingClient {
     operationOptions: Options,
     callback: Callback,
     spanOptions?: TracingSpanOptions
-  ): Promise<ReturnType<Callback>>;
+  ): Promise<AwaitedLike<ReturnType<Callback>>>;
   /**
    * Starts a given span but does not set it as the active span.
    *

sdk/core/core-tracing/src/tracingClient.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license.
 
 import {
+  AwaitedLike,
   OperationTracingOptions,
   TracingClient,
   TracingClientOptions,
@@ -64,14 +65,14 @@ export function createTracingClient(options: TracingClientOptions): TracingClien
     operationOptions: Options,
     callback: Callback,
     spanOptions?: TracingSpanOptions
-  ): Promise<ReturnType<Callback>> {
+  ): Promise<AwaitedLike<ReturnType<Callback>>> {
     const { span, updatedOptions } = startSpan(name, operationOptions, spanOptions);
     try {
       const result = await withContext(updatedOptions.tracingOptions!.tracingContext!, () =>
         Promise.resolve(callback(updatedOptions, span))
       );
       span.setStatus({ status: "success" });
-      return result;
+      return result as ReturnType<typeof withSpan>;
     } catch (err) {
       span.setStatus({ status: "error", error: err });
       throw err;