[ServiceBus] expose omitMessagesBody option under ./experimental subpath (#31361)

playing with the idea of exposing features under the `./experimental`
subpath and add a dev-tool command to report error if we consume
experimental Apis in a GA package.

[ServiceBus] Add the experimental diagnostic feature omitMessageBody 

via an augmented `PeekMessagesOptions` interface under `./experimental`
subpath export.

After migrating to ESM, we no longer use rolled-up dts files thus lose the ability
to trim `@beta` Apis from public type definition files. This PR explores an approach to
expose Apis from the `./experimental` export.

Author: jeremymeng

sdk/servicebus/service-bus/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Features Added
 
 - Adds `deleteMessages` which deletes messages from the queue.
+- Add the experimental diagnostic feature `omitMessageBody` via `PeekMessagesOptions` under `./experimental` subpath export.
 
 ### Breaking Changes
 
@@ -424,8 +425,8 @@ If migrating from version 1.1.10 or lower, look at our [migration guide to move
 
   ```typescript
   // this same method will work with subscriptions as well.
-  serviceBusClient.createReceiver(<queue>, {
-    subQueue: "deadLetter"
+  serviceBusClient.createReceiver("<queue name>", {
+    subQueue: "deadLetter",
   });
   ```
 

sdk/servicebus/service-bus/package.json

@@ -143,7 +143,8 @@
   "tshy": {
     "exports": {
       "./package.json": "./package.json",
-      ".": "./src/index.ts"
+      ".": "./src/index.ts",
+      "./experimental": "./src/experimental/index.ts"
     },
     "dialects": [
       "esm",
@@ -174,6 +175,24 @@
         "types": "./dist/commonjs/index.d.ts",
         "default": "./dist/commonjs/index.js"
       }
+    },
+    "./experimental": {
+      "browser": {
+        "types": "./dist/browser/experimental/index.d.ts",
+        "default": "./dist/browser/experimental/index.js"
+      },
+      "react-native": {
+        "types": "./dist/react-native/experimental/index.d.ts",
+        "default": "./dist/react-native/experimental/index.js"
+      },
+      "import": {
+        "types": "./dist/esm/experimental/index.d.ts",
+        "default": "./dist/esm/experimental/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/experimental/index.d.ts",
+        "default": "./dist/commonjs/experimental/index.js"
+      }
     }
   }
 }

sdk/servicebus/service-bus/review/service-bus-experimental.api.md

