docs: add typings, plus new documentation, on the on() methods of Subscriber (#1225)

feywind · web-flow · commit 77be4b34c457 · 2021-03-19T14:11:26.000-04:00
* docs: add optional typings, plus new documentation, on the on() methods of Subscriber

* build: i'm not sure why it keeps wanting to shift these lines around, but sure

* docs: update typings to be a bit more specific again, and fix a system-test that was broken by it

* fix: deactive typings for Subscription.on() for now, and revert typing change to the listener event handler
diff --git a/samples/package.json b/samples/package.json
@@ -14,9 +14,9 @@
     "test": "mocha system-test --timeout 600000"
   },
   "dependencies": {
+    "@google-cloud/pubsub": "^2.10.0",
     "@opentelemetry/api": "^0.11.0",
-    "@opentelemetry/tracing": "^0.11.0",
-    "@google-cloud/pubsub": "^2.10.0"
+    "@opentelemetry/tracing": "^0.11.0"
   },
   "devDependencies": {
     "chai": "^4.2.0",
diff --git a/src/subscription.ts b/src/subscription.ts
@@ -88,6 +88,32 @@ export type SetSubscriptionMetadataResponse = MetadataResponse;
 export type DetachSubscriptionCallback = EmptyCallback;
 export type DetachSubscriptionResponse = EmptyResponse;
 
+// JSDoc won't see these, so this is just to let you get typings
+// in your editor of choice.
+//
+// NOTE: These are commented out for now because we don't want to
+// break any existing clients that rely on not-entirely-correct
+// typings. We'll re-enable on the next major.
+/* export declare interface Subscription {
+  on(
+    event: 'message',
+    listener: (message: Message) => void
+  ): this;
+  on(
+    event: 'error',
+    listener: (error: StatusError) => void
+  ): this;
+  on(event: 'close', listener: () => void): this;
+
+  // Only used internally.
+  on(event: 'newListener', listener: Function): this;
+  on(event: 'removeListener', listener: Function): this;
+
+  // Catch-all. If you get an error about this line, it means you're
+  // using an unsupported event type or listener type.
+  on(event: string, listener: void): this;
+} */
+
 /**
  * @typedef {object} ExpirationPolicy
  * A policy that specifies the conditions for this subscription's expiration. A
@@ -120,7 +146,16 @@ export type DetachSubscriptionResponse = EmptyResponse;
  * All Subscription objects are instances of an
  * [EventEmitter](http://nodejs.org/api/events.html). The subscription will pull
  * for messages automatically as long as there is at least one listener assigned
- * for the `message` event.
+ * for the `message` event. Available events:
+ *
+ * Upon receipt of a message:
+ * on(event: 'message', listener: (message: {@link Message}) => void): this;
+ *
+ * Upon receipt of an error:
+ * on(event: 'error', listener: (error: Error) => void): this;
+ *
+ * Upon the closing of the subscriber:
+ * on(event: 'close', listener: Function): this;
  *
  * By default Subscription objects allow you to process 100 messages at the same
  * time. You can fine tune this value by adjusting the
diff --git a/system-test/pubsub.ts b/system-test/pubsub.ts
@@ -904,12 +904,12 @@ describe('pubsub', () => {
 
       // This creates a Promise that hooks the 'message' callback of the
       // subscription above, and resolves when that callback calls `resolve`.
-      type WorkCallback<T> = (arg: T, resolve: Function) => void;
+      type WorkCallback = (arg: Message, resolve: Function) => void;
       function makeMessagePromise<T>(
-        workCallback: WorkCallback<T>
+        workCallback: WorkCallback
       ): Promise<void> {
         return new Promise(resolve => {
-          subscription.on('message', (arg: T) => {
+          subscription.on('message', (arg: Message) => {
             workCallback(arg, resolve);
           });
         });
