allow pushScope to push an already-existing scope

Author: lobsterkatie

packages/hub/src/hub.ts

@@ -127,14 +127,16 @@ export class Hub implements HubInterface {
   /**
    * @inheritDoc
    */
-  public pushScope(): Scope {
-    // We want to clone the content of prev scope
-    const scope = Scope.clone(this.getScope());
+  public pushScope(scope?: Scope): Scope {
+    // Use a clone of the current scope if no scope is given
+    const newScope = Scope.clone(scope || this.getScope());
+
     this.getStack().push({
       client: this.getClient(),
-      scope,
+      scope: newScope,
     });
-    return scope;
+
+    return newScope;
   }
 
   /**

packages/types/src/hub.ts

@@ -35,14 +35,18 @@ export interface Hub {
   /**
    * Create a new scope to store context information.
    *
-   * The scope will be layered on top of the current one. It is isolated, i.e. all
-   * breadcrumbs and context information added to this scope will be removed once
-   * the scope ends. Be sure to always remove this scope with {@link this.popScope}
-   * when the operation finishes or throws.
+   * If an existing scope is given, it will be cloned and that clone used as the new scope. If no scope is given, a
+   * clone of the currently-active scope will be used.
    *
-   * @returns Scope, the new cloned scope
+   * The cloned scope will be layered on top of the current one. It is isolated, i.e. it does not mutate the given scope
+   * (if any) or the current scope. So, for example, all breadcrumbs and context information added to this scope will be
+   * removed once the scope ends. Be sure to always remove this scope with {@link this.popScope} when the operation
+   * finishes or throws.
+   *
+   * @param scope An existing scope to clone for use as the new scope
+   * @returns The newly-active scope
    */
-  pushScope(): Scope;
+  pushScope(scope?: Scope): Scope;
 
   /**
    * Removes a previously pushed scope from the stack.