@@ -0,0 +1,9 @@
+## API Report File for "@azure/service-bus"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// (No @packageDocumentation comment for this package)
+
+```

sdk/servicebus/service-bus/review/service-bus.api.md

@@ -211,8 +211,6 @@ export function parseServiceBusConnectionString(connectionString: string): Servi
 // @public
 export interface PeekMessagesOptions extends OperationOptionsBase {
     fromSequenceNumber?: Long;
-    // @beta
-    omitMessageBody?: boolean;
 }
 
 // @public

sdk/servicebus/service-bus/src/experimental/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+declare module "../models.js" {
+  interface PeekMessagesOptions {
+    /**
+     * (Experimental for diagnostic purpose) Specifies whether to omit the body when peeking messages. Default value `false`.
+     */
+    omitMessageBody?: boolean;
+  }
+}

sdk/servicebus/service-bus/src/models.ts

@@ -320,11 +320,6 @@ export interface PeekMessagesOptions extends OperationOptionsBase {
    * The sequence number to start peeking messages from (inclusive).
    */
   fromSequenceNumber?: Long;
-  /**
-   * @beta
-   * (Experimental for diagnostic purpose) Specifies whether to omit the body when peeking messages. Default  value `false`.
-   */
-  omitMessageBody?: boolean;
 }
 
 /**

sdk/servicebus/service-bus/src/receivers/receiver.ts

@@ -547,21 +547,25 @@ export class ServiceBusReceiverImpl implements ServiceBusReceiver {
       skipParsingBodyAsJson: this.skipParsingBodyAsJson,
       skipConvertingDate: this.skipConvertingDate,
     };
+    // omitMessageBody is available at runtime, but only exported in experimental subpath
+    const { fromSequenceNumber, omitMessageBody } = options as PeekMessagesOptions & {
+      omitMessageBody: boolean;
+    };
     const peekOperationPromise = async (): Promise<ServiceBusReceivedMessage[]> => {
-      if (options.fromSequenceNumber !== undefined) {
+      if (fromSequenceNumber !== undefined) {
         return this._context
           .getManagementClient(this.entityPath)
           .peekBySequenceNumber(
-            options.fromSequenceNumber,
+            fromSequenceNumber,
             maxMessageCount,
             undefined,
-            options.omitMessageBody,
+            omitMessageBody,
             managementRequestOptions,
           );
       } else {
         return this._context
           .getManagementClient(this.entityPath)
-          .peek(maxMessageCount, options.omitMessageBody, managementRequestOptions);
+          .peek(maxMessageCount, omitMessageBody, managementRequestOptions);
       }
     };
 

sdk/servicebus/service-bus/src/receivers/sessionReceiver.ts

@@ -337,15 +337,19 @@ export class ServiceBusSessionReceiverImpl implements ServiceBusSessionReceiver
       skipParsingBodyAsJson: this._skipParsingBodyAsJson,
       skipConvertingDate: this._skipConvertingDate,
     };
+    // omitMessageBody is available at runtime, but only exported in experimental subpath
+    const { fromSequenceNumber, omitMessageBody } = options as PeekMessagesOptions & {
+      omitMessageBody: boolean;
+    };
     const peekOperationPromise = async (): Promise<ServiceBusReceivedMessage[]> => {
-      if (options.fromSequenceNumber !== undefined) {
+      if (fromSequenceNumber !== undefined) {
         return this._context
           .getManagementClient(this.entityPath)
           .peekBySequenceNumber(
-            options.fromSequenceNumber,
+            fromSequenceNumber,
             maxMessageCount,
             this.sessionId,
-            options.omitMessageBody,
+            omitMessageBody,
             managementRequestOptions,
           );
       } else {
@@ -354,7 +358,7 @@ export class ServiceBusSessionReceiverImpl implements ServiceBusSessionReceiver
           .peekMessagesBySession(
             this.sessionId,
             maxMessageCount,
-            options.omitMessageBody,
+            omitMessageBody,
             managementRequestOptions,
           );
       }

sdk/servicebus/service-bus/test/public/peekMessagesOptions.spec.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { ServiceBusReceiver, ServiceBusSender } from "../../src/index.js";
+import {
+  createServiceBusClientForTests,
+  EntityName,
+  ServiceBusClientForTests,
+} from "./utils/testutils2.js";
+import { TestClientType, TestMessage } from "./utils/testUtils.js";
+import { expect } from "./utils/chai.js";
+import { afterAll, afterEach, beforeAll, describe, it } from "vitest";
+
+let serviceBusClient: ServiceBusClientForTests;
+let entityNames: EntityName;
+let sender: ServiceBusSender;
+let receiveAndDeleteReceiver: ServiceBusReceiver;
+
+async function beforeEachTest(entityType: TestClientType): Promise<void> {
+  entityNames = await serviceBusClient.test.createTestEntities(entityType);
+  receiveAndDeleteReceiver =
+    await serviceBusClient.test.createReceiveAndDeleteReceiver(entityNames);
+
+  sender = serviceBusClient.test.addToCleanup(
+    serviceBusClient.createSender(entityNames.queue ?? entityNames.topic!),
+  );
+}
+
+function afterEachTest(): Promise<void> {
+  return serviceBusClient.test.afterEach();
+}
+describe("PeekMessagesOptions.omitMessageBody", () => {
+  beforeAll(() => {
+    serviceBusClient = createServiceBusClientForTests();
+  });
+
+  afterAll(() => {
+    return serviceBusClient.test.after();
+  });
+
+  afterEach(async () => {
+    await afterEachTest();
+  });
+
+  [
+    TestClientType.UnpartitionedQueue,
+    TestClientType.UnpartitionedSubscription,
+    // Service issue feature doesn't work for PartitionedQueue and PartitionedSubscription
+    // TestClientType.PartitionedQueue,
+    // TestClientType.PartitionedSubscription,
+    TestClientType.UnpartitionedQueueWithSessions,
+    TestClientType.UnpartitionedSubscriptionWithSessions,
+    TestClientType.PartitionedQueueWithSessions,
+    TestClientType.PartitionedSubscriptionWithSessions,
+  ].forEach((testType) => {
+    it(testType + ": peek messages", async () => {
+      await beforeEachTest(testType);
+      const testMessages = entityNames.usesSessions
+        ? TestMessage.getSessionSample()
+        : TestMessage.getSample();
+      await sender.sendMessages(testMessages);
+
+      const peeked = await receiveAndDeleteReceiver.peekMessages(1, {
+        omitMessageBody: true,
+      });
+
+      expect(peeked.length).to.equal(1);
+      expect(peeked[0].body).toBeUndefined();
+
+      const received = await receiveAndDeleteReceiver.receiveMessages(1);
+      expect(received.length).toBe(1);
+    });
+  });
+